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:

• Create a new directory named my-new-mcp-server.
• Prompt you for project details (name, description).
• Copy the template files (src, docs, config files, etc.) into the new directory.
• 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

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

Adding a New Tool (yourTool)

• Define Types: Create src/types/yourServiceTypes.ts with interfaces (e.g., YourServiceConfig, YourServiceData). Export from src/types/index.ts.
• Implement Service: Create src/services/YourService.ts with the core logic class. Export from src/services/index.ts.
• Define Tool Params: Create src/tools/yourToolParams.ts with TOOL_NAME, TOOL_DESCRIPTION, and TOOL_PARAMS (using Zod with detailed .describe() calls).
• 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).
• Register the Tool: Import and call the registration function from src/tools/index.ts within the egisterTools function.
• Add Configuration: If needed, update src/config/ConfigurationManager.ts to include config types, defaults, getters, and updaters for the new service.
• Add Utilities: If needed, add helper functions to src/utils/ and export them.
• 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.