mcp-boilerplate

# 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: ```bash # Using npm npm install # Using yarn yarn # Using pnpm pnpm install # Using bun bun install ``` 2. Start the server: ```bash # Start the server npm start ``` 3. For development with auto-reload: ```bash # Development mode npm run dev ``` ## 📖 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: ```bash # 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: ```json { "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: ```bash # Inspect with MCP Inspector npx @modelcontextprotocol/inspector --config inspector-config.json --server mcp-template ``` ## 🛠️ Adding Custom Tools ```typescript // 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](https://modelcontextprotocol.io/introduction). ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.