revhawk/MCP-server-training-typescript

MCP Server Implementation in TypeScript

This is a TypeScript implementation of a Model Context Protocol (MCP) server. The server provides a set of tools for interacting with a database and performing web searches.

Features

• MCP protocol implementation
• SQLite database integration
• Web search capabilities
• RESTful API endpoints
• Interactive API documentation with Swagger UI
• CORS support
• Session management
• Server-Sent Events (SSE) for real-time updates

Prerequisites

• Node.js (v14 or higher)
• npm (v6 or higher)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/mcp-typescript-workshop.git
cd mcp-typescript-workshop

2. Install dependencies:

npm install

3. Build the project:

npm run build

Running the Server

Development Mode

npm run dev

Production Mode

npm start

The server will start on port 3000 by default. You can access:

• API Documentation: http://localhost:3000/api-docs
• MCP Endpoint: http://localhost:3000/mcp

Testing the Server

You can test the server using curl commands. Here's a complete sequence to test all functionality:

1. Initialize a new session:

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

This will return a session ID that you'll need for subsequent requests.

2. List available tools:

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"list_tools","params":{},"id":2}'

3. Get all employees:

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"get_employees","arguments":{}},"id":3}'

4. Search employees by department:

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"search_employees","arguments":{"department":"Engineering"}},"id":4}'

5. Perform a web search:

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"web_search","arguments":{"query":"Model Context Protocol"}},"id":5}'

6. Terminate the session:

curl -v -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: YOUR_SESSION_ID"

Note: Replace YOUR_SESSION_ID with the session ID received from the initialize request.

Expected Responses

1. Initialize response:

{
  "jsonrpc": "2.0",
  "result": {
    "sessionId": "e6c389d7-e90a-4d09-a916-47bc5edd365e",
    "serverInfo": {
      "name": "workshop-typescript-server",
      "version": "1.0.0"
    }
  },
  "id": 1
}

2. Get employees response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Employees:\nID: 1, Name: Alice Johnson, Department: Engineering, Salary: $85000\nID: 2, Name: Bob Smith, Department: Marketing, Salary: $62000\nID: 3, Name: Carol Davis, Department: Engineering, Salary: $92000\nID: 4, Name: David Wilson, Department: Sales, Salary: $58000\n"
    }]
  },
  "id": 3
}

API Documentation

The API documentation is available at http://localhost:3000/api-docs when the server is running. The documentation includes:

• All available endpoints
• Request/response schemas
• Interactive testing interface
• Example requests and responses

Available Endpoints

POST /mcp

Main endpoint for MCP communication. Handles:

• Session initialization
• Tool listing
• Tool execution

GET /mcp

Server-Sent Events (SSE) endpoint for real-time updates.

DELETE /mcp

Endpoint for terminating an MCP session.

Available Tools

1. get_employees

   • Description: Get all employees from the database
   • No input parameters required

2. web_search

   • Description: Search the web for information
   • Input parameters:
     • query (string): Search query

3. search_employees

   • Description: Search employees by department or name
   • Input parameters:
     • department (string, optional): Department to search in
     • name (string, optional): Name to search for

Session Management

The server uses session IDs to maintain state between requests. The session ID is:

• Generated during initialization
• Required in the mcp-session-id header for subsequent requests
• Automatically cleaned up when the session is terminated

Error Handling

The server provides detailed error responses in the following format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description"
  },
  "id": null
}

Development

Project Structure

src/
  ├── server.ts      # Main server implementation
  ├── swagger.ts     # API documentation configuration
  └── types/         # TypeScript type definitions

Building

npm run build

Testing

npm test

License

This project is licensed under the ISC License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request