io.github.jannks/handbook
MCP server for the Handbook API β manage handbook entries via CRUD, overview and tag search.
Ask AI about io.github.jannks/handbook
Powered by Claude Β· Grounded in docs
I know everything about io.github.jannks/handbook. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
| Tool | Description |
|---|---|
handbook_list_entries | List all handbook entries |
handbook_get_entry | Retrieve a single entry by ID (including markdown content) |
handbook_create_entry | Create a new entry |
handbook_update_entry | Update an existing entry |
handbook_delete_entry | Delete an entry |
handbook_get_overview | Compact overview of all entries per app |
handbook_search_tags | Search tags across all entries |
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
| Variable | Required | Default | Description |
|---|---|---|---|
HANDBOOK_API_TOKEN | Yes | β | Bearer token for the Handbook API |
HANDBOOK_API_URL | No | https://handbook.ah-oh.com/handbook-api | Base URL of the API |
TRANSPORT | No | stdio | Transport mode: stdio or http |
PORT | No | 3000 | Port for HTTP transport |
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β fieldsname,mcpName,repository,homepage,bugsserver.jsonβ fieldsname,repository,packages[0].identifierREADME.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:
- Go to npmjs.com β Access Tokens β Create a new token
- In GitHub β Repository β Settings β Secrets and Variables β Actions β Add NPM_TOKEN as a secret
- 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:
- Bump the version in
package.jsonandserver.json - 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
