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.
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 calculationsget_weather
- Get weather information (mock data)generate_uuid
- Generate unique identifiers
Resources Available:
file://project-info
- Information about this projectfile://sample-data
- Sample JSON datafile://system-status
- System status and statistics
Prompts Available:
code-review
- Generate code reviewsexplain-concept
- Explain technical conceptsproject-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
- Protocol Structure: MCP uses JSON-RPC 2.0 over stdio
- Capability Declaration: Servers declare what they can do (tools, resources, prompts)
- Schema Validation: All inputs use JSON Schema for validation
- Error Handling: Proper error codes and messages are crucial
- 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
- Extend Tools: Add more sophisticated tools that call real APIs
- Dynamic Resources: Connect to databases or file systems
- Advanced Prompts: Create more complex prompt templates
- Authentication: Add security for production use
- Logging: Implement comprehensive logging
- 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!