io.github.jannks/handbook

Install

Config snippet generator goes here (5 client tabs)

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 \