handbook

handbook-mcp-server

由 ah-oh.com 提供的 Handbook API 的 MCP（模型上下文协议）服务。可通过 Claude Desktop、Claude Code、VS Code Copilot 和其他兼容 MCP 的客户端，直接全面管理手册条目。

---

功能

工具	描述
handbook_list_entries	列出所有手册条目
handbook_get_entry	根据 ID 获取单个条目（包括 Markdown 内容）
handbook_create_entry	创建新条目
handbook_update_entry	更新现有条目
handbook_delete_entry	删除条目
handbook_get_overview	按应用提供所有条目的简要概览
handbook_search_tags	搜索所有条目中的标签

---

前置条件

• Node.js >= 18
• Bearer Token（用于 Handbook API）

---

安装

选项 A：从 npm 安装

npm install -g @ah-oh/handbook-mcp-server

选项 B：从源代码构建

git clone https://github.com/ah-oh/handbook-mcp-server.git
cd handbook-mcp-server
npm install
npm run build

---

配置

环境变量

变量	必填	默认值	描述
HANDBOOK_API_TOKEN	是	–	Handbook API 的 Bearer Token
HANDBOOK_API_URL	否	https://handbook.ah-oh.com/handbook-api	API 的基础 URL
TRANSPORT	否	stdio	传输模式：stdio 或 http
PORT	否	3000	HTTP 传输使用的端口

---

使用方法

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "handbook": {
      "command": "node",
      "args": ["/absolute/path/to/handbook-mcp-server/dist/index.js"],
      "env": {
        "HANDBOOK_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

如果通过 npm 全局安装：

{
  "mcpServers": {
    "handbook": {
      "command": "handbook-mcp-server",
      "env": {
        "HANDBOOK_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

Claude Code

claude mcp add handbook -- node /path/to/handbook-mcp-server/dist/index.js \
  --env HANDBOOK_API_TOKEN=your-bearer-token

VS Code（Copilot / Continue）

在 .vscode/mcp.json 中：

{
  "servers": {
    "handbook": {
      "command": "node",
      "args": ["/path/to/handbook-mcp-server/dist/index.js"],
      "env": {
        "HANDBOOK_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

HTTP 模式（远程）

TRANSPORT=http HANDBOOK_API_TOKEN=your-token PORT=3000 npm start

服务将在 http://localhost:3000/mcp 上监听。

---

示例

连接 MCP 服务后，你可以向 Claude 提出类似这样的请求：

• “显示所有手册条目”
• “为应用 szales 创建一个标题为 ‘Onboarding Guide’ 的新条目”
• “更新 ID 为 65c4e1f5... 的条目——将内容设置为……”
• “哪些标签以 ‘meet’ 开头？”
• “概览应用 sethub 的所有条目”
• “删除条目 65c4e1f5...”

---

发布到 MCP Registry

官方 MCP Registry 可让所有 MCP 客户端发现你的服务。以下是分步指南：

步骤 1：替换占位符

将项目中所有的 ah-oh 替换为你的 GitHub 用户名：

# macOS
find . -type f \( -name "*.json" -o -name "*.md" \) \
  -exec sed -i '' 's/ah-oh/my-github-user/g' {} +

# Linux
find . -type f \( -name "*.json" -o -name "*.md" \) \
  -exec sed -i 's/ah-oh/my-github-user/g' {} +

这会影响以下文件：

• package.json – 字段 name、mcpName、repository、homepage、bugs
• server.json – 字段 name、repository、packages[0].identifier
• README.md – 链接和安装命令

步骤 2：发布到 npm

# Log in to npm (one-time)
npm login

# Publish the package
npm publish --access public

注意： MCP Registry 只托管元数据，不托管代码本身。你的软件包必须先发布到 npm（或 PyPI、Docker Hub 等平台）。

步骤 3：安装 mcp-publisher CLI

curl -L \
  "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
  | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

# Verify
mcp-publisher --help

步骤 4：登录注册表

mcp-publisher login github

这会打开浏览器进行 GitHub OAuth 登录。你将获得 io.github.ah-oh/* 命名空间的访问权限。

替代方案（自定义域名，例如 com.ah-oh/*）：

# 生成 Ed25519 密钥对
openssl genpkey -algorithm Ed25519 -out key.pem

# 将公钥托管在 https://ah-oh.com/.well-known/mcp-registry-auth
# 然后：
mcp-publisher login http --domain=ah-oh.com --private-key=HEX_KEY

步骤 5：发布

# Dry run first
mcp-publisher publish --dry-run

# Publish for real
mcp-publisher publish

随后，你的服务便可在 registry.modelcontextprotocol.io 中被发现，并会自动收录到下游注册表（GitHub、VS Code 等）。

步骤 6（可选）：通过 GitHub Actions 自动化

项目在 .github/workflows/publish.yml 中提供了一个现成的工作流文件。每次创建 git 标签（v*）时，它都会自动发布到 npm 和 MCP Registry。

设置：

1. 前往 npmjs.com → Access Tokens → 创建新令牌
2. 在 GitHub 中 → Repository → Settings → Secrets and Variables → Actions → 添加 NPM_TOKEN 作为机密
3. 为发布版本创建标签并推送：

git tag v1.0.0
git push origin v1.0.0

后续工作由流水线处理。

更新版本

发布新版本时：

1. 更新 package.json 和 server.json 中的版本号
2. 创建并推送新标签：

npm version patch   # or minor / major
git push origin v$(node -p "require('./package.json').version")

---

项目结构

handbook-mcp-server/
├── .github/workflows/
│   └── publish.yml          # CI/CD: npm + MCP Registry
├── src/
│   ├── index.ts             # Entry point (stdio + HTTP)
│   ├── constants.ts         # API URL, limits
│   ├── types.ts             # TypeScript interfaces
│   ├── schemas/
│   │   └── handbook-entry.ts # Zod validation schemas
│   ├── services/
│   │   ├── api-client.ts    # HTTP client for the Handbook API
│   │   └── formatting.ts    # Markdown formatting
│   └── tools/
│       └── handbook-entry.ts # Tool registrations
├── dist/                    # Compiled JS files
├── package.json
├── tsconfig.json
├── server.json              # MCP Registry metadata
└── README.md

---

开发

# Install dependencies
npm install

# Build TypeScript (one-time)
npm run build

# TypeScript watch mode
npm run dev

# Start server (stdio)
npm start

# Start server (HTTP)
TRANSPORT=http npm start

---

API 参考

基于 Handbook OpenAPI 规范。

所有端点都需要 Bearer 令牌身份验证。MCP 服务会自动处理身份验证标头——你只需设置 HANDBOOK_API_TOKEN。

---

许可证

MIT