{"_id":"@ah-oh/handbook-mcp-server","_rev":"2-9617359572357a12daafdb6d03a26cd3","name":"@ah-oh/handbook-mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@ah-oh/handbook-mcp-server","version":"1.0.0","keywords":["mcp","mcp-server","handbook","model-context-protocol","ai","llm","claude"],"license":"MIT","_id":"@ah-oh/handbook-mcp-server@1.0.0","maintainers":[{"name":"jannks","email":"development@ah-oh.com"}],"homepage":"https://github.com/ah-oh/handbook-mcp-server#readme","bugs":{"url":"https://github.com/ah-oh/handbook-mcp-server/issues"},"bin":{"handbook-mcp-server":"dist/index.js"},"dist":{"shasum":"5a160d0fa767027ed42da02da4ba01090049a4a1","tarball":"https://registry.npmjs.org/@ah-oh/handbook-mcp-server/-/handbook-mcp-server-1.0.0.tgz","fileCount":32,"integrity":"sha512-xfxCNd+B/sT/gw1NrrCTzwy6Dwwrxib8aukzcZTau4+I4JSMx/CxryEsefUGN1HBGSV6K28jQkz71dAmmwOH/Q==","signatures":[{"sig":"MEUCIFF7+p1DY6e3E1c/zF5lNSeqNfiHtvgUrhmp/SUX+Oe7AiEA6Mh+UnaO+OLD503fu7aQgZQ3OoKnEaTUSlYlTcL9O1k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48386},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"8310f645936c858eca68aa5405f4583543cf9630","mcpName":"io.github.ah-oh/handbook","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"jannks","email":"development@ah-oh.com"},"repository":{"url":"git+https://github.com/ah-oh/handbook-mcp-server.git","type":"git"},"_npmVersion":"11.3.0","description":"MCP server for the Handbook API – manage handbook entries (CRUD, overview, tag search) via the Model Context Protocol.","directories":{},"_nodeVersion":"24.2.0","dependencies":{"zod":"^3.24.4","express":"^5.1.0","@modelcontextprotocol/sdk":"^1.12.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.3","@types/express":"^5.0.2"},"_npmOperationalInternal":{"tmp":"tmp/handbook-mcp-server_1.0.0_1772722501667_0.9220054707176153","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ah-oh/handbook-mcp-server","version":"1.0.1","description":"MCP server for the Handbook API – manage handbook entries via CRUD, overview and tag search.","mcpName":"io.github.jannks/handbook","main":"dist/index.js","bin":{"handbook-mcp-server":"dist/index.js"},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch","prepublishOnly":"npm run build"},"keywords":["mcp","mcp-server","handbook","model-context-protocol","ai","llm","claude"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ah-oh/handbook-mcp-server.git"},"homepage":"https://github.com/ah-oh/handbook-mcp-server#readme","bugs":{"url":"https://github.com/ah-oh/handbook-mcp-server/issues"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","express":"^5.1.0","zod":"^3.24.4"},"devDependencies":{"@types/express":"^5.0.2","@types/node":"^22.15.3","typescript":"^5.8.3"},"engines":{"node":">=18"},"_id":"@ah-oh/handbook-mcp-server@1.0.1","gitHead":"d7b069249070879561b0e6302300c077d89e71ff","types":"./dist/index.d.ts","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-a1d74gfEcBIXxYci1WSV/SsngBofeCeohn8QABOTJO/7oo6DtumFfxiHJe4Rx82hU1quycw92Y5yCWRX7ItcJQ==","shasum":"752f44c47f209add85c6c4c194e9dbb00b3ad61d","tarball":"https://registry.npmjs.org/@ah-oh/handbook-mcp-server/-/handbook-mcp-server-1.0.1.tgz","fileCount":32,"unpackedSize":48239,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHMrhO019mEcmjqCc+P4aQVnvhb0sD0QONfevObUT1+qAiBR5SMrc2Y8IGHToOLxgqIO/DspnXKmEBcFB7ofzqzxww=="}]},"_npmUser":{"name":"jannks","email":"development@ah-oh.com"},"directories":{},"maintainers":[{"name":"jannks","email":"development@ah-oh.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/handbook-mcp-server_1.0.1_1772779576384_0.22797741111841807"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T14:55:01.595Z","modified":"2026-03-06T06:46:16.694Z","1.0.0":"2026-03-05T14:55:01.823Z","1.0.1":"2026-03-06T06:46:16.548Z"},"bugs":{"url":"https://github.com/ah-oh/handbook-mcp-server/issues"},"license":"MIT","homepage":"https://github.com/ah-oh/handbook-mcp-server#readme","keywords":["mcp","mcp-server","handbook","model-context-protocol","ai","llm","claude"],"repository":{"type":"git","url":"git+https://github.com/ah-oh/handbook-mcp-server.git"},"description":"MCP server for the Handbook API – manage handbook entries via CRUD, overview and tag search.","maintainers":[{"name":"jannks","email":"development@ah-oh.com"}],"readme":"# 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","readmeFilename":"README.md"}