handbook

handbook-mcp-server

ah-oh.com の Handbook API 用 MCP（Model Context Protocol）サーバーです。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
• Handbook API の Bearer トークン

---

インストール

オプション 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 トークン
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 レジストリへの公開

公式の 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］→［Create a new token］を選択します
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