io.github.jannks/handbook
MCP server for the Handbook API – manage handbook entries via CRUD, overview and tag search.
Open source Open in the app JSON README (API)
About
MCP server for the Handbook API – manage handbook entries via CRUD, overview and tag search.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- jannks
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Last push
- 2026-03-06T06:47:43Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:14
- Updated
- 2026-08-29 04:00:14
- Origin id
io.github.jannks/handbook
README
# handbook-mcp-server
An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for the **Handbook API** by [ah-oh.com](https://handbook.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
```bash
npm install -g @ah-oh/handbook-mcp-server
```
### Option B: Build from source
```bash
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`
```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:
```json
{
"mcpServers": {
"handbook": {
"command": "handbook-mcp-server",
"env": {
"HANDBOOK_API_TOKEN": "your-bearer-token"
}
}
}
}
```
### Claude Code
```bash
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`:
```json
{
"servers": {
"handbook": {
"command": "node",
"args": ["/path/to/handbook-mcp-server/dist/index.js"],
"env": {
"HANDBOOK_API_TOKEN": "your-bearer-token"
}
}
}
}
```
### HTTP Mode (Remote)
```bash
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](https://registry.modelcontextprotocol.io) 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:
```bash
# 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
```bash
# 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
```bash
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
```bash
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
```bash
# 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](https://www.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:
```bash
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:
```bash
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
```bash
# 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](https://handbook.ah-oh.com/handbook-open-api-json/).
All endpoints require Bearer token authentication. The MCP server handles auth headers automatically – you only need to set `HANDBOOK_API_TOKEN`.
---
## License
MIT