AI导哈

MCP服务器模板

一个基于Model Context Protocol（MCP）的服务器模板，集成了Harness工程最佳实践，包括TypeScript严格模式、预提交钩子、CI质量检查和协议级测试。

  • by Harurow
  • Shell
  • 本地部署
  • 更新于
在 GitHub 查看 Harurow/mcp-server-template

使用说明

mcp服务器模板

模型上下文协议（MCP） 服务器模板与线束工程最佳实践。

日语版在这里

特性

  • TypeScript+严格模式 — noUncheckedIndexedAccess, NodeNext 模组分辨率
  • 工程利用 --PostTool使用钩子、预提交门、CI质量检查
  • 代码检查 — Oxlint （皮棉）+ 生物群系 （格式），Rust支持毫秒级反馈
  • 测试 — Vitest 使用MCP SDK InMemoryTransport 用于协议级测试
  • 预承诺 — 左撇子 在每次提交时强制执行lint+typecheck+test+覆盖率

安装

直接使用npx运行（无需安装）

npx my-mcp-server

使用npm全局安装

npm install -g my-mcp-server
my-mcp-server

从存储库克隆

git clone https://github.com/USER/REPO.git
cd REPO
npm install
npm run build
npm run start

用作模板

来自GitHub（推荐）

  1. 使用此模板创建新存储库：

    gh repo create my-new-mcp --template harurow/mcp-server-template --clone --private
cd my-new-mcp

  2. 运行init脚本以自定义项目：

    bash scripts/init.sh my-new-mcp

  3. 设置分支保护（可选）：

    gh repo create my-new-mcp --private --source=. --push  # if not pushed yet
bash scripts/setup-branch-protection.sh

使用克劳德代码

/init-mcp-server my-new-mcp

手动复印

cp -r /path/to/mcp-server-template ~/code/my-new-mcp
cd ~/code/my-new-mcp
bash scripts/init.sh my-new-mcp

在初始化之后， scripts/init.sh 已删除，本节已从README中删除。

发展

npm run dev          # Start dev server (tsx watch)
npm run inspect      # Open MCP Inspector
npm run test         # Run tests
npm run test:coverage # Run tests with coverage (threshold: 80%)
npm run test:watch   # Run tests in watch mode
npm run lint         # Run oxlint + biome
npm run typecheck    # Run tsc --noEmit
npm run build        # Build to dist/

添加工具

  1. 创建 src/tools/<name>.ts:
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerMyTool(server: McpServer): void {
  server.tool(
    "my-tool",
    "Description of what this tool does",
    {
      param: z.string().describe("Parameter description"),
    },
    async ({ param }) => {
      return {
        content: [{ type: "text", text: `Result: ${param}` }],
      };
    },
  );
}
  1. 注册于 src/server.ts:
import { registerMyTool } from "./tools/my-tool.js";
registerMyTool(server);
  1. 添加测试 test/<name>.test.ts:
import { afterEach, describe, expect, it } from "vitest";
import type { TestContext } from "./helpers.js";
import { createTestContext } from "./helpers.js";

describe("my-tool", () => {
  let ctx: TestContext;
  afterEach(async () => { await ctx.cleanup(); });

  it("returns expected result", async () => {
    ctx = await createTestContext();
    const result = await ctx.client.callTool({
      name: "my-tool",
      arguments: { param: "hello" },
    });
    expect(result.content).toEqual([{ type: "text", text: "Result: hello" }]);
  });
});

MCP客户端配置

添加到您的MCP客户端配置中（例如Claude Desktop）：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

或者，如果全局安装或本地克隆：

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

项目结构

src/
├── index.ts               # STDIO entrypoint
├── server.ts              # McpServer creation + tool registration
└── tools/                 # One file per tool (filename = tool name)
test/
├── helpers.ts             # Shared test utilities (createTestContext)
└── *.test.ts              # Tests using InMemoryTransport
docs/adr/                  # Architecture Decision Records
scripts/                   # init.sh, setup-branch-protection.sh
.claude/                   # Hooks, settings, rules, skills
.github/workflows/         # CI pipeline
biome.json                 # Formatter config (Biome)
lefthook.yml               # Pre-commit hooks
tsconfig.json              # TypeScript config (strict)
vitest.config.ts           # Test config + coverage thresholds

备注: package.json 有 "private": true 默认情况下。在发布到npm之前删除它。

分支策略

  • main --受保护，需要CI通过+PR审查才能合并
  • feat/<name> --特征分支，南瓜并入主
  • fix/<name> --bugfix分支
  • chore/<name> --维护（deps、CI、docs）

看 贡献.md 了解详情。

许可证

麻省理工学院

相关 MCP