JUHE API Marketplace
thanhtn2902 avatar
MCP Server

MCP Learning Server

A comprehensive educational server demonstrating Model Context Protocol capabilities for tools, resources, and prompts, allowing AI assistants to connect to external data and functionality.

0
GitHub Stars
8/23/2025
Last Updated
No Configuration
Please check the documentation below.

README Documentation

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

📄 License

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

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source