io.github.jannks/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/*):

# 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