@kerabie/mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,20 +1,43 @@
 # @kerabie/mcp
 
-An [MCP](https://modelcontextprotocol.io) server for [Kerabie](https://kerabie.com).
+An [MCP](https://modelcontextprotocol.io) server for [Kerabie](https://kerabie.com). Connect Claude, Cursor or any MCP client to build with Kerabie and to work with your account.
 
-- **Build with Kerabie, no API key needed:** search the docs, list REST endpoints, read the TypeScript and React Native SDK types, and get integration guides (`typescript`, `react-native`, `wordpress`, `web-widget`, `rest-api`). Answers come from docs bundled in the package, so they match the SDK version you install.
-- **Work with your account, with `KERABIE_API_KEY`:** conversations, tickets, contacts, campaigns, the Knowledge Base, analytics, AI tools and the MCP servers your chatbot uses. A thin layer over `@kerabie/sdk` and the `/v1` API, so it can do exactly what your key can.
+- **Build with Kerabie, no API key needed:** search the docs, list REST endpoints, read the TypeScript and React Native SDK types, and get integration guides (`typescript`, `react-native`, `wordpress`, `web-widget`, `rest-api`). Answers come from docs bundled in the package, so they match the version you install.
+- **Work with your account, with an API key:** conversations, tickets, contacts, campaigns, the Knowledge Base, analytics, AI tools and the MCP servers your chatbot uses. It is a thin layer over [`@kerabie/sdk`](https://www.npmjs.com/package/@kerabie/sdk) and the `/v1` API, so it can do exactly what your key can, and nothing more.
 
-## Hosted (no install)
+## Hosted (nothing to install)
+
+Point your client at the hosted server and send your API key as a Bearer token.
 
 ```
-POST https://mcp.kerabie.com/mcp
+https://mcp.kerabie.com/mcp
 Authorization: Bearer ker_live_...
 ```
 
-Stateless Streamable HTTP. The caller's key is used for every call and is never stored; with no key only the developer tools are offered; `?readOnly=true` leaves out tools that change data. To host it yourself run `kerabie-mcp-http` (`PORT`, optional `KERABIE_BASE_URL`; `GET /health` for probes) behind TLS.
+**Claude Code**
+
+```bash
+claude mcp add --transport http kerabie https://mcp.kerabie.com/mcp --header "Authorization: Bearer ker_live_..."
+```
+
+**Cursor** (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "kerabie": {
+      "url": "https://mcp.kerabie.com/mcp",
+      "headers": { "Authorization": "Bearer ker_live_..." }
+    }
+  }
+}
+```
+
+Add `?readOnly=true` to the URL to leave out every tool that changes data. With no key, only the developer tools are offered. Your key is used for each call and is never stored.
 
-## Use locally (stdio)
+## Run it locally
+
+Add the server to your MCP client (Claude Desktop, Cursor, Claude Code):
 
 ```json
 {
@@ -28,29 +51,27 @@ Stateless Streamable HTTP. The caller's key is used for every call and is never
 }
 ```
 
+Or add it to Claude Code with `claude mcp add kerabie --env KERABIE_API_KEY=ker_live_... -- npx -y @kerabie/mcp`.
+
 | Variable | |
 |---|---|
-| `KERABIE_API_KEY` | Optional. API key from Settings > API. Without it only the developer tools are offered. |
+| `KERABIE_API_KEY` | Optional. API key from Settings > Integrations > API Keys. Without it only the developer tools are offered. |
 | `KERABIE_ORG_ID` | Optional. Only if the key covers several organisations. |
 | `KERABIE_BASE_URL` | Optional. Defaults to `https://api.kerabie.com`. |
-| `KERABIE_MCP_READ_ONLY` | `true` (or `--read-only`) offers only tools that read. |
+| `KERABIE_MCP_READ_ONLY` | `true` (or pass `--read-only`) offers only tools that read. |
 
-Tools that change data carry the MCP `readOnlyHint: false` annotation, and deleting ones `destructiveHint: true`, so clients can ask before running them. Start read-only.
+To serve it yourself over HTTP, run `kerabie-mcp-http` (set `PORT`, and optionally `KERABIE_BASE_URL`) behind TLS. The endpoint is `POST /mcp`, with `GET /health` for health checks.
 
-Full tool list and docs: https://kerabie.com/docs/sdks/mcp
+## Safety
 
-## Deploy (Cloudflare Workers)
+An MCP client can use every tool your key allows, including ones that reply to customers or delete things. Tools that change data carry the MCP `readOnlyHint: false` annotation, and deleting ones `destructiveHint: true`, so clients can ask before running them. Start read-only, and keep your client's approval prompts on.
 
-`src/worker.ts` is the hosted endpoint; `wrangler.jsonc` serves it at `mcp.kerabie.com`. Every push to `main` runs the tests and deploys through `.github/workflows/deploy-worker.yml`, which needs two repository secrets: `CLOUDFLARE_API_TOKEN` (the "Edit Cloudflare Workers" template) and `CLOUDFLARE_ACCOUNT_ID`.
+API access is on the Pro plan and above.
 
-The build installs `@kerabie/sdk` from npm and uses the docs knowledge committed in `src/generated/`. After changing the docs or the SDK types, run `npm run sync` and commit the result.
+## Documentation
 
-## Develop
+Full tool list and guides: https://kerabie.com/docs/sdks/mcp
 
-```bash
-npm install
-npm run sync        # rebuild src/generated/knowledge.json from the docs, readmes and SDK types
-npm run dev:worker  # run the Worker locally with wrangler
-npm test            # in-process MCP client against the server, SDK faked
-npm run build       # dist/cli.js is the `kerabie-mcp` binary
-```
+## License
+
+MIT

package/package.json

@@ -1,47 +1,47 @@
-{
-  "name": "@kerabie/mcp",
-  "version": "1.0.0",
-  "description": "MCP server for Kerabie: lets Claude, Cursor and other MCP clients work with your conversations, tickets, contacts, campaigns, knowledge base, analytics and AI tools",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "kerabie-mcp": "dist/cli.js",
-    "kerabie-mcp-http": "dist/cli-http.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "keywords": [
-    "kerabie",
-    "mcp",
-    "model-context-protocol",
-    "helpdesk",
-    "customer-support"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "knowledge": "node scripts/build-knowledge.mjs",
-    "build": "node scripts/build-knowledge.mjs && tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "sync": "node scripts/build-knowledge.mjs",
-    "dev:worker": "wrangler dev",
-    "deploy": "wrangler deploy"
-  },
-  "dependencies": {
-    "@kerabie/sdk": "^1.0.1",
-    "@modelcontextprotocol/sdk": "^1.32.1",
-    "zod": "^3.25.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^3.0.0",
-    "wrangler": "^4.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@kerabie/mcp",
+  "version": "1.0.1",
+  "description": "MCP server for Kerabie: lets Claude, Cursor and other MCP clients work with your conversations, tickets, contacts, campaigns, knowledge base, analytics and AI tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "kerabie-mcp": "dist/cli.js",
+    "kerabie-mcp-http": "dist/cli-http.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "kerabie",
+    "mcp",
+    "model-context-protocol",
+    "helpdesk",
+    "customer-support"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "knowledge": "node scripts/build-knowledge.mjs",
+    "build": "node scripts/build-knowledge.mjs && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "sync": "node scripts/build-knowledge.mjs",
+    "dev:worker": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@kerabie/sdk": "^1.0.1",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^3.0.0",
+    "wrangler": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}