README.md•10.2 kB
# 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ı
```typescript
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
```bash
npm install
```
### 2. TypeScript Build
```bash
npm run server:build
```
### 3. Development Mode
```bash
npm run server:dev
```
### 4. MCP Inspector ile Test
```bash
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
```bash
# 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ı
```bash
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
```json
{
"method": "tools/call",
"params": {
"name": "get_all_users",
"arguments": {}
}
}
```
### 2. ID'ye Göre Kullanıcı Getir
```json
{
"method": "tools/call",
"params": {
"name": "get_user_by_id",
"arguments": {
"id": 1
}
}
}
```
### 3. İsme Göre Kullanıcı Ara
```json
{
"method": "tools/call",
"params": {
"name": "search_users_by_name",
"arguments": {
"name": "Ahmet"
}
}
}
```
### 4. E-posta ile Kullanıcı Ara
```json
{
"method": "tools/call",
"params": {
"name": "search_users_by_email",
"arguments": {
"email": "ahmet.yilmaz@example.com"
}
}
}
```
### 5. Telefon ile Kullanıcı Ara
```json
{
"method": "tools/call",
"params": {
"name": "search_users_by_phone",
"arguments": {
"phone": "+90 532 123 4567"
}
}
}
```
### 6. Yeni Kullanıcı Ekle
```json
{
"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:
```json
[
{
"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
```json
{
"mcpServers": {
"user-info-server": {
"command": "node",
"args": ["dist/server.js"],
"cwd": "/path/to/McpProjectScaffold"
}
}
}
```
### Claude Desktop
```json
{
"mcpServers": {
"user-info-server": {
"command": "npm",
"args": ["run", "server:dev"],
"cwd": "/path/to/McpProjectScaffold"
}
}
}
```
### VS Code (MCP Extension)
```json
{
"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
```typescript
// 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.