Foundation for MCP Service Implementation

This template provides a production-ready starting point for developing Model Context Protocol (MCP) backend services using TypeScript.

⚡ Rapid Initialization

1. Clone the source repository.
2. Resolve project dependencies: bash bun install

🌟 Core Capabilities

• Execution speed powered by Bun for swift testing cycles and development flow.
• Code quality enforcement via Biome for comprehensive linting and automated formatting.
• Standardization of version tracking through the standard-version utility.
• A meticulously organized and easily navigable project layout.

📁 Directory Schema

mcp-foundation/
├── src/
│   ├── tools/          # Contains core MCP tool implementations
│   ├── utils/          # Common, shared utility functions
│   ├── main.ts         # Primary server bootstrap file
│   └── types.ts        # Centralized type definitions and interfaces
├── tests/
├── biome.json          # Biome configuration settings
├── tsconfig.json       # TypeScript compiler directives
└── package.json        # Manifest of project dependencies

🔧 Configuration & Tool Generation

This repository features a dedicated script designed to streamline the creation of new MCP tools:

bun run scripts/create-tool.ts <tool-identifier>

This command automates the following: 1. Provisioning a new directory under src/tools/<tool-identifier>. 2. Populating the directory with boilerplate files, including: - index.ts (The primary logic module). - schema.ts (JSON schema definition for parameter validation). - test.ts (A corresponding unit test file). 3. Automatically registering the freshly created tool within the main tools index file.

Invocation Example (for a 'weather' utility):

bun run scripts/create-tool.ts weather

🧪 Operational Workflow

• Execute Unit Tests: bun test
• Apply Code Formatting: bun run format
• Perform Static Analysis: bun run lint
• Compile Assets: bun run build

To integrate your active MCP service instance with the Claude Desktop environment:

1. Compile the project assets: bash bun run build
2. Configure your Claude Desktop manifest (settings.json): json // Arguments are optional; only required if your server needs runtime parameters { "mcpServers": { "my-service-instance": { "command": "node", "args": ["/absolute/path/to/your/project/dist/main.js", "initial_config_param"] } } }

📜 Version Lifecycle Management

This project adopts standard-version for autonomous version bumping and changelog generation. Execute bun run release to finalize a new iteration.

Commit Convention

• feat: Introduces a new capability (results in a minor version increment).
• fix: Rectifies a defect (results in a patch version increment).
• BREAKING CHANGE: Signifies a backwards-incompatible modification (results in a major version increment).

📦 Distribution via npm

1. Verify authentication with the npm registry: bash npm login
2. Compile the final distributable assets: bash bun run build
3. Push the package to the registry: bash npm publish Crucially, initiate a version update (bun run release) before publishing any version increments.

📥 Installation from Registry

Once published, integrate the tool into your Claude Desktop configuration: ```json // Use 'npx' to execute the globally installed package directly { "mcpServers": { "my-published-tool": { "command": "npx", "args": ["-y", "your-npm-package-name", "startup_param"] } } }