Handbook

handbook-mcp-server

An MCP (Model Context Protocol) server for the Handbook API by ah-oh.com. Enables full management of handbook entries directly from Claude Desktop, Claude Code, VS Code Copilot, and other MCP-compatible clients.

Features

Prerequisites

• Node.js >= 18
• Bearer Token for the Handbook API

Installation

Option A: Install from npm

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

Option B: Build from source

git clone https://github.com/ah-oh/handbook-mcp-server.gitcd handbook-mcp-servernpm installnpm run build

Configuration

Environment Variables

Usage

Claude Desktop

Add the following to your 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"      }    }  }}

If installed globally via 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)

In .vscode/mcp.json:

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

HTTP Mode (Remote)

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

The server will listen on http://localhost:3000/mcp.

Examples

Once the MCP server is connected, you can ask Claude things like:

• "Show me all handbook entries"
• "Create a new entry titled 'Onboarding Guide' for the app szales"
• "Update the entry with ID 65c4e1f5... – set the content to ..."
• "Which tags start with 'meet'?"
• "Give me an overview of all entries for the app sethub"
• "Delete entry 65c4e1f5..."

Publishing to the MCP Registry

The official MCP Registry makes your server discoverable by all MCP clients. Here's the step-by-step guide:

Step 1: Replace placeholders

Replace ah-oh everywhere in the project with your GitHub username:

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

This affects the following files:

• package.json – fields name, mcpName, repository, homepage, bugs
• server.json – fields name, repository, packages[0].identifier
• README.md – links and install command

Step 2: Publish to npm

# Log in to npm (one-time)npm login
# Publish the packagenpm publish --access public

Note: The MCP Registry only hosts metadata, not the code itself. Your package must first be available on npm (or PyPI, Docker Hub, etc.).

Step 3: Install the 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/
# Verifymcp-publisher --help

Step 4: Log in to the registry

mcp-publisher login github

This opens the browser for GitHub OAuth. You'll get access to the namespace io.github.ah-oh/*.

Alternative (custom domain, e.g. com.ah-oh/*):

bash

# Generate an Ed25519 keypairopenssl genpkey -algorithm Ed25519 -out key.pem
# Host the public key at https://ah-oh.com/.well-known/mcp-registry-auth# Then:mcp-publisher login http --domain=ah-oh.com --private-key=HEX_KEY

Step 5: Publish

# Dry run firstmcp-publisher publish --dry-run
# Publish for realmcp-publisher publish

Your server will then be discoverable at registry.modelcontextprotocol.io and automatically picked up by downstream registries (GitHub, VS Code, etc.).

Step 6 (Optional): Automation via GitHub Actions

The project includes a ready-made workflow file at .github/workflows/publish.yml. It automatically publishes to npm and the MCP Registry on every git tag (v*).

Setup:

1. Go to npmjs.com → Access Tokens → Create a new token
2. In GitHub → Repository → Settings → Secrets and Variables → Actions → Add NPM_TOKEN as a secret
3. Tag a release and push:

git tag v1.0.0git push origin v1.0.0

The pipeline takes care of the rest.

Updating the version

For new versions:

1. Bump the version in package.json and server.json
2. Create and push a new tag:

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

Project Structure

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

Development

# Install dependenciesnpm install
# Build TypeScript (one-time)npm run build
# TypeScript watch modenpm run dev
# Start server (stdio)npm start
# Start server (HTTP)TRANSPORT=http npm start

API Reference

Based on the Handbook OpenAPI specification.

All endpoints require Bearer token authentication. The MCP server handles auth headers automatically – you only need to set HANDBOOK_API_TOKEN.

License

MIT