planla-ai/nodejs-mcp-tool-template

MCP Tool Template

A clean, production-ready template for building custom MCP (Model Context Protocol) server tools. Get started quickly with TypeScript, Docker support, and example tools.

✨ Features

• HTTP Transport: Streamable HTTP server for web integration
• TypeScript: Full type safety and modern development experience
• Docker Ready: Containerized deployment with health checks
• Example Tools: Calculator, text processor, and test tools included
• Hot Reload: Development server with automatic restart
• MCP Inspector: Built-in testing and debugging tools

🚀 Quick Start

# Clone and setup
git clone <your-repo-url>
cd mcp-tool-template
npm install

# Configure environment
cp .env.example .env

# Start development server
npm run dev

Server runs at http://localhost:8080 with endpoints:

• MCP: /mcp
• Health: /health

📁 Project Structure

src/
├── config/default.ts        # Environment configuration
├── mcp/
│   ├── tools/              # Your custom tools
│   │   ├── example.tools.ts # Calculator & text processor
│   │   └── test.tools.ts    # Basic test tool
│   └── mcpServer.ts        # MCP server setup
└── index.ts                # HTTP server entry point

🛠️ Creating Custom Tools

1. Create tool file in src/mcp/tools/:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export const registerMyTools = (server: McpServer) => {
  server.tool(
    "my_tool",
    "Tool description",
    {
      input: z.string().describe("Input parameter"),
      count: z.number().optional().describe("Optional count"),
    },
    async ({ input, count = 1 }) => {
      const result = input.repeat(count);
      return {
        content: [{ type: "text", text: result }],
      };
    }
  );
};

2. Register in server (src/mcp/mcpServer.ts):

import { registerMyTools } from "./tools/my-tool";
// Add to getServer function:
registerMyTools(serverInstance);

3. Test with inspector:

npm run inspect
> list_tools
> call_tool my_tool '{"input": "Hello", "count": 3}'

⚙️ Configuration

Environment variables in .env:

🐳 Docker Usage

# Build and run
docker build -t nodejs-mcp-tool-template .
docker run -p 8080:8080 nodejs-mcp-tool-template

# With custom environment
docker run -p 8080:8080 \
  -e MCP_SERVER_NAME=my-server \
  -e PORT=3000 \
  mcp-tool-template

🧪 Testing

MCP Inspector (interactive testing):

npm run inspect

HTTP Endpoints (direct testing):

# Health check
curl http://localhost:8080/health

# MCP initialize
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' \
  http://localhost:8080/mcp

📦 Production Deployment

# Build for production
npm run build
npm start

# Or with Docker
docker build -t my-mcp-server .
docker run -d -p 8080:8080 --name mcp-server my-mcp-server

🔧 Available Scripts

• npm run dev - Development server with hot reload
• npm run build - Build TypeScript to JavaScript
• npm start - Start production server
• npm run inspect - Launch MCP Inspector
• npm run format - Format code with Prettier

🔗 Integration

Connect your MCP server to AI applications via HTTP transport:

• URL: http://localhost:8080/mcp
• Protocol: MCP 2024-11-05
• Transport: Streamable HTTP

📚 Example Tools Included

• test: Basic testing tool
• calculator: Math operations (add, subtract, multiply, divide)
• text_processor: Text manipulation (uppercase, lowercase, reverse, word count)

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/my-tool
3. Commit changes: git commit -m 'Add my tool'
4. Push and create Pull Request

📄 License

MIT License - see file for details.

Ready to build? Start creating your custom MCP tools and integrate them with AI applications! 🚀