mcp-server-template

# Enterprise MCP Server Template 🚀

[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-1.4.1-purple.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

```bash
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:

```bash
cp .env.example .env
```

### 3. Development Workflow

Start the server in watch mode for local development:
```bash
npm run dev
```

Run the test suite:
```bash
npm test
```

Verify typings:
```bash
npm run typecheck
```

### 4. Production Build

Bundle the server into a single, optimized executable:
```bash
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):

```json
{
  "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](https://modelcontextprotocol.io/registry)** automatically whenever a `v*` tag is pushed:

```bash
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](LICENSE) licensed.