MCP Learning Server

A comprehensive educational Model Context Protocol (MCP) server built with JavaScript that demonstrates all three main MCP capabilities: Tools, Resources, and Prompts.

🎯 What is MCP?

Model Context Protocol (MCP) is a protocol that allows AI assistants to connect to external data sources and tools. It provides three main capabilities:

1. 🔧 Tools

Functions that the AI can call to perform actions:

• API calls
• Calculations
• Data manipulation
• External system interactions

2. 📚 Resources

Data sources that the AI can read from:

• Files and documents
• Database content
• Web pages
• System information

3. 📝 Prompts

Template prompts with variables:

• Reusable prompt templates
• Customizable with parameters
• Consistent AI interactions

🚀 Getting Started

Prerequisites

• Node.js 18+
• Yarn package manager

Installation

# Clone or create the project
yarn install

# Run the server
yarn start

# Or run in development mode with auto-reload
yarn dev

🛠️ Features Demonstrated

Tools Available:

• calculate - Perform mathematical calculations
• get_weather - Get weather information (mock data)
• generate_uuid - Generate unique identifiers

Resources Available:

• file://project-info - Information about this project
• file://sample-data - Sample JSON data
• file://system-status - System status and statistics

Prompts Available:

• code-review - Generate code reviews
• explain-concept - Explain technical concepts
• project-documentation - Generate project documentation

📖 Step-by-Step Learning Guide

Step 1: Understanding the Basic Structure

The MCP server is built using the @modelcontextprotocol/sdk package:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

Step 2: Server Initialization

const server = new Server(
  {
    name: 'learning-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},      // Enable tools
      resources: {},  // Enable resources
      prompts: {},    // Enable prompts
    },
  }
);

Step 3: Implementing Tools

Tools are functions the AI can call. Each tool needs:

• A name and description
• An input schema (JSON Schema)
• A handler function

// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'calculate',
        description: 'Perform basic mathematical calculations',
        inputSchema: {
          type: 'object',
          properties: {
            expression: {
              type: 'string',
              description: 'Mathematical expression to evaluate',
            },
          },
          required: ['expression'],
        },
      },
    ],
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Execute the tool based on name and arguments
});

Step 4: Implementing Resources

Resources provide data that the AI can read:

// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: 'file://project-info',
        name: 'Project Information',
        description: 'Information about this MCP server project',
        mimeType: 'text/plain',
      },
    ],
  };
});

// Handle resource reading
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  const { uri } = request.params;
  // Return resource content based on URI
});

Step 5: Implementing Prompts

Prompts are reusable templates with variables:

// List available prompts
server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: [
      {
        name: 'code-review',
        description: 'Generate a code review',
        arguments: [
          {
            name: 'code',
            description: 'The code to review',
            required: true,
          },
        ],
      },
    ],
  };
});

// Handle prompt requests
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Return formatted prompt with variables filled in
});

🧪 Testing Your Server

Manual Testing

You can test the server by running it and sending MCP protocol messages via stdin/stdout:

yarn start

Using with MCP Clients

MCP servers typically run as stdio processes that communicate with AI assistants or other MCP clients through JSON-RPC messages.

🔍 Key Learning Points

1. Protocol Structure: MCP uses JSON-RPC 2.0 over stdio
2. Capability Declaration: Servers declare what they can do (tools, resources, prompts)
3. Schema Validation: All inputs use JSON Schema for validation
4. Error Handling: Proper error codes and messages are crucial
5. Transport Layer: StdioServerTransport handles communication

🛡️ Error Handling

The server includes comprehensive error handling:

import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

// Throw MCP-specific errors
throw new McpError(
  ErrorCode.InvalidRequest,
  `Unknown resource: ${uri}`
);

📚 Next Steps

1. Extend Tools: Add more sophisticated tools that call real APIs
2. Dynamic Resources: Connect to databases or file systems
3. Advanced Prompts: Create more complex prompt templates
4. Authentication: Add security for production use
5. Logging: Implement comprehensive logging
6. Testing: Add unit and integration tests

🔗 Resources

• MCP Official Documentation
• MCP SDK Documentation
• JSON Schema Documentation
• JSON-RPC 2.0 Specification

📄 License

MIT License - feel free to use this code for learning and building your own MCP servers!