Content
# Enterprise MCP Server Template 🚀
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](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.
