# 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