cmskite-mcp 0.1.0 → 0.1.1

package/README.md

@@ -7,7 +7,29 @@ content surface behind one agent token.
 
 Create a token in the dashboard under **Settings → Agent tokens**. Tick only
 what the assistant needs; the defaults are read and write content. The token is
-shown once.
+shown once, and that dialogue generates the block below for whichever client you
+pick — **Set up a client** on the same screen shows it again afterwards.
+
+Every client runs the same process. They disagree only about where it is written
+and under what key, and a block copied from the wrong one pastes without
+complaint and then does nothing.
+
+### Claude Code
+
+```sh
+claude mcp add cmskite --scope user \
+  --env CMSKITE_API_URL=https://api.cmskite.com \
+  --env CMSKITE_AGENT_TOKEN=cka_live_… \
+  -- npx -y cmskite-mcp
+```
+
+`--scope user` puts it in every project. Drop it to add it to one repository.
+
+### Claude Desktop, Cursor, Windsurf, and most others
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` ·
+`%APPDATA%\Claude\claude_desktop_config.json` · `~/.cursor/mcp.json` ·
+`~/.codeium/windsurf/mcp_config.json`
 
 ```jsonc
 {
@@ -24,6 +46,65 @@ shown once.
 }
 ```
 
+Claude Desktop reads that file only at start-up, so quit it completely and open
+it again.
+
+### Codex CLI
+
+`~/.codex/config.toml` — TOML, and the only one here that does not take the
+block above.
+
+```toml
+[mcp_servers.cmskite]
+command = "npx"
+args = ["-y", "cmskite-mcp"]
+
+[mcp_servers.cmskite.env]
+CMSKITE_API_URL = "https://api.cmskite.com"
+CMSKITE_AGENT_TOKEN = "cka_live_…"
+```
+
+### VS Code
+
+`.vscode/mcp.json` — the key is `servers`, not `mcpServers`, and the transport
+is named.
+
+```jsonc
+{
+  "servers": {
+    "cmskite": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "cmskite-mcp"],
+      "env": {
+        "CMSKITE_API_URL": "https://api.cmskite.com",
+        "CMSKITE_AGENT_TOKEN": "cka_live_…"
+      }
+    }
+  }
+}
+```
+
+### Zed
+
+Settings (`cmd-shift-p` → “open settings”) — context servers, marked custom.
+
+```jsonc
+{
+  "context_servers": {
+    "cmskite": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "cmskite-mcp"],
+      "env": {
+        "CMSKITE_API_URL": "https://api.cmskite.com",
+        "CMSKITE_AGENT_TOKEN": "cka_live_…"
+      }
+    }
+  }
+}
+```
+
 | Variable | |
 |---|---|
 | `CMSKITE_AGENT_TOKEN` | Required. Starts `cka_`. A `csk_` value is a project API key: read-only, one project, and rejected here. |
@@ -41,9 +122,27 @@ shown once.
 **Content** — `list_posts`, `get_post`, `search_posts`, `create_post`,
 `update_post`, `delete_post`
 
+**Keys** — `list_api_keys`, `create_api_key`
+
+**Connecting a website** — `get_integration_guide`, `check_integration`,
+`get_content_analytics`
+
 Start with `whoami`, then `list_projects` for a `prj_…` id. Every content tool
 needs one unless `CMSKITE_PROJECT_ID` is set.
 
+### Connecting a website
+
+`get_integration_guide` returns the files to write for the project in front of
+you. It answers for JavaScript with the `cmskite` package, and for PHP,
+WordPress, Laravel, Python or a plain HTML site with the raw HTTP calls — those
+need no dependency at all.
+
+`check_integration` is the one to finish with, and the one to start with when
+somebody says their views are zero. An integration has two halves: the server
+fetches content, and the reader's browser reports the view. Building only the
+first produces a site that works perfectly and counts nobody, with no error
+anywhere to find. Nothing else can tell those two states apart.
+
 Each tool needs the matching grant, and a token has only what was ticked:
 
 | Tool | Grant |
@@ -54,10 +153,23 @@ Each tool needs the matching grant, and a token has only what was ticked:
 | `create_workspace` | `workspace.create` |
 | `list_*`, `get_post`, `search_posts` | `content.read` |
 | `create_*`, `update_*` | `content.write` |
+| `update_post` with `status: "published"` | `content.publish`, on top of `content.write` |
 | `delete_*` | `content.delete` |
+| `list_api_keys` | `apikey.read` |
+| `create_api_key` | `apikey.write` |
+| `check_integration` | `project.read` |
+| `get_content_analytics` | `analytics.read` |
+| `get_integration_guide` | none — it reads nothing and changes nothing |
 
 New posts are drafts. Publishing is `update_post` with `status: "published"` —
-a separate step, because publishing is a decision the person should make.
+a separate step, because publishing is a decision the person should make, and a
+separate grant, so an assistant can be allowed to draft without being allowed to
+ship.
+
+The member's own permissions are checked as well, fresh on every request. A
+token ticked for `content.publish` held by somebody whose role does not include
+it publishes nothing: the grant list is a ceiling on what its owner can already
+do, never an addition to it.
 
 ## What it cannot do
 
@@ -65,8 +177,18 @@ This server adds no permissions. Every limit is enforced by the API on every
 request: the token's grant list, the member's current role, the one workspace
 the token is bound to, and the plan.
 
-No token can mint or revoke credentials, delete a project, or delete a
-workspace — not at any role and not with any configuration. See
+No token can revoke credentials, invite or remove a member, change anybody's
+permissions, delete a project, or delete a workspace — not at any role and not
+with any configuration.
+
+`create_api_key` is the one credential an agent can mint, and only with the
+grant ticked. What it produces is strictly weaker than the token that made it:
+one project, read-only, published content only, no ability to revoke anything.
+It exists so that finishing a site does not require shipping the agent token —
+which can write and delete — to production.
+
+A token also cannot reach a project its owner was not admitted to. Project
+access belongs to the person, and the token acts as them. See
 `docs/agents-and-mcp.md` in the API repository.
 
 `create_workspace` returns a **new** token for the workspace it created. The

package/dist/tools/diagnose.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { segment } from '../client.js';
+import { defineTool } from './register.js';
+/**
+ * Whether the work actually worked.
+ *
+ * Every other tool here changes something and reports that it changed it. None
+ * of them could tell anybody whether the result was a working website, and the
+ * failure this product has is specifically one that reports success: an
+ * assistant creates a project, writes eight posts, mints a key and wires up the
+ * content fetching, and every one of those steps succeeds. The tracker is a
+ * separate snippet, nothing asked for it, and so nobody added it. The site
+ * works. Every post reads zero views. There is no error anywhere to find.
+ *
+ * So `check_integration` exists to make that state something a tool can say out
+ * loud. It is the last call of any integration, and the first call of "why are
+ * my views zero".
+ */
+export const diagnosticTools = [
+    defineTool({
+        name: 'check_integration',
+        title: 'Is this project actually working?',
+        description: 'Checks whether a project is really connected to a website: does it have a key, has a ' +
+            'site ever used it, and are views arriving from the pages that render the content. ' +
+            'Each check comes back with the one action that fixes it. ' +
+            'ALWAYS call this after wiring up an integration, and always when somebody says views or ' +
+            'analytics are zero — a site can fetch content perfectly and report nothing, and this is ' +
+            'the only thing that tells the difference. Requires the project.read grant.',
+        input: { projectId: z.string().describe('The project id, as `prj_...`.') },
+        readOnly: true,
+        run: (client, args) => client.request(`/v1/projects/${segment(args.projectId)}/integration-health`),
+    }),
+    defineTool({
+        name: 'get_content_analytics',
+        title: 'Views, uniques and clicks',
+        description: 'What readers did with a project’s posts over a date range: totals, a daily series, and ' +
+            'the posts that were actually read. Read from rollups, so the answer is the same size ' +
+            'whatever the traffic was. If everything is zero, call check_integration — that is a ' +
+            'tracking problem far more often than it is a traffic problem. Requires the ' +
+            'analytics.read grant.',
+        input: {
+            projectId: z.string().describe('The project id, as `prj_...`.'),
+            from: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe('Inclusive UTC day. Defaults to 30 days ago.'),
+            to: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe('Inclusive UTC day. Defaults to today.'),
+            topPosts: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('How many of the best-read posts to include. Defaults to 10.'),
+        },
+        readOnly: true,
+        run: async (client, args) => {
+            const query = { projectId: args.projectId, from: args.from, to: args.to };
+            // Two calls rather than one, because the summary and the leaderboard are
+            // different shapes and an assistant asking "how is the blog doing" wants
+            // both. They are independent reads and nothing here mutates, so they go
+            // together.
+            const [summary, top] = await Promise.all([
+                client.request('/v1/analytics/content/summary', { query }),
+                client.request('/v1/analytics/content/top-posts', {
+                    query: { ...query, limit: args.topPosts ?? 10 },
+                }),
+            ]);
+            return { summary, topPosts: top };
+        },
+    }),
+];
+//# sourceMappingURL=diagnose.js.map

package/dist/tools/diagnose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.js","sourceRoot":"","sources":["../../src/tools/diagnose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU,CAAC;QACT,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,mCAAmC;QAC1C,WAAW,EACT,uFAAuF;YACvF,oFAAoF;YACpF,2DAA2D;YAC3D,0FAA0F;YAC1F,0FAA0F;YAC1F,4EAA4E;QAC9E,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC,EAAE;QAC1E,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CACpB,MAAM,CAAC,OAAO,CAAC,gBAAgB,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC;KAC/E,CAAC;IAEF,UAAU,CAAC;QACT,IAAI,EAAE,uBAAuB;QAC7B,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,yFAAyF;YACzF,uFAAuF;YACvF,sFAAsF;YACtF,6EAA6E;YAC7E,uBAAuB;QACzB,KAAK,EAAE;YACL,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;YAC/D,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,EAAE;iBACV,QAAQ,CAAC,6CAA6C,CAAC;YAC1D,EAAE,EAAE,CAAC;iBACF,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,EAAE;iBACV,QAAQ,CAAC,uCAAuC,CAAC;YACpD,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,EAAE,CAAC;iBACP,QAAQ,EAAE;iBACV,QAAQ,CAAC,6DAA6D,CAAC;SAC3E;QACD,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;YAC1B,MAAM,KAAK,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAA;YACzE,yEAAyE;YACzE,yEAAyE;YACzE,wEAAwE;YACxE,YAAY;YACZ,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBACvC,MAAM,CAAC,OAAO,CAAU,+BAA+B,EAAE,EAAE,KAAK,EAAE,CAAC;gBACnE,MAAM,CAAC,OAAO,CAAU,iCAAiC,EAAE;oBACzD,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE;iBAChD,CAAC;aACH,CAAC,CAAA;YACF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAA;QACnC,CAAC;KACF,CAAC;CACM,CAAA"}

package/dist/tools/index.js

@@ -1,3 +1,6 @@
+import { diagnosticTools } from './diagnose.js';
+import { integrationTools } from './integrate.js';
+import { keyTools } from './keys.js';
 import { postTools } from './posts.js';
 import { taxonomyTools } from './taxonomy.js';
 import { workspaceTools } from './workspace.js';
@@ -5,6 +8,16 @@ import { workspaceTools } from './workspace.js';
  * Every tool, in the order an assistant meeting a workspace for the first time
  * would want them: find out where you are, then what is here, then change it.
  *
+ * Integration is last and used first, which is the one exception: an assistant
+ * asked to "add a blog to this site" should call `get_integration_guide` before
+ * it writes a line, because the alternative is a hand-rolled fetch wrapper that
+ * works and counts no readers -- a customer gets a working site with no
+ * analytics and nothing indicating that anything is missing.
+ *
+ * Diagnostics come after integration for the same reason integration comes
+ * last: `check_integration` is what an assistant calls once it thinks it has
+ * finished, and what it calls first when somebody says the numbers are zero.
+ *
  * Media is deliberately absent. Uploading goes to object storage through a
  * presigned URL, so it is two calls and a byte stream, and an assistant that
  * cannot see the file has nothing useful to send. When it is added it belongs
@@ -14,6 +27,9 @@ export const allTools = [
     ...workspaceTools,
     ...taxonomyTools,
     ...postTools,
+    ...keyTools,
+    ...integrationTools,
+    ...diagnosticTools,
 ];
 export { registerTools } from './register.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAG/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,cAAc;IACjB,GAAG,aAAa;IAChB,GAAG,SAAS;CACS,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAG/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,cAAc;IACjB,GAAG,aAAa;IAChB,GAAG,SAAS;IACZ,GAAG,QAAQ;IACX,GAAG,gBAAgB;IACnB,GAAG,eAAe;CACG,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}