<div align="center">

# 🧩 MCP Server Template Boilerplate

**Production-ready MCP server starter with TypeScript, realistic examples, and Claude Desktop integration.**

[![npm version](https://img.shields.io/npm/v/mcp-boilerplate?color=blue&style=flat-square)](https://www.npmjs.com/package/mcp-boilerplate)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
[![CI](https://github.com/agiulucom42-del/mcp-boilerplate/actions/workflows/ci.yml/badge.svg)](https://github.com/agiulucom42-del/mcp-boilerplate/actions)

</div>

---

A production-ready boilerplate for building Model Context Protocol (MCP) servers using TypeScript and Node.js.

## Features

- **TypeScript** pre-configured for modern module resolution (`NodeNext`)
- **`tsup`** configured for lightning-fast builds
- Clean **MCP SDK** setup using `StdioServerTransport`
- Example **Tool** (`web_fetch`) — fetches URLs and returns content as a resource
- Example **Resource** (`file://read`) — reads local files securely
- Claude Desktop integration guide

## Quick Start

### Installation

```bash
git clone https://github.com/agiulucom42-del/mcp-boilerplate.git
cd mcp-boilerplate
npm install
npm run build
```

### Run the server

```bash
npm start
```

*MCP servers using `stdio` communicate via standard input/output. `npm start` waits for JSON-RPC messages from an MCP client.*

## Integration with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-boilerplate/dist/index.js"]
    }
  }
}
```

## Example Tool: `web_fetch`

The boilerplate ships with a realistic tool that fetches a URL and returns its content:

```typescript
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "web_fetch") {
    const url = String(request.params.arguments?.url);
    const response = await fetch(url);
    const text = await response.text();
    return {
      content: [{ type: "text", text: text.slice(0, 10000) }]
    };
  }
  throw new Error("Tool not found");
});
```

## Example Resource: `file://read`

Safely read files from an allowed directory:

```typescript
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  const path = request.params.uri.replace("file://", "");
  const content = await fs.readFile(path, "utf-8");
  return {
    contents: [{ uri: request.params.uri, text: content }]
  };
});
```

## How to Customize

1. **Add Tools:** Edit the `CallToolRequestSchema` handler in `src/index.ts`
2. **Add Resources:** Edit `ReadResourceRequestSchema` and `ListResourcesRequestSchema`
3. **Change Name:** Update the `name` in `new Server()` instantiation

---

## 🚀 HUQAN Ecosystem

mcp-boilerplate is part of the **HUQAN** trust infrastructure for AI. Sister projects:

| Tool | What it does |
|---|---|
| [env-sentinel](https://github.com/agiulucom42-del/env-sentinel) | 🔴 Stop leaking API keys |
| [readme-score](https://github.com/agiulucom42-del/readme-score) | 📊 Score your README quality |
| [repo-risk-scan](https://github.com/agiulucom42-del/repo-risk-scan) | 🛡️ Scan repo before giving to agent |
| [pr-scope-check](https://github.com/agiulucom42-del/pr-scope-check) | 📏 Block PR scope creep |
| [llm-diff](https://github.com/agiulucom42-del/llm-diff) | 🔍 Compare LLM outputs |
| [token-budget](https://github.com/agiulucom42-del/token-budget) | 💰 Track LLM API costs |
| [axiom-verify](https://github.com/agiulucom42-del/axiom-verify) | ✅ Validate LLM JSON outputs |
| [mcp-boilerplate](https://github.com/agiulucom42-del/mcp-boilerplate) | 🧩 MCP server starter **You are here** |

---

## License

MIT © [HUQAN](https://huqan.com)

---

<div align="center">
  <a href="https://www.buymeacoffee.com/huqan">☕ Buy me a coffee</a>
</div>