User Info MCP Server

🚀 Gelişmiş Model Context Protocol (MCP) Server - Context7 Best Practices ile geliştirilmiş kullanıcı yönetim sistemi.

Bu proje, modern layered architecture pattern kullanarak kullanıcı bilgilerini JSON dosyasından sağlayan profesyonel bir MCP server'dır. Context7 MCP best practices ve clean architecture prensipleri uygulanarak geliştirilmiştir.

🏗️ Proje Mimarisi

McpProjectScaffold/
├── src/
│   ├── server.ts                   # 🎯 Ana MCP server (Entry Point)
│   ├── controllers/
│   │   └── user.controller.ts      # 🎮 Tool handlers (MCP Interface Layer)
│   ├── services/
│   │   └── user.service.ts         # 🧠 Business logic & validation
│   ├── repositories/
│   │   └── user.repository.ts      # 💾 Data access layer (JSON operations)
│   ├── tools/
│   │   ├── index.ts               # 🔧 Tool registration orchestrator
│   │   └── user-tools.ts          # 📋 MCP tool definitions
│   └── types/
│       └── user.ts                # 📝 TypeScript interfaces & Zod schemas
├── data/
│   └── users.json                 # 💿 JSON veri dosyası
├── package.json                   # 📦 Proje bağımlılıkları
├── tsconfig.json                  # ⚙️ TypeScript konfigürasyonu
└── README.md                      # 📖 Bu dosya

🎨 Architecture Pattern: Layered Architecture (Context7 Pattern)

Separation of Concerns prensipleri:

• Controllers → MCP tool handlers & response formatting
• Services → Business logic, validation & error handling
• Repositories → Pure data access (JSON file operations)
• Tools → MCP tool registration & schema definitions
• Types → TypeScript interfaces & Zod validation schemas

✨ Özellikler

MCP server 6 gelişmiş tool sağlar:

1. get_all_users → Tüm kullanıcıların listesini getirir
2. get_user_by_id → ID'ye göre belirli kullanıcıyı getirir
3. search_users_by_name → İsme göre kullanıcı arar (partial match)
4. search_users_by_email → E-posta adresine göre kullanıcı arar
5. search_users_by_phone → Telefon numarasına göre kullanıcı arar
6. add_user → Yeni kullanıcı ekler (validation + duplicate control)

🔍 User Veri Yapısı

interface User {
  id: number;        // Benzersiz kullanıcı kimliği (auto-increment)
  name: string;      // Kullanıcının tam adı (2-100 karakter)
  email: string;     // E-posta adresi (unique, email format)
  phone: string;     // Telefon numarası (10-20 karakter)
}

📦 Kurulum & Setup

1. Bağımlılıkları Yükleyin

npm install

2. TypeScript Build

npm run server:build

3. Development Mode

npm run server:dev

4. MCP Inspector ile Test

npm run server:inspect

🛠️ Teknoloji Stack

Core Technologies

• Node.js (v18+) → JavaScript runtime
• TypeScript (v5.8+) → Type-safe development
• ES Modules → Modern module system
• MCP TypeScript SDK → Protocol implementation

Development & Quality Tools

• Zod (v3.25+) → Runtime schema validation
• tsx → TypeScript execution
• MCP Inspector → Interactive tool testing
• Strict TypeScript → Maximum type safety

Architecture Patterns

• Context7 MCP Best Practices → Industry standards
• Layered Architecture → Clean separation of concerns
• Repository Pattern → Data access abstraction
• Service Layer Pattern → Business logic encapsulation

🚀 Kullanım

Development Scripts

# Development mode (hot reload)
npm run server:dev

# TypeScript build
npm run server:build

# Watch mode build
npm run server:build:watch

# MCP Inspector (interactive testing)
npm run server:inspect

MCP Inspector Kullanımı

npm run server:inspect

Bu komut MCP Inspector web arayüzünü açar ve tool'ları interaktif olarak test etmenizi sağlar. Tarayıcıda http://localhost:3000 adresinde açılır.

🔧 MCP Tool Kullanım Örnekleri

1. Tüm Kullanıcıları Getir

{
  "method": "tools/call",
  "params": {
    "name": "get_all_users",
    "arguments": {}
  }
}

2. ID'ye Göre Kullanıcı Getir

{
  "method": "tools/call",
  "params": {
    "name": "get_user_by_id",
    "arguments": {
      "id": 1
    }
  }
}

3. İsme Göre Kullanıcı Ara

{
  "method": "tools/call",
  "params": {
    "name": "search_users_by_name",
    "arguments": {
      "name": "Ahmet"
    }
  }
}

4. E-posta ile Kullanıcı Ara

{
  "method": "tools/call",
  "params": {
    "name": "search_users_by_email",
    "arguments": {
      "email": "ahmet.yilmaz@example.com"
    }
  }
}

5. Telefon ile Kullanıcı Ara

{
  "method": "tools/call",
  "params": {
    "name": "search_users_by_phone",
    "arguments": {
      "phone": "+90 532 123 4567"
    }
  }
}

6. Yeni Kullanıcı Ekle

{
  "method": "tools/call",
  "params": {
    "name": "add_user",
    "arguments": {
      "name": "Zeynep Kılıç",
      "email": "zeynep.kilic@example.com",
      "phone": "+90 537 555 1234"
    }
  }
}

📁 Veri Dosyası Düzenleme

data/users.json dosyasını düzenleyerek kullanıcı verilerini manuel olarak değiştirebilirsiniz:

[
  {
    "id": 1,
    "name": "Ahmet Yılmaz",
    "email": "ahmet.yilmaz@example.com",
    "phone": "+90 532 123 4567"
  },
  {
    "id": 2,
    "name": "Ayşe Demir", 
    "email": "ayse.demir@example.com",
    "phone": "+90 533 987 6543"
  }
]

⚠️ Not: JSON formatını bozmamaya dikkat edin. Yeni kullanıcılar için add_user tool'unu kullanmak daha güvenlidir.

🔗 MCP Client Konfigürasyonu

Bu MCP server'ı çeşitli IDE'ler ve AI araçlarında kullanabilirsiniz:

Cursor IDE

{
  "mcpServers": {
    "user-info-server": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/McpProjectScaffold"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "user-info-server": {
      "command": "npm",
      "args": ["run", "server:dev"],
      "cwd": "/path/to/McpProjectScaffold"
    }
  }
}

VS Code (MCP Extension)

{
  "mcp": {
    "servers": {
      "user-info-server": {
        "type": "stdio",
        "command": "npm",
        "args": ["run", "server:dev"],
        "cwd": "/path/to/McpProjectScaffold"
      }
    }
  }
}

🔒 Güvenlik & Validasyon

Zod ile Type-Safe Validasyon

• Schema-based validasyon → Tüm input'lar Zod schema'ları ile doğrulanır
• Runtime type checking → TypeScript + Zod ile çifte güvenlik
• Otomatik validasyon mesajları → Zod'un built-in error handling
• E-posta format kontrolü → z.string().email() ile format doğrulama
• String uzunluk kontrolü → z.string().min(2).max(100) ile range validation
• Sayı validasyonu → z.number().int().positive() ile integer kontrolü
• Duplicate e-posta kontrolü → Repository layer'da unique email kontrolü
• Required field validasyonu → Zod schema ile zorunlu alan kontrolü

Zod Schema Örnekleri

// User entity schema
export const UserSchema = z.object({
  id: z.number().int().positive().describe("Benzersiz kullanıcı kimliği"),
  name: z.string().min(2).max(100).describe("Kullanıcının tam adı"),
  email: z.string().email().describe("E-posta adresi"),
  phone: z.string().min(10).max(20).describe("Telefon numarası")
});

// Add user input schema
export const AddUserInputSchema = {
  name: z.string().min(2).max(100).describe("Kullanıcının tam adı"),
  email: z.string().email().describe("E-posta adresi"),
  phone: z.string().min(10).max(20).describe("Telefon numarası")
};

🏗️ Geliştirme Notları

Context7 MCP Best Practices ✅

• Modular architecture → Layered separation of concerns
• Tool registration → Clean tool definition & registration
• Error handling → Comprehensive error management
• Type safety → Full TypeScript + Zod validation
• Input schemas → Context7 compatible schema definitions
• Clean responses → Standardized MCP response format

Technical Features

• ES Modules → Modern JavaScript module system
• Strict TypeScript → Maximum type safety
• Auto-increment IDs → Automatic ID generation
• Duplicate prevention → Email uniqueness checks
• Business validation → Service layer business rules
• Repository pattern → Data access abstraction
• CRUD operations → Full Create, Read, Update capabilities

Code Quality

• Separation of concerns → Each layer has single responsibility
• Error boundaries → Proper error catching & handling
• Validation layers → Multiple validation levels
• Clean code → Readable, maintainable codebase
• Type inference → Zod to TypeScript type generation

📚 MCP Protocol Hakkında

Model Context Protocol (MCP), AI asistanlarına structured veri ve tool sağlamak için tasarlanmış modern bir protokoldür.

MCP'nin Avantajları:

• Standardized communication → AI araçları arası standart iletişim
• Tool-based architecture → Modular fonksiyonellik
• Real-time data access → Canlı veri erişimi
• Type-safe operations → Güvenli operasyonlar
• Cross-platform compatibility → Platform bağımsızlık

Bu proje, Context7 MCP best practices kullanarak profesyonel MCP server geliştirme konusunda pratik yapmak için tasarlanmıştır.

---

🤝 Katkıda Bulunma

1. Fork yapın
2. Feature branch oluşturun (git checkout -b feature/AmazingFeature)
3. Değişikliklerinizi commit edin (git commit -m 'Add some AmazingFeature')
4. Branch'e push yapın (git push origin feature/AmazingFeature)
5. Pull Request açın

📝 Lisans

Bu proje MIT lisansı altında lisanslanmıştır.

---

🚀 Happy Coding! - Context7 MCP Best Practices ile geliştirilmiştir.