Submit
vishutorvi

MCP Learning Project - Complete Guide

Community vishutorvi
Updated

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

# 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

{
  "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:

{
  "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

# 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:

    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:

// 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:

// 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:

    {
  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:

    {
  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:

    {
  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:

    {
  uri: 'config://app-settings',
  name: 'Application Settings',
  description: 'Current application configuration',
  mimeType: 'application/json'
}

  2. Documentation Resource:

    {
  uri: 'docs://api-reference',
  name: 'API Reference',
  description: 'Complete API documentation',
  mimeType: 'text/markdown'
}

Create Interactive Prompts:

  1. Code Review Prompt: 
    {
  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:

    # 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:

    # 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:

    // 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:

// 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:

// 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:

// 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:

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:

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:

Community Examples:

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! 🚀

MCP Server · Populars

MCP Server · New