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.git

cd handbook-mcp-server npm install npm 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:

# 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' {} +

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 package

npm 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/

Verify

mcp-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 keypair

openssl 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 first

mcp-publisher publish --dry-run

Publish for real

mcp-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.0

git 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 / major

git 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 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 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