# Clone and rename
git clone https://github.com/srmcguirt/mcp-server-starter-kit my-mcp-server
cd my-mcp-server

# Install dependencies
npm install

# Copy env file and fill in your values
cp .env.example .env

# Start in dev mode (hot reload)
npm run dev

npx @wireforge/mcp-server-starter init my-server-name
cd my-server-name
npm install && npm run dev

npm install @wireforge/mcp-server-starter

// src/tools/my-tool.ts
import { z } from 'zod';
import { toolResult } from '../lib/error-handler.js';
import type { MCPTool } from '../types.js';

const MyInputSchema = z.object({
  query: z.string().min(1).max(500),
  limit: z.number().int().positive().max(100).default(10),
});

export const myTool: MCPTool = {
  name: 'my_tool',
  description: 'Search for something and return results. Be specific about what this does — the AI reads this description.',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'The search query' },
      limit: { type: 'number', description: 'Max results to return', default: 10 },
    },
    required: ['query'],
  },
  async execute(args) {
    const { query, limit } = MyInputSchema.parse(args);

    // Your implementation here
    const results = await myApi.search(query, { limit });

    return toolResult(JSON.stringify(results, null, 2));
  },
};

import { myTool } from './my-tool.js';

export const tools: MCPTool[] = [
  echoTool,
  fetchUrlTool,
  myTool, // 👈 Add here
];

# Build and add to Claude Desktop config automatically
chmod +x scripts/add-to-claude.sh
./scripts/add-to-claude.sh my-server-name

# Then restart Claude Desktop

{
  "mcpServers": {
    "my-server-name": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"],
      "env": {
        "MY_API_KEY": "your-key-here"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "my-server-name": {
        "command": "node",
        "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
      }
    }
  }
}

# Build and run with docker-compose
cd docker && docker-compose up --build

# Or build manually
docker build -f docker/Dockerfile -t my-mcp-server .
docker run -it --env-file .env my-mcp-server

mcp-server-starter/
├── src/
│   ├── index.ts              # Server entry point — wire everything together here
│   ├── types.ts              # MCPTool interface and shared types
│   ├── lib/
│   │   ├── logger.ts         # Winston logger — always logs to stderr
│   │   ├── rate-limiter.ts   # Token-bucket rate limiter
│   │   ├── env.ts            # Environment variable validation (Zod)
│   │   └── error-handler.ts  # Centralized error handling + toolResult helpers
│   └── tools/
│       ├── index.ts          # Tool registry — add your tools here
│       ├── echo.ts           # Example: simple string echo
│       └── fetch-url.ts      # Example: HTTP fetch with timeout + size limit
├── docker/
│   ├── Dockerfile            # Multi-stage production build
│   └── docker-compose.yml    # Local development + production compose
├── scripts/
│   └── add-to-claude.sh      # Auto-add to Claude Desktop config
├── .env.example              # Required environment variables
├── tsconfig.json             # Strict TypeScript config
└── package.json

// ❌ WRONG — corrupts MCP protocol
console.log('something happened');

// ✅ CORRECT — logs to stderr, leaves stdout clean
logger.info('something happened');

// ❌ WRONG — trusting AI-provided args
const { query } = args as { query: string };

// ✅ CORRECT — parse and validate
const { query } = MySchema.parse(args); // throws McpError on invalid input

// ❌ WRONG — unhandled exceptions crash the server
async execute(args) {
  return await riskyOperation(args);
}

// ✅ CORRECT — errors logged + safe message returned to AI
return withErrorHandling('my_tool', () => riskyOperation(args));