MCP 服务器

My MCP Server

An extensible TypeScript-based MCP server designed for Claude Code with a modular architecture for easily adding custom tools. It includes built-in examples like a calculator and echo tool, utilizing Zod for robust input validation and error handling.

README

My MCP Server

A custom Model Context Protocol (MCP) server with an extensible tool architecture for Claude Code. This server makes it easy to add custom tools that Claude can use during conversations.

Features

Extensible Architecture: Easy-to-use pattern for adding new tools
TypeScript: Full type safety with TypeScript
Example Tools Included: Calculator and Echo tools to demonstrate the pattern
Production-Ready: Proper error handling and validation with Zod
Well-Documented: Clear examples and documentation for adding new tools

Available Tools

1. Calculate

Perform basic arithmetic operations (add, subtract, multiply, divide).

Example usage:

"Calculate 15 + 27"
"What's 100 divided by 4?"
"Multiply 8 by 9"

2. Echo

Echo a message back, with optional text transformation (uppercase/lowercase).

Example usage:

"Echo 'Hello World'"
"Echo 'test message' in uppercase"
"Echo 'LOUD TEXT' in lowercase"

Installation

1. Install Dependencies

npm install

2. Build the Project

npm run build

This will compile the TypeScript code to JavaScript in the build/ directory.

3. Configure Claude Code

Add the following configuration to your ~/.claude.json file:

{
  "mcpServers": {
    "my-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/martin/src/my-mcp/build/index.js"]
    }
  }
}

Important: Make sure to use the absolute path to your build/index.js file.

4. Restart Claude Code

After updating the configuration, restart Claude Code to load the MCP server.

Adding New Tools

Adding a new tool is simple and follows a consistent pattern:

Step 1: Create a New Tool File

Create a new file in src/tools/ with the naming convention your-tool.tool.ts:

import { z } from "zod";
import type { ToolDefinition } from "../types/index.js";

export const yourTool: ToolDefinition = {
  name: "your_tool_name",
  description: "Description of what your tool does",

  inputSchema: z.object({
    param1: z.string().describe("Description of parameter 1"),
    param2: z.number().optional().describe("Optional parameter 2"),
  }),

  handler: async (args) => {
    // Your tool logic here
    const result = `Processed: ${args.param1}`;

    return {
      content: [{
        type: "text",
        text: result
      }]
    };
  }
};

Step 2: Register the Tool

Add your tool to the registry in src/tools/index.ts:

import { yourTool } from "./your-tool.tool.js";

export const tools: ToolDefinition[] = [
  echoTool,
  calculatorTool,
  yourTool,  // Add your tool here
];

Step 3: Rebuild

npm run build

Step 4: Restart Claude Code

Restart Claude Code to load the new tool.

Step 5: Test

Try using your new tool in a conversation with Claude!

Tool Examples

Simple Text Processing Tool

import { z } from "zod";
import type { ToolDefinition } from "../types/index.js";

export const reverseTool: ToolDefinition = {
  name: "reverse",
  description: "Reverse a string",

  inputSchema: z.object({
    text: z.string().describe("The text to reverse"),
  }),

  handler: async (args) => {
    const reversed = args.text.split("").reverse().join("");

    return {
      content: [{
        type: "text",
        text: reversed
      }]
    };
  }
};

API Call Tool

import { z } from "zod";
import type { ToolDefinition } from "../types/index.js";

export const weatherTool: ToolDefinition = {
  name: "get_weather",
  description: "Get current weather for a location",

  inputSchema: z.object({
    location: z.string().describe("City name or zip code"),
  }),

  handler: async (args) => {
    try {
      // Make API call (example)
      const response = await fetch(
        `https://api.weather.example.com/current?location=${args.location}`
      );
      const data = await response.json();

      return {
        content: [{
          type: "text",
          text: `Weather in ${args.location}: ${data.temperature}°F, ${data.conditions}`
        }]
      };
    } catch (error) {
      return {
        isError: true,
        content: [{
          type: "text",
          text: `Failed to fetch weather: ${error instanceof Error ? error.message : 'Unknown error'}`
        }]
      };
    }
  }
};

Project Structure

my-mcp/
├── src/
│   ├── index.ts                    # Main entry point
│   ├── server.ts                   # Server initialization and request handlers
│   ├── tools/
│   │   ├── index.ts                # Tool registry (add new tools here)
│   │   ├── calculator.tool.ts      # Calculator tool implementation
│   │   └── echo.tool.ts            # Echo tool implementation
│   └── types/
│       └── index.ts                # TypeScript type definitions
├── build/                          # Compiled JavaScript (generated)
├── package.json                    # Project dependencies and scripts
├── tsconfig.json                   # TypeScript configuration
├── .gitignore                      # Git ignore rules
├── .env.example                    # Environment variable template
└── README.md                       # This file

Development

Build the Project

npm run build

Run in Development Mode

npm run dev

This will build and run the server, showing any startup logs.

Error Handling

All tools should handle errors gracefully and return structured error responses:

// Success response
return {
  content: [{
    type: "text",
    text: "Operation successful"
  }]
};

// Error response
return {
  isError: true,
  content: [{
    type: "text",
    text: "Error: Something went wrong"
  }]
};

Important Notes

Logging: Always use console.error() for logging, never console.log(). The latter corrupts JSON-RPC messages over stdio.
Input Validation: All inputs are automatically validated using Zod schemas
Error Messages: Provide clear, helpful error messages for debugging
Async Handlers: All tool handlers are async functions