io.github.qmmughal/mcp-server-template

Enterprise MCP Server Template 🚀

A production-ready, enterprise-grade template for building Model Context Protocol (MCP) servers in TypeScript and Node.js. Designed for scalability, type safety, and seamless integration with AI agents like Claude Desktop and Cursor.

📖 About

The Model Context Protocol (MCP) standardizes how AI models interact with local and remote resources. This template provides a robust foundation for building your own custom MCP servers, eliminating boilerplate and enforcing best practices.

Key Features

• Strict TypeScript: Modern ECMAScript targets with rigorous type safety.
• Zod Validation: Runtime schema validation for tool inputs and environment variables, ensuring your server never crashes from malformed AI payloads.
• Fast Bundling (esbuild): Compiles the entire server into a single, optimized executable (dist/index.js), eliminating the need to deploy node_modules.
• Safe Structured Logging: Pre-configured pino logger writing safely to stderr, preserving the integrity of the stdout JSON-RPC transport required by MCP.
• Modular Architecture: Clean separation of Tools, Resources, Prompts, and Services.
• Vitest Integration: Blazing fast unit testing out of the box.

🚀 Getting Started

1. Installation

Clone the repository and install dependencies:

git clone https://github.com/qmmughal/mcp-server-template.git
cd mcp-server-template
npm install

2. Configuration

Copy the example environment file and configure your variables:

cp .env.example .env

3. Development Workflow

Start the server in watch mode for local development:

npm run dev

Run the test suite:

npm test

Verify typings:

npm run typecheck

4. Production Build

Bundle the server into a single, optimized executable:

npm run build

The output will be generated at dist/index.js.

🔌 Connecting to an MCP Client

Claude Desktop

To connect this server to the Claude Desktop app, edit your Claude configuration file (usually found at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "enterprise-template-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-template/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "EXAMPLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

In Cursor, navigate to Settings -> Features -> MCP and add a new MCP server:

• Type: command
• Command: node /absolute/path/to/mcp-server-template/dist/index.js

🏗️ Architecture Overview

• src/index.ts: Application entrypoint, capability registration, and stdio connection setup.
• src/tools/: Definitions and JSON schemas for MCP Tools (actions the AI can take).
• src/resources/: Dynamic resources via URI templating (data the AI can read).
• src/prompts/: Reusable agent prompt templates.
• src/services/: Core business logic, keeping protocol handlers thin and testable.
• src/utils/errors.ts: Standardized error handling aligned with MCP error codes.

📦 Publishing & Registry

package.json is publish-ready (scoped name @qmmughal/mcp-server-template, license, repository, keywords), and server.json + .github/workflows/publish-mcp.yml are wired up to publish to both npm and the MCP Registry automatically whenever a v* tag is pushed:

git tag v1.0.0
git push origin v1.0.0

The workflow needs one repo secret before it can run: NPM_TOKEN (an npm automation token with publish rights to the @qmmughal scope). MCP Registry auth uses GitHub OIDC, so no extra secret is needed there.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

📝 License

This project is MIT licensed.