@kerabie/mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @kerabie/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server for [Kerabie](https://kerabie.com).
+
+- **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.
+
+## Hosted (no install)
+
+```
+POST 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.
+
+## Use locally (stdio)
+
+```json
+{
+  "mcpServers": {
+    "kerabie": {
+      "command": "npx",
+      "args": ["-y", "@kerabie/mcp"],
+      "env": { "KERABIE_API_KEY": "ker_live_..." }
+    }
+  }
+}
+```
+
+| Variable | |
+|---|---|
+| `KERABIE_API_KEY` | Optional. API key from Settings > API. 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. |
+
+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.
+
+Full tool list and docs: https://kerabie.com/docs/sdks/mcp
+
+## Deploy (Cloudflare Workers)
+
+`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`.
+
+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.
+
+## Develop
+
+```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
+```

package/dist/chunk-4MMO737J.js

@@ -0,0 +1,86 @@
+import {
+  createServer
+} from "./chunk-72BI6YMN.js";
+
+// src/common.ts
+var MAX_BODY_BYTES = 1e6;
+function bearerKey(header) {
+  const m = /^Bearer\s+(\S+)$/i.exec(header ?? "");
+  return m ? m[1] : null;
+}
+var CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, Accept, Mcp-Protocol-Version",
+  "Access-Control-Max-Age": "86400"
+};
+
+// src/http.ts
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { KerAbieClient } from "@kerabie/sdk";
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { "Content-Type": "application/json", ...CORS, ...headers });
+  res.end(JSON.stringify(body));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(Object.assign(new Error("Request body too large"), { status: 413 }));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      } catch {
+        reject(Object.assign(new Error("Body must be JSON"), { status: 400 }));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function createHttpHandler(opts = {}) {
+  return async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname === "/health") return send(res, 200, { ok: true });
+    if (url.pathname !== "/mcp") return send(res, 404, { error: "Not found. The MCP endpoint is POST /mcp." });
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, CORS);
+      res.end();
+      return;
+    }
+    if (req.method !== "POST") return send(res, 405, { jsonrpc: "2.0", error: { code: -32e3, message: "Use POST." }, id: null }, { Allow: "POST, OPTIONS" });
+    let body;
+    try {
+      body = await readBody(req);
+    } catch (e) {
+      return send(res, e?.status ?? 400, { jsonrpc: "2.0", error: { code: -32700, message: e?.message ?? "Bad request" }, id: null });
+    }
+    const key = bearerKey(req.headers.authorization);
+    const client = key ? new KerAbieClient({ apiKey: key, baseUrl: opts.baseUrl }) : null;
+    const server = createServer(client, { readOnly: url.searchParams.get("readOnly") === "true", version: opts.version });
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    try {
+      await server.connect(transport);
+      for (const [k, v] of Object.entries(CORS)) res.setHeader(k, v);
+      await transport.handleRequest(req, res, body);
+    } catch {
+      if (!res.headersSent) send(res, 500, { jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
+    }
+  };
+}
+
+export {
+  bearerKey,
+  createHttpHandler
+};