Example MCP Server

A simple Model Context Protocol (MCP) server implementation in Node.js with TypeScript for use with Claude Desktop.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI models like Claude to interact with external tools and data sources. It allows Claude Desktop to call local or remote tools, retrieve information, and perform actions through standardized JSON-RPC messaging.

This server exposes tools that Claude can discover and invoke over a stdio (standard input/output) transport, making it perfect for local integrations.

Project Structure

Features

• ✅ MCP-compliant JSON-RPC 2.0 server

• ✅ Stdio transport (works with Claude Desktop local tools)

• ✅ Two sample tools: ping and system_info

• ✅ Extensible tool registry system

• ✅ Proper error handling and validation

• ✅ TypeScript for type safety

Prerequisites

• Node.js 16+ (or compatible version)

• npm or yarn

Getting Started

1. Install Dependencies

2. Build TypeScript to JavaScript

This compiles TypeScript from src/ to JavaScript in dist/.

3. Run the MCP Server

The server will start and listen for JSON-RPC requests on stdin.

Available Tools

ping

A simple test tool that returns "pong".

Request:

Response:

system_info

Returns detailed system information including OS, architecture, CPU count, memory usage, and uptime.

Request:

Response:

MCP Protocol Methods

tools/list

Lists all available tools.

Request:

Response:

tools/call

Calls a specific tool with optional arguments.

Request:

Response:

Registering with Claude Desktop

To use this MCP server with Claude Desktop:

1. Build the project:

   npm run build

2. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

3. Add the server to your claude_desktop_config.json:

   { "mcpServers": { "example-mcp-server": { "command": "node", "args": ["/absolute/path/to/dist/mcp/server.js"], "env": {} } } }

   Replace /absolute/path/to with the full path to your project folder.

4. Restart Claude Desktop to load the new MCP server.

5. Claude will now be able to discover and call the tools provided by this server.

Adding New Tools

To add a new tool:

1. Create a new tool file in src/tools/ (e.g., src/tools/my-tool.ts):

   import { Tool, ToolResult, ToolHandler } from "../types/index.js"; export const myTool: Tool = { name: "my_tool", description: "Description of what the tool does", inputSchema: { type: "object", properties: { param1: { type: "string" }, }, required: ["param1"], }, }; export const myToolHandler: ToolHandler = async (args) => { // Implementation return { content: [{ type: "text", text: "Result" }], }; };

2. Register it in src/tools/registry.ts:

   import { myTool, myToolHandler } from "./my-tool.js"; const toolRegistry: Map<string, ToolEntry> = new Map([ // ... existing tools ["my_tool", { definition: myTool, handler: myToolHandler }], ]);

3. Rebuild and restart the server:

   npm run build npm start

Development

For development with auto-reload, you can use ts-node:

This will run the TypeScript directly without compilation (requires ts-node to be installed).

Error Handling

The server implements proper JSON-RPC 2.0 error handling:

• -32700: Parse error

• -32600: Invalid request

• -32601: Method not found

• -32603: Internal error

All errors are returned with descriptive messages to help with debugging.

Architecture

MCP Server (src/mcp/server.ts)

• Reads JSON-RPC 2.0 messages from stdin

• Routes requests to appropriate handlers

• Validates incoming requests

• Writes responses to stdout

• Handles errors gracefully

Tool Registry (src/tools/registry.ts)

• Central registry of available tools

• Provides tool list for discovery

• Dispatches tool calls to appropriate handlers

Tool Handlers

Each tool has:

• A Tool definition (name, description, input schema)

• A ToolHandler function (async execution logic)

Troubleshooting

Server not starting

• Ensure Node.js is installed: node --version

• Check that dependencies are installed: npm install

• Build the project: npm run build

Tools not visible in Claude

• Verify the full path in claude_desktop_config.json is correct

• Restart Claude Desktop after configuration changes

• Check server logs for errors

Connection issues

• Ensure the server process stays running

• Check file permissions on the compiled files

• Verify stdin/stdout are not being intercepted

License

MIT

References

• Model Context Protocol Specification

• Claude Desktop Documentation

• JSON-RPC 2.0 Specification