A template repository for creating Model Context Protocol (MCP) servers in Node.js/TypeScript. This template demonstrates a simple notes management system using the MCP protocol.

The Model Context Protocol (MCP) is a standardized way for applications to provide context to Large Language Models (LLMs). Learn more at the Model Context Protocol Website.

• TypeScript implementation with strict type checking
• Simple notes management system with basic CRUD operations
• Complete examples of MCP concepts (Tools, Resources, Prompts)
• In-memory storage for notes
• Comprehensive error handling and validation
• Unit tests with Vitest
• VS Code debugging configuration
• GitHub Actions CI workflow for testing and building

• Node.js 18 or later
• npm or yarn

mcp-template-node/ ├── build/ # Compiled JavaScript files ├── src/ │ ├── __tests__/ # Integration tests and test utilities │ ├── errors/ # Custom error classes │ ├── tools/ # MCP tool implementations │ │ └── __tests__/ # Tool unit tests │ ├── types/ # TypeScript type definitions │ │ └── __tests__/ # Type tests │ └── index.ts # Main server entry point with MCP examples ├── package.json # Project configuration ├── tsconfig.json # TypeScript configuration ├── eslint.config.mjs # ESLint flat configuration └── README.md # Project documentation

1. Clone the repository:

   git clone https://github.com/Rethunk-Tech/mcp-template-node.git cd mcp-template-node

2. Install dependencies:

   yarn install

3. Build and run the server:

   yarn build yarn start

• Start TypeScript compiler in watch mode: yarn dev
• Lint your code: yarn lint
• Fix linting issues: yarn lint:fix
• Run tests: yarn test

This project includes comprehensive tests to verify the functionality of the MCP server and its tools.

Run all tests:

yarn test

Run tests in watch mode (rerun tests when files change):

yarn test:watch

Run tests with coverage:

yarn test:coverage

• Unit Tests: Located in __tests__ directories near the code they test
• Integration Tests: Located in src/__tests__/
• Test Utilities: Common test helpers in src/__tests__/test-utils.ts

The project includes a MockMcpServer for testing tools without real MCP dependencies:

import { MockMcpServer } from '../__tests__/test-utils.js'; describe('My Tool Tests', () => { let server: MockMcpServer; beforeEach(() => { server = new MockMcpServer(); // Register tools registerMyTools(server as any); }); it('should perform some action', async () => { const result = await server.callTool('my_tool', { param: 'value' }); expect(result.content[0].text).toContain('Expected text'); }); });

For standalone testing, use the MCP Inspector tool:

yarn inspector

This will open an interactive session where you can test your MCP tools.

Creates a new note with title and content.

Lists all available notes with their IDs and titles.

Retrieves a specific note by ID.

Updates an existing note's title, content, or tags.

Deletes a note by ID.

To extend this template:

1. Add new types in src/types/
2. Implement new tools in src/tools/
3. Add new resources in src/index.ts
4. Create new prompt templates as needed
5. Add tests for your new functionality

See CONTRIBUTING.md for guidelines on how to contribute to this project.

MIT