Skip to main content
Glama
User Info MCP Server

User Info MCP Server

by huseyindol

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

Related MCP server: Enterprise Data MCP Server

✨ Ö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.

Available Tools

6 tools
add_userKullanıcı EkleC

Yeni kullanıcı ekle

Inputs: name (required), email (required), phone (required).

get_all_usersTüm Kullanıcıları GetirB

Tüm kullanıcıların listesini getir

Inputs: no named parameters.

get_user_by_idKullanıcı GetirC

ID'ye göre belirli bir kullanıcıyı getir

Inputs: id (required).

search_users_by_emailKullanıcı AraC

E-posta adresine göre kullanıcı ara

Inputs: email (required).

search_users_by_nameKullanıcı AraC

İsme göre kullanıcı ara

Inputs: name (required).

search_users_by_phoneKullanıcı AraC

Telefon numarasına göre kullanıcı ara

Inputs: phone (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: add_user creates a new user, get_all_users retrieves all users, get_user_by_id fetches a specific user by ID, and the three search tools each target different attributes (email, name, phone). There is no overlap or ambiguity in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., add_user, get_all_users, search_users_by_email). The naming is predictable and readable throughout the set.

    Tool Count5/5

    With 6 tools, this server is well-scoped for user information management. The count is appropriate, covering core operations (create, retrieve, search) without being excessive or insufficient for the domain.

    Completeness4/5

    The tool set covers key user operations: creation (add_user), retrieval (get_all_users, get_user_by_id), and search (by email, name, phone). Minor gaps exist, such as missing update and delete operations, which agents might need to work around, but core workflows are largely supported.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides tools to query and interact with MongoDB user collections, supporting filtering, sorting, and retrieval operations.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing natural-language tools for managing and querying an employee database, including user CRUD, search, and statistics.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A simple Model Context Protocol (MCP) server that allows LLMs to create and manage user entries in a JSON file system database.
      2,530 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A user management MCP server that enables CRUD operations on users stored in a JSON file, with random user generation using Faker.
      13 npm
      1
      ISC