scaffold-mcp-typescript-service

Generate a fresh, feature-complete MCP host application in TypeScript.

Initializing the Project

shell npm init mcp-ts your-service-name cd your-service-name npm run dev

This toolchain demands no upfront build configuration; it automatically provisions all necessary dependencies for coding, compiling, and establishing your MCP service.

Integration Setup for Cursor, Windsurf, and Claude Desktop

scaffold-mcp-typescript-service offers automated setup scripts for major clients:

shell npm run setup

This execution verifies the presence of your-service-name within each client's designated MCP configuration registry. If absent, it injects a new entry referencing the compiled service executable (dist/index.js):

{ "mcpConfig": { "your-service-name": { "command": "node", "args": ["/absolute/path/to/your-service-name/dist/index.js"] } } }

For exhaustive instructions on integrating MCP services across Cursor, Windsurf, and Claude Desktop, consult:

• Cursor's MCP Documentation
• Windsurf MCP Guide
• Claude Desktop Quickstart for MCP

Utilizing Custom Boilerplates

To employ a bespoke project structure, supply the desired template package name or filesystem reference during invocation:

shell npx create-mcp-ts your-service-name --template=custom-mcp-template-package npx create-mcp-ts your-service-name --template=file:/path/to/local/template

Distributing Your MCP Service

To ready your backend for public distribution via npm:

1. Update package.json: ensure version is set and private is false.
2. Execute npm install.
3. Run npm run build.
4. Execute npm login (if authentication is required).
5. Execute npm publish.

Decoupling from the Core Build System (mcp-scripts)

The mcp-scripts module encapsulates the essential compilation utilities for projects initiated by this scaffolding tool—providing everything needed for development and deployment without external configuration.

Internally, mcp-scripts leverages high-performance tools such as tsup and esbuild, robust components suitable for enterprise-grade TypeScript environments.

Should you wish to transition to a self-managed build setup, execute the following migration command:

shell npm run eject

This action eliminates the mcp-scripts dependency and replaces all associated script hooks in your package.json with direct configurations, allowing immediate modification of the underlying toolchain.

Troubleshooting Service Execution

Verify Node.js Runtime Presence

If your service fails to initialize, confirm that Node.js is accessible system-wide:

shell node --version

If Node.js is missing, installation guidance is available here.

Compatibility with Node Version Managers

Certain host environments might restrict the system PATH, leading to resolution failures when utilizing Node version switchers like nodenv or nvm. In such scenarios, supplying the absolute path to the Node.js executable within your MCP configuration is necessary:

{ "mcpConfig": { "your-service-name": { "command": "/absolute/path/to/node", "args": ["/path/to/your-service-name/dist/index.js"] } } }

To ascertain the absolute path of your active Node.js binary, use:

shell which node

Remember to update the MCP settings in every integrated client (Cursor, Windsurf, Claude Desktop) to reflect the correct binary location.

For all supplementary issues, please submit a new ticket here.

Core Design Principles

scaffold-mcp-typescript-service prioritizes a 'zero-friction' development experience for MCP backend authors.

• Comprehensive Inclusion: Relies solely on the mcp-scripts package, which curates experiences built upon stellar open-source components like tsup and esbuild.
• Instant Readiness: Eliminates the need for manual configuration; a sensible, optimized setup is pre-applied, allowing focus solely on application logic.
• Freedom to Evolve: The 'eject' mechanism permits instantaneous migration to a fully customized setup. One command transfers all configuration and build dependencies directly into your project, ensuring continuity.

This utility draws foundational inspiration from the philosophy established by create-react-app.

Associated Tooling

• packages/mcp-scripts: The backend build orchestration layer powering projects generated by this tool.
• packages/mcp-ts-template-default: The boilerplate structure used by default for new instances.