mcp -template

This MCP server template provides a TypeScript foundation for building MCP-compatible servers. It uses a service-based architecture with a DataProcessor interface and example tool implementations to demonstrate how tools are exposed, validated, and executed through the MCP protocol. The project includes a built-in TestClient for local testing and an MCP Inspector for visual debugging, making it straightforward to validate tool behavior and request/response flows as you develop custom tools. To get started, implement your tools in src/tools, export them along with their handlers, and register them in src/index.ts so they appear in the available tools and are wired to their handlers automatically.

Once your tools are wired, you can run the development server, build the project, and run tests using the provided npm scripts. The inspector and TestClient give you a convenient playground to iterate quickly on tool definitions, input validation, and formatting of MCP-compliant responses. When you're ready for production, the server can be started with a single node process running dist/index.js, after a TypeScript build step.

Prerequisites:

• Node.js and npm installed on your machine
• Git to clone the repository (optional if you already have the code)

Setup and install steps:

1. Clone the repository or download the template
2. Install dependencies

   npm install
   

3. Build the project (transpile TypeScript to JavaScript)

   npm run build
   

4. Run the development server with hot reload during development

   npm run dev
   

5. Run tests with the built-in TestClient and Vitest setup

   npm test
   

6. Create a production build and start the production server

   npm run build
   npm start
   

Notes:

• If you modify code, you may need to rebuild before running again
• The inspector can be launched via the provided command in the README to validate tool behavior

Tip: Use the example tool as a starter to understand the tool metadata format (name, description, parameters) and the corresponding handler shape. The template is designed to be extended by exporting new tools and handlers from src/tools/ and then combining them in src/index.ts. If you plan to test locally with Cursor, remember to build and link the package, then run the example tool via npx and register it in Cursor as described in the README. Keep an eye on MCP message formatting rules to ensure your responses conform to the MCP protocol. If you encounter environment-related issues, verify that MCP_HOST and MCP_PORT (or other required vars) are correctly set for your runtime environment.