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