# MCP Learning Project - Complete Guide

This is a comprehensive tutorial project that teaches Model Context Protocol (MCP) development from beginner to advanced levels. You'll learn both **server-side** (backend) and **client-side** (frontend) development.

## 🎯 What You'll Learn

### **Beginner Level:**
- ✅ Basic MCP server structure and concepts
- ✅ Simple tool creation and registration  
- ✅ Parameter handling and validation
- ✅ Basic client connection and tool calling

### **Intermediate Level:**
- ✅ State management between tool calls
- ✅ Resource management (serving data to AI)
- ✅ Data processing and complex operations
- ✅ Client-server communication patterns

### **Advanced Level:**
- ✅ CRUD operations with persistent state
- ✅ Comprehensive error handling
- ✅ Prompt templates for AI interactions
- ✅ Best practices and production considerations

## 📁 Project Structure

```
mcp-learning-project/
├── src/
│   ├── server.ts          # MCP Learning Server (backend)
│   └── client.ts          # MCP Learning Client (frontend)
├── dist/                  # Compiled JavaScript
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file
```

## 🚀 Quick Start

### 1. **Setup Project**

```bash
# Create project directory
mkdir mcp-learning-project
cd mcp-learning-project

# Initialize npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk

# Install dev dependencies
npm install --save-dev typescript @types/node tsx
```

### 2. **Create Package.json**

```json
{
  "name": "mcp-learning-project",
  "version": "1.0.0",
  "description": "Learn MCP development from beginner to advanced",
  "main": "dist/server.js",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start:server": "node dist/server.js",
    "start:client": "node dist/client.js dist/server.js",
    "dev:server": "tsx src/server.ts",
    "dev:client": "tsx src/client.ts dist/server.js",
    "demo": "npm run build && npm run start:client"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.4.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}
```

### 3. **Create TypeScript Config**

Create `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### 4. **Save the Code Files**

- Save the **MCP Learning Server** code as `src/server.ts`
- Save the **MCP Learning Client** code as `src/client.ts`

### 5. **Build and Run**

```bash
# Build the project
npm run build

# Run the interactive client (this will also start the server)
npm run demo
```

## 🎓 Learning Path

### **Phase 1: Understanding the Basics**

1. **Start the interactive client:**
   ```bash
   npm run demo
   ```

2. **Try basic commands:**
   ```
   mcp-learning> help
   mcp-learning> tools
   mcp-learning> call hello_world {"name": "Alice"}
   ```

3. **Learn about resources:**
   ```
   mcp-learning> resources
   mcp-learning> read mcp-concepts
   ```

### **Phase 2: Hands-on Practice**

1. **Run the beginner demo:**
   ```
   mcp-learning> demo beginner
   ```

2. **Practice tool calls:**
   ```
   mcp-learning> call calculator {"operation": "add", "a": 5, "b": 3}
   mcp-learning> call calculator {"operation": "divide", "a": 10, "b": 0}
   ```

3. **Understand state management:**
   ```
   mcp-learning> call counter {"action": "get"}
   mcp-learning> call counter {"action": "increment", "amount": 5}
   mcp-learning> call counter {"action": "get"}
   ```

### **Phase 3: Advanced Concepts**

1. **Run intermediate demo:**
   ```
   mcp-learning> demo intermediate
   ```

2. **Work with complex data:**
   ```
   mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "sort"}
   mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "average"}
   ```

3. **CRUD operations:**
   ```
   mcp-learning> call task_manager {"action": "create", "task": {"title": "Learn MCP", "priority": "high"}}
   mcp-learning> call task_manager {"action": "list"}
   ```

### **Phase 4: Production Ready**

1. **Run advanced demo:**
   ```
   mcp-learning> demo advanced
   ```

2. **Learn error handling:**
   ```
   mcp-learning> call error_demo {"error_type": "none"}
   mcp-learning> call error_demo {"error_type": "validation"}
   ```

3. **Study best practices:**
   ```
   mcp-learning> read best-practices
   ```

## 🔧 Key Concepts Explained

### **1. MCP Server (Backend)**

The server provides capabilities to AI models:

```typescript
// Server setup
const server = new Server({
  name: 'my-server',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {},      // Functions AI can call
    resources: {},  // Data AI can read  
    prompts: {}     // Templates AI can use
  }
});

// Tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'my_tool',
      description: 'What this tool does',
      inputSchema: { /* JSON Schema */ }
    }
  ]
}));

// Tool implementation
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Process the tool call and return results
  return {
    content: [{
      type: 'text',
      text: 'Tool response'
    }]
  };
});
```

### **2. MCP Client (Frontend)**

The client connects to servers and uses their capabilities:

```typescript
// Client setup
const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: { /* client capabilities */ }
});

// Connect to server
const transport = new StdioClientTransport(/* server process */);
await client.connect(transport);

// Discover server capabilities
const tools = await client.listTools();
const resources = await client.listResources();

// Use server tools
const result = await client.callTool({
  name: 'tool_name',
  arguments: { /* tool parameters */ }
});
```

### **3. Communication Flow**

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   AI Model  │ ───▶ │ MCP Client  │ ───▶ │ MCP Server  │
│             │      │ (Frontend)  │      │ (Backend)   │
│             │ ◀─── │             │ ◀─── │             │
└─────────────┘      └─────────────┘      └─────────────┘
     ▲                      │                      │
     │                      │                      │
     └──────────────────────┴──────────────────────┘
              Uses server capabilities
```

## 🧪 Experimentation Ideas

### **Create Your Own Tools:**

1. **Weather Tool:**
   ```typescript
   {
     name: 'weather',
     description: 'Get weather information',
     inputSchema: {
       type: 'object',
       properties: {
         city: { type: 'string', description: 'City name' },
         units: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
       },
       required: ['city']
     }
   }
   ```

2. **File System Tool:**
   ```typescript
   {
     name: 'file_operations',
     description: 'Basic file system operations',
     inputSchema: {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['list', 'read', 'write'] },
         path: { type: 'string', description: 'File or directory path' },
         content: { type: 'string', description: 'Content to write' }
       },
       required: ['action', 'path']
     }
   }
   ```

3. **Database Tool:**
   ```typescript
   {
     name: 'database',
     description: 'Simple in-memory database operations',
     inputSchema: {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['create', 'read', 'update', 'delete'] },
         table: { type: 'string', description: 'Table name' },
         data: { type: 'object', description: 'Data to store/update' },
         id: { type: 'string', description: 'Record ID' }
       },
       required: ['action', 'table']
     }
   }
   ```

### **Create Custom Resources:**

1. **Configuration Resource:**
   ```typescript
   {
     uri: 'config://app-settings',
     name: 'Application Settings',
     description: 'Current application configuration',
     mimeType: 'application/json'
   }
   ```

2. **Documentation Resource:**
   ```typescript
   {
     uri: 'docs://api-reference',
     name: 'API Reference',
     description: 'Complete API documentation',
     mimeType: 'text/markdown'
   }
   ```

### **Create Interactive Prompts:**

1. **Code Review Prompt:**
   ```typescript
   {
     name: 'code-review',
     description: 'Start a code review session',
     arguments: [
       {
         name: 'language',
         description: 'Programming language',
         required: true
       },
       {
         name: 'focus',
         description: 'Review focus (security, performance, style)',
         required: false
       }
     ]
   }
   ```

## 🐛 Debugging and Troubleshooting

### **Common Issues:**

1. **Server Won't Start:**
   ```bash
   # Check if TypeScript compiled correctly
   npm run build
   
   # Look for compilation errors
   npx tsc --noEmit
   
   # Check for missing dependencies
   npm install
   ```

2. **Client Can't Connect:**
   ```bash
   # Make sure server path is correct
   node dist/client.js dist/server.js
   
   # Check if server process starts
   node dist/server.js
   ```

3. **Tool Calls Fail:**
   ```typescript
   // Add debugging to your server
   console.error(`[DEBUG] Tool called: ${name}`, JSON.stringify(args));
   
   // Validate input parameters carefully
   if (typeof args.requiredParam === 'undefined') {
     throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter');
   }
   ```

### **Debug Mode:**

Enable verbose logging in both server and client:

```typescript
// In server
console.error('[SERVER]', 'Detailed log message');

// In client  
console.log('[CLIENT]', 'Connection status:', connected);
```

## 🚀 Next Steps: Building Production Servers

### **1. Add Real Functionality:**

Replace demo tools with actual useful functionality:

```typescript
// Example: Real file system access
private async handleFileOperations(args: any) {
  const { action, path, content } = args;
  
  switch (action) {
    case 'read':
      return {
        content: [{
          type: 'text',
          text: await fs.readFile(path, 'utf-8')
        }]
      };
    case 'write':
      await fs.writeFile(path, content);
      return {
        content: [{
          type: 'text', 
          text: `File written: ${path}`
        }]
      };
  }
}
```

### **2. Add External Integrations:**

```typescript
// Example: HTTP API integration
private async handleApiCall(args: any) {
  const { url, method, data } = args;
  
  const response = await fetch(url, {
    method,
    headers: { 'Content-Type': 'application/json' },
    body: data ? JSON.stringify(data) : undefined
  });
  
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        status: response.status,
        data: await response.json()
      }, null, 2)
    }]
  };
}
```

### **3. Add Persistence:**

```typescript
import * as fs from 'fs/promises';

class PersistentMCPServer {
  private dataFile = './mcp-data.json';
  
  async loadState(): Promise<Map<string, any>> {
    try {
      const data = await fs.readFile(this.dataFile, 'utf-8');
      return new Map(Object.entries(JSON.parse(data)));
    } catch {
      return new Map();
    }
  }
  
  async saveState(state: Map<string, any>): Promise<void> {
    const data = Object.fromEntries(state);
    await fs.writeFile(this.dataFile, JSON.stringify(data, null, 2));
  }
}
```

### **4. Add Authentication:**

```typescript
private validateAuth(headers: any): boolean {
  const token = headers['authorization'];
  return token === 'Bearer your-secret-token';
}

private async handleSecureTool(args: any, headers: any) {
  if (!this.validateAuth(headers)) {
    throw new McpError(ErrorCode.InvalidParams, 'Authentication required');
  }
  
  // Continue with tool logic...
}
```

## 📚 Additional Resources

### **Official Documentation:**
- [MCP Specification](https://modelcontextprotocol.io/specification)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)

### **Community Examples:**
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
- [Community Tools and Integrations](https://github.com/modelcontextprotocol/community)

### **Advanced Topics:**
- HTTP transport for web services
- WebSocket transport for real-time communication
- Custom transport implementations
- Performance optimization techniques
- Security best practices

## 🎯 Learning Exercises

### **Exercise 1: Extend the Calculator**
Add more operations: `power`, `sqrt`, `factorial`, `sin`, `cos`

### **Exercise 2: Build a Note-Taking System**
Create tools for creating, editing, searching, and organizing notes with tags.

### **Exercise 3: Add External API Integration**
Integrate with a real API (weather, news, stock prices) and create corresponding tools.

### **Exercise 4: Build a Project Manager**
Create a comprehensive project management system with tasks, deadlines, priorities, and progress tracking.

### **Exercise 5: Add Real-Time Features**
Implement tools that can send notifications or updates back to the client.

## 🏆 Mastery Checklist

### **Beginner Level ✅**
- [ ] Understand MCP architecture (client, server, transport)
- [ ] Create basic tools with input validation
- [ ] Handle simple tool calls and responses
- [ ] Read and understand error messages

### **Intermediate Level ✅**
- [ ] Implement stateful tools with persistence
- [ ] Create and serve resources to AI
- [ ] Handle complex data processing
- [ ] Implement proper error handling patterns

### **Advanced Level ✅**
- [ ] Build CRUD operations with complex state
- [ ] Create interactive prompt templates
- [ ] Implement production-ready error handling
- [ ] Understand security and authentication concepts
- [ ] Optimize performance for production use

### **Expert Level 🚀**
- [ ] Build custom transport layers
- [ ] Create MCP server frameworks
- [ ] Implement advanced security measures
- [ ] Build distributed MCP architectures
- [ ] Contribute to the MCP ecosystem

---

## 🎉 Congratulations!

You now have a complete understanding of MCP development from both frontend and backend perspectives. You can:

- **Build MCP servers** that provide tools, resources, and prompts
- **Create MCP clients** that interact with servers effectively
- **Handle errors gracefully** and implement proper validation
- **Manage state** between tool calls and across sessions
- **Follow best practices** for production-ready implementations

The interactive learning environment in this project gives you hands-on experience with all MCP concepts. Use this as a foundation to build your own specialized MCP servers for any domain or use case!

**Happy coding! 🚀**