mcp-server-template

MCP Server Template (create-mcp-server)

This template helps you quickly bootstrap a new Model Context Protocol (MCP) server project based on recommended practices.

Usage (Creating a New Server)

To create a new MCP server project named my-new-mcp-server, run the following command using npx:

npx create-mcp-server my-new-mcp-server

(Note: If you haven't published this package to npm, you might need to run npm link in this template directory first, then use create-mcp-server my-new-mcp-server)

This will:

1. Create a new directory named my-new-mcp-server.
2. Prompt you for project details (name, description).
3. Copy the template files (src, docs, config files, etc.) into the new directory.
4. Update the package.json with your project details.

After initialization, follow the instructions provided in the terminal:

cd my-new-mcp-server
npm install
# Review configuration in src/config/ConfigurationManager.ts
# Add your tools in src/tools/
# Add your services in src/services/
npm run dev  # Start the development server

---

Developing This Template (Advanced)

This section describes the structure and development process for the mcp-server-template itself. You typically don't need this if you are just using the template to create your own server.

Project Structure

• /src: Contains all source code.
  • /config: Configuration management (ConfigurationManager).
  • /services: Core business logic classes.
  • /tools: MCP tool definitions and adapters (*Tool.ts,*Params.ts).
  • /types: TypeScript interfaces and Zod schemas.
  • /utils: Shared utility functions (logging, errors, etc.).
  • initialize.ts: Server instance creation and tool registration.
  • server.ts: Main application entry point.
• /dist: Compiled JavaScript output (generated by pm run build).
• package.json: Project metadata and dependencies.
• sconfig.json: TypeScript compiler options.
• .eslintrc.json: ESLint configuration.
• .prettierrc.json: Prettier configuration.
• .gitignore: Git ignore rules.

Getting Started

1. Install Dependencies: ash npm install
2. Configure Husky (if needed, first time): ash npx husky install
3. Run in Development Mode: (Uses s-node and odemon for auto-reloading) ash npm run dev
4. Build for Production: ash npm run build
5. Run Production Build: ash npm start

Adding a New Tool (yourTool)

1. Define Types: Create src/types/yourServiceTypes.ts with interfaces (e.g., YourServiceConfig, YourServiceData). Export from src/types/index.ts.
2. Implement Service: Create src/services/YourService.ts with the core logic class. Export from src/services/index.ts.
3. Define Tool Params: Create src/tools/yourToolParams.ts with TOOL_NAME, TOOL_DESCRIPTION, and TOOL_PARAMS (using Zod with detailed .describe() calls).
4. Implement Tool Registration: Create src/tools/yourTool.ts. Import the service and params. Create a function that instantiates the service and calls server.tool() with an async handler that validates input, calls the service, formats output, and handles errors (mapping to McpError).
5. Register the Tool: Import and call the registration function from src/tools/index.ts within the egisterTools function.
6. Add Configuration: If needed, update src/config/ConfigurationManager.ts to include config types, defaults, getters, and updaters for the new service.
7. Add Utilities: If needed, add helper functions to src/utils/ and export them.
8. Write Tests: Add unit tests for the service logic in src/services/ and potentially integration tests for the tool adapter in src/tools/.

Linting and Formatting

• Lint: pm run lint
• Format: pm run format

Code will be automatically linted and formatted on commit via Husky and lint-staged.