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:

get_all_users → Tüm kullanıcıların listesini getirir
get_user_by_id → ID'ye göre belirli kullanıcıyı getirir
search_users_by_name → İsme göre kullanıcı arar (partial match)
search_users_by_email → E-posta adresine göre kullanıcı arar
search_users_by_phone → Telefon numarasına göre kullanıcı arar
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

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

📝 Lisans

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

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