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

Troubleshooting

Server Not Appearing in Claude Code

1. Check that the path in ~/.claude.json is absolute and correct
2. Verify the build succeeded: npm run build
3. Restart Claude Code completely
4. Check for errors: node build/index.js (should start without errors)

Tool Not Working

1. Verify the tool is added to the registry in src/tools/index.ts
2. Rebuild the project: npm run build
3. Restart Claude Code
4. Check the Zod schema matches your expected input format

TypeScript Errors

1. Make sure all imports use .js extensions (required for ES modules)
2. Run npm run build to see detailed error messages
3. Check that types are correctly imported from ../types/index.js

License

MIT

Contributing

Feel free to add more tools and share them! The modular architecture makes it easy to create and share tool implementations.