README.md•6.23 kB
# 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
```bash
# 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:
```javascript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
```
### Step 2: Server Initialization
```javascript
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
```javascript
// 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:
```javascript
// 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:
```javascript
// 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:
```bash
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:
```javascript
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](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [JSON Schema Documentation](https://json-schema.org/)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
## 📄 License
MIT License - feel free to use this code for learning and building your own MCP servers!