{
  "markdown": "# handbook-mcp-server\n\nAn [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.\n\n---\n\n## Features\n\n| Tool                    | Description                                                  |\n| ----------------------- | ------------------------------------------------------------ |\n| `handbook_list_entries` | List all handbook entries                                    |\n| `handbook_get_entry`    | Retrieve a single entry by ID (including markdown content)   |\n| `handbook_create_entry` | Create a new entry                                           |\n| `handbook_update_entry` | Update an existing entry                                     |\n| `handbook_delete_entry` | Delete an entry                                              |\n| `handbook_get_overview` | Compact overview of all entries per app                       |\n| `handbook_search_tags`  | Search tags across all entries                               |\n\n---\n\n## Prerequisites\n\n- **Node.js** >= 18\n- **Bearer Token** for the Handbook API\n\n---\n\n## Installation\n\n### Option A: Install from npm\n\n```bash\nnpm install -g @ah-oh/handbook-mcp-server\n```\n\n### Option B: Build from source\n\n```bash\ngit clone https://github.com/ah-oh/handbook-mcp-server.git\ncd handbook-mcp-server\nnpm install\nnpm run build\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable             | Required | Default                                   | Description                           |\n| -------------------- | -------- | ----------------------------------------- | ------------------------------------- |\n| `HANDBOOK_API_TOKEN` | **Yes**  | –                                         | Bearer token for the Handbook API     |\n| `HANDBOOK_API_URL`   | No       | `https://handbook.ah-oh.com/handbook-api` | Base URL of the API                   |\n| `TRANSPORT`          | No       | `stdio`                                   | Transport mode: `stdio` or `http`     |\n| `PORT`               | No       | `3000`                                    | Port for HTTP transport               |\n\n---\n\n## Usage\n\n### Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"handbook\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/handbook-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"HANDBOOK_API_TOKEN\": \"your-bearer-token\"\n      }\n    }\n  }\n}\n```\n\nIf installed globally via npm:\n\n```json\n{\n  \"mcpServers\": {\n    \"handbook\": {\n      \"command\": \"handbook-mcp-server\",\n      \"env\": {\n        \"HANDBOOK_API_TOKEN\": \"your-bearer-token\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add handbook -- node /path/to/handbook-mcp-server/dist/index.js \\\n  --env HANDBOOK_API_TOKEN=your-bearer-token\n```\n\n### VS Code (Copilot / Continue)\n\nIn `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"handbook\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/handbook-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"HANDBOOK_API_TOKEN\": \"your-bearer-token\"\n      }\n    }\n  }\n}\n```\n\n### HTTP Mode (Remote)\n\n```bash\nTRANSPORT=http HANDBOOK_API_TOKEN=your-token PORT=3000 npm start\n```\n\nThe server will listen on `http://localhost:3000/mcp`.\n\n---\n\n## Examples\n\nOnce the MCP server is connected, you can ask Claude things like:\n\n- _\"Show me all handbook entries\"_\n- _\"Create a new entry titled 'Onboarding Guide' for the app szales\"_\n- _\"Update the entry with ID 65c4e1f5... – set the content to ...\"_\n- _\"Which tags start with 'meet'?\"_\n- _\"Give me an overview of all entries for the app sethub\"_\n- _\"Delete entry 65c4e1f5...\"_\n\n---\n\n## Publishing to the MCP Registry\n\nThe official [MCP Registry](https://registry.modelcontextprotocol.io) makes your server discoverable by all MCP clients. Here's the step-by-step guide:\n\n### Step 1: Replace placeholders\n\nReplace `ah-oh` everywhere in the project with your GitHub username:\n\n```bash\n# macOS\nfind . -type f \\( -name \"*.json\" -o -name \"*.md\" \\) \\\n  -exec sed -i '' 's/ah-oh/my-github-user/g' {} +\n\n# Linux\nfind . -type f \\( -name \"*.json\" -o -name \"*.md\" \\) \\\n  -exec sed -i 's/ah-oh/my-github-user/g' {} +\n```\n\nThis affects the following files:\n\n- `package.json` – fields `name`, `mcpName`, `repository`, `homepage`, `bugs`\n- `server.json` – fields `name`, `repository`, `packages[0].identifier`\n- `README.md` – links and install command\n\n### Step 2: Publish to npm\n\n```bash\n# Log in to npm (one-time)\nnpm login\n\n# Publish the package\nnpm publish --access public\n```\n\n> **Note:** The MCP Registry only hosts metadata, not the code itself. Your package must first be available on npm (or PyPI, Docker Hub, etc.).\n\n### Step 3: Install the mcp-publisher CLI\n\n```bash\ncurl -L \\\n  \"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\" \\\n  | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/\n\n# Verify\nmcp-publisher --help\n```\n\n### Step 4: Log in to the registry\n\n```bash\nmcp-publisher login github\n```\n\nThis opens the browser for GitHub OAuth. You'll get access to the namespace `io.github.ah-oh/*`.\n\n> **Alternative** (custom domain, e.g. `com.ah-oh/*`):\n>\n> ```bash\n> # Generate an Ed25519 keypair\n> openssl genpkey -algorithm Ed25519 -out key.pem\n>\n> # Host the public key at https://ah-oh.com/.well-known/mcp-registry-auth\n> # Then:\n> mcp-publisher login http --domain=ah-oh.com --private-key=HEX_KEY\n> ```\n\n### Step 5: Publish\n\n```bash\n# Dry run first\nmcp-publisher publish --dry-run\n\n# Publish for real\nmcp-publisher publish\n```\n\nYour server will then be discoverable at `registry.modelcontextprotocol.io` and automatically picked up by downstream registries (GitHub, VS Code, etc.).\n\n### Step 6 (Optional): Automation via GitHub Actions\n\nThe 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*`).\n\n**Setup:**\n\n1. Go to [npmjs.com](https://www.npmjs.com) → Access Tokens → Create a new token\n2. In GitHub → Repository → Settings → Secrets and Variables → Actions → Add **NPM_TOKEN** as a secret\n3. Tag a release and push:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\nThe pipeline takes care of the rest.\n\n### Updating the version\n\nFor new versions:\n\n1. Bump the version in `package.json` and `server.json`\n2. Create and push a new tag:\n\n```bash\nnpm version patch   # or minor / major\ngit push origin v$(node -p \"require('./package.json').version\")\n```\n\n---\n\n## Project Structure\n\n```\nhandbook-mcp-server/\n├── .github/workflows/\n│   └── publish.yml          # CI/CD: npm + MCP Registry\n├── src/\n│   ├── index.ts             # Entry point (stdio + HTTP)\n│   ├── constants.ts         # API URL, limits\n│   ├── types.ts             # TypeScript interfaces\n│   ├── schemas/\n│   │   └── handbook-entry.ts # Zod validation schemas\n│   ├── services/\n│   │   ├── api-client.ts    # HTTP client for the Handbook API\n│   │   └── formatting.ts    # Markdown formatting\n│   └── tools/\n│       └── handbook-entry.ts # Tool registrations\n├── dist/                    # Compiled JS files\n├── package.json\n├── tsconfig.json\n├── server.json              # MCP Registry metadata\n└── README.md\n```\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript (one-time)\nnpm run build\n\n# TypeScript watch mode\nnpm run dev\n\n# Start server (stdio)\nnpm start\n\n# Start server (HTTP)\nTRANSPORT=http npm start\n```\n\n---\n\n## API Reference\n\nBased on the [Handbook OpenAPI specification](https://handbook.ah-oh.com/handbook-open-api-json/).\n\nAll endpoints require Bearer token authentication. The MCP server handles auth headers automatically – you only need to set `HANDBOOK_API_TOKEN`.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 8095,
  "sha": "75eca5a64ecb69c194d72229826ac10a07822b17f690772fdec4d6b86741abf1",
  "repo_slug": "ah-oh/handbook-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jannks_handbook_cca4644e/readme"
}