MCP Template Server

A template project for creating your own MCP (Model Context Protocol) server using the standard MCP SDK

🔭 What's Included

The template includes:

• Ready-to-use MCP server setup with stdio transport
• Structure for defining MCP tools, resources, and prompts
• TypeScript configuration
• Development scripts and configuration

✨ Features

• TypeScript: Full TypeScript support for type safety
• Zod Validation: Type-safe validation of tool inputs
• Extensible: Easy to add custom tools, resources, and prompts

🚀 Getting Started

After setting up your project:

1. Install dependencies using your preferred package manager:

   # Using npm
   npm install
   
   # Using yarn
   yarn
   
   # Using pnpm
   pnpm install
   
   # Using bun
   bun install
   

   Copy

2. Start the server:

   # Start the server
   npm start
   

   Copy

3. For development with auto-reload:

   # Development mode
   npm run dev
   

   Copy

📖 Detailed Usage

Transport Method

This MCP server uses stdio transport:

• Runs on your local machine
• Managed automatically by Cursor
• Communicates directly via stdout
• Ideal for personal development and tools

Running the Server Locally

Start the server in stdio mode:

# Start the server
npm start
# or with other package managers
yarn start
pnpm start
bun start

# Start the server in development mode with auto-reload
npm run dev
# or
yarn dev
pnpm dev
bun dev

Connecting from Cursor

To connect to your MCP server from Cursor:

1. Open Cursor and go to Settings (gear icon in the bottom left)
2. Click on "Features" in the left sidebar
3. Scroll down to "MCP Servers" section
4. Click "Add new MCP server"
5. Enter the following details:
   • Server name: my-mcp-server (or any name you prefer)
   • Type: command
   • Command: The path to your server executable, e.g., npm start
6. Click "Save"

Using mcp.json with Cursor

For a more portable configuration, create an .cursor/mcp.json file in your project's root directory:

{
  "mcpServers": {
    "mcp-template": {
      "command": "npm",
      "args": ["start"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

You can also create a global configuration at ~/.cursor/mcp.json to make your MCP servers available in all your Cursor workspaces.

Testing Your Server with MCP Inspector

MCP SDK provides tools for testing your server:

# Inspect with MCP Inspector
npx @modelcontextprotocol/inspector --config inspector-config.json --server mcp-template

🛠️ Adding Custom Tools

// Define your tool in src/tools/myTool.ts
import { myToolSchema, MyToolParams } from '../types/index.js';

export const myTool = {
  name: 'my_tool',
  description: 'My custom tool description',
  parameters: myToolSchema,
  execute: async (params: MyToolParams) => {
    return `Hello, ${params.name}!`;
  }
};

// Then register it in src/core/server.ts
import { myTool } from '../tools/myTool.js';
import { myToolSchema } from '../types/index.js';

// Add to server capabilities
tools: {
  my_tool: {
    description: 'My custom tool description',
    schema: myToolSchema.shape
  }
}

// Add to ListToolsRequestSchema handler
tools: [
  {
    name: 'my_tool',
    description: 'My custom tool description',
    inputSchema: {
      // Schema definition...
    }
  }
]

// Add to CallToolRequestSchema handler
if (request.params.name === 'my_tool') {
  const args = myToolSchema.parse(request.params.arguments || {});
  const result = await myTool.execute(args);
  // Return result...
}

📚 Documentation

For more information about the Model Context Protocol, visit the MCP Documentation.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.