README.md•15.6 kB
# 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! 🚀**