@attrkit/mcp 0.2.0 → 0.3.1

package/README.md

@@ -1,14 +1,18 @@
 # @attrkit/mcp
 
-A stdio [MCP](https://modelcontextprotocol.io) server that lets you drive [AttriKit](https://attrikit.io)
-from Codex, Cursor, Gemini, or another MCP client. It is a thin client over AttriKit's public API — it
-holds no database access; your tenant scope is resolved from your secret management key.
+A stdio [MCP](https://modelcontextprotocol.io) server that lets you drive
+[AttrKit](https://attrikit.io) from Codex, Cursor, Gemini, or another MCP client.
+It is a thin client over AttrKit's public API. It holds no database access; your
+tenant scope is resolved from your secret management key.
 
 ## What it exposes
 
+The server provides 36 tools.
+
 | Area | Tools |
 |---|---|
 | Key scope | `whoami` |
+| Workspace usage | `get_usage_cap`, `set_usage_cap` |
 | Apps | `list_apps`, `create_app`, `get_app`, `update_app`, `archive_app` |
 | SDK keys | `get_publishable_key`, `rotate_publishable_key` |
 | Management keys | `list_api_keys`, `create_api_key`, `revoke_api_key` |
@@ -20,14 +24,54 @@ holds no database access; your tenant scope is resolved from your secret managem
 | Outbound webhooks | `list_webhooks`, `create_webhook`, `delete_webhook` |
 | Data export | `export_events` |
 
-`get_campaign_decision` returns the engine's call **verbatim** — the model reports it, it does not recompute it.
+`get_campaign_decision` returns the engine's call verbatim. The model reports it;
+it does not recompute it.
+
+## Before you connect
+
+Create the first workspace management key under
+[Dashboard → Settings → API keys](https://attrikit.io/en/dashboard/settings/api-keys).
+This one-time bootstrap requires the dashboard.
+
+After that first key exists, a workspace-scoped read/write key can manage every
+customer operation available through the Management API. This includes apps,
+delegated keys, usage caps, integrations, and exports.
+
+Use a read-only or app-scoped key when the client needs less access. App-scoped
+keys cannot read or change the workspace usage cap, create sibling apps, or
+manage workspace-wide integrations.
+
+Load the key into the shell that starts your MCP client:
+
+```bash
+printf "AttrKit management key: "
+IFS= read -r -s ATTRKIT_API_KEY
+export ATTRKIT_API_KEY
+printf "\n"
+```
+
+## Codex
+
+Add this server to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.attrkit]
+command = "npx"
+args = ["-y", "@attrkit/mcp"]
+env = { ATTRKIT_API_URL = "https://attrikit.io" }
+env_vars = ["ATTRKIT_API_KEY"]
+```
+
+```bash
+codex mcp get attrkit
+```
+
+See the [Codex setup guide](https://attrikit.io/en/docs/mcp#codex).
 
-## Setup
+## Cursor
 
-1. Obtain one workspace management key (`sk_…`). Once you have that bootstrap key, all operational
-   setup—including apps and delegated app keys—can be completed through MCP without the web dashboard.
-   Keep `write` only on agents that should mutate the workspace.
-2. Add the server to your client config:
+Add the server to `.cursor/mcp.json` for one project or `~/.cursor/mcp.json` for
+every project:
 
 ```json
 {
@@ -36,7 +80,7 @@ holds no database access; your tenant scope is resolved from your secret managem
       "command": "npx",
       "args": ["-y", "@attrkit/mcp"],
       "env": {
-        "ATTRKIT_API_KEY": "sk_your_key_here",
+        "ATTRKIT_API_KEY": "${env:ATTRKIT_API_KEY}",
         "ATTRKIT_API_URL": "https://attrikit.io"
       }
     }
@@ -44,7 +88,47 @@ holds no database access; your tenant scope is resolved from your secret managem
 }
 ```
 
-`ATTRKIT_API_URL` is optional (defaults to `https://attrikit.io`).
+Then enable it and inspect the available tools:
+
+```bash
+cursor-agent mcp list
+cursor-agent mcp list-tools attrkit
+```
+
+See the [Cursor setup guide](https://attrikit.io/en/docs/mcp#cursor).
+
+## Gemini CLI
+
+Add this server to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "attrkit": {
+      "command": "npx",
+      "args": ["-y", "@attrkit/mcp"],
+      "env": {
+        "ATTRKIT_API_KEY": "$ATTRKIT_API_KEY",
+        "ATTRKIT_API_URL": "https://attrikit.io"
+      }
+    }
+  }
+}
+```
+
+```bash
+gemini mcp list
+```
+
+See the [Gemini setup guide](https://attrikit.io/en/docs/mcp#gemini).
+
+## Other MCP clients
+
+Configure a stdio server with command `npx`, arguments
+`["-y", "@attrkit/mcp"]`, and the `ATTRKIT_API_KEY` environment variable.
+Environment-variable interpolation differs between clients, so follow the
+client's secret-handling documentation. `ATTRKIT_API_URL` is optional and
+defaults to `https://attrikit.io`.
 
 ## Test it locally
 
@@ -52,16 +136,40 @@ holds no database access; your tenant scope is resolved from your secret managem
 ATTRKIT_API_KEY=sk_... npx @modelcontextprotocol/inspector npx -y @attrkit/mcp
 ```
 
-The Inspector lists the tools and lets you invoke them against your live workspace.
+The Inspector lists the tools and lets you invoke them against your live
+workspace.
+
+## Access boundaries
+
+| Control | Management API and MCP |
+|---|---|
+| Customer operations after the first key | Available with a workspace-scoped read/write key |
+| First workspace management key | Dashboard bootstrap only |
+| Billing and subscription | Not available |
+| Sign-in and organization membership | Not available |
+| Workspace deletion | Not available |
+| Internal administration | Not available |
+
+See the [Management API guide](https://attrikit.io/en/docs/management-api) and
+[OpenAPI contract](https://attrikit.io/openapi.json) for the complete HTTP
+surface.
 
 ## Notes
 
-- stdio only — no network listener, no port bind.
-- Key scopes gate reads vs writes; a read-only key gets `403 forbidden_scope` on every mutation.
-- App-scoped keys cannot create other apps, reach sibling apps, or manage workspace-wide integrations.
-- App creation, management-key creation, and webhook creation return secret values once. Capture them
-  from the tool result; list tools only return masked metadata.
-- Mutation tools accept an optional `idempotency_key`. Reuse the same value only for an exact retry;
-  one-time secret responses are encrypted at rest and safely replayed.
-- Management keys are protected by distributed per-key global, mutation, and expensive-operation limits.
-- All diagnostics go to stderr (stdout is the MCP transport).
+- stdio only. The package does not open a network port.
+- Key scopes gate reads vs writes. A read-only key gets `403 forbidden_scope` on
+  every mutation.
+- App-scoped keys cannot create other apps, reach sibling apps, or manage
+  workspace-wide integrations.
+- App creation, management-key creation, and webhook creation return secret
+  values once. Capture them from the tool result; list tools only return masked
+  metadata.
+- Mutation tools accept an optional `idempotency_key`. Reuse the same value only
+  for an exact retry. One-time secret responses are encrypted at rest and safely
+  replayed.
+- Management keys are protected by distributed per-key global, mutation, and
+  expensive-operation limits.
+- All diagnostics go to stderr. stdout is reserved for the MCP transport.
+- MCP clients store environment values in local configuration. Never commit a
+  configuration containing a key. Restrict access to the file and revoke any
+  key that is exposed.

package/dist/cli.js

@@ -9,7 +9,7 @@ import { z } from "zod";
 function readConfig(env = process.env) {
   const apiKey = env.ATTRKIT_API_KEY;
   if (!apiKey) {
-    throw new Error("ATTRKIT_API_KEY is required (create one in AttriKit → Settings → API keys).");
+    throw new Error("ATTRKIT_API_KEY is required (create one in AttrKit → Settings → API keys).");
   }
   const apiUrl = (env.ATTRKIT_API_URL ?? "https://attrikit.io").replace(/\/+$/, "");
   return { apiKey, apiUrl };
@@ -61,7 +61,7 @@ function toToolResult(result) {
     const code = envelope?.error?.code ?? `http_${result.status}`;
     const message = envelope?.error?.message ? `: ${envelope.error.message}` : "";
     return {
-      content: [{ type: "text", text: `AttriKit API error (${result.status || "network"}): ${code}${message}` }],
+      content: [{ type: "text", text: `AttrKit API error (${result.status || "network"}): ${code}${message}` }],
       isError: true
     };
   }
@@ -71,9 +71,10 @@ function toToolResult(result) {
     structuredContent: structured
   };
 }
+var SERVER_VERSION = "0.3.1";
 var periodSchema = z.enum(["7d", "30d", "90d", "all"]).describe("Reporting window. Defaults to 30d.").optional();
 var appIdSchema = z.string().describe("Optional app id to scope the result to one app.").optional();
-var requiredAppIdSchema = z.string().describe("The AttriKit app id.");
+var requiredAppIdSchema = z.string().describe("The AttrKit app id.");
 var idempotencyKeySchema = z.string().max(255).describe("Stable retry key for this exact mutation.").optional();
 var ownersSchema = z.record(z.string(), z.enum(["attrkit", "revenuecat", "customer"]));
 var spendRowSchema = z.object({
@@ -88,16 +89,52 @@ var spendRowSchema = z.object({
   spendMinorUnits: z.number().int().nonnegative()
 });
 function createServer(config, fetchImpl) {
-  const server = new McpServer({ name: "attrkit", version: "0.2.0" });
+  const server = new McpServer({ name: "attrkit", version: SERVER_VERSION });
   const call = (path, options) => callApi(config, path, { fetchImpl, ...options });
   server.registerTool("whoami", {
     title: "Inspect management-key scope",
     description: "Return the authenticated workspace, plan, app restriction and read/write scopes.",
     inputSchema: {}
   }, async () => toToolResult(await call("/api/v1/whoami")));
+  server.registerTool("get_usage_cap", {
+    title: "Get the workspace usage cap",
+    description: "Return the workspace's monthly qualified-install cap, alert email, current billing period and usage. Requires a workspace-scoped read key.",
+    inputSchema: {}
+  }, async () => toToolResult(await call("/api/v1/workspace/usage-cap")));
+  server.registerTool("set_usage_cap", {
+    title: "Set the workspace usage cap",
+    description: "Set a monthly qualified-install cap of at least 10,000 and its alert email. Pass null for both values to clear the cap. Requires a workspace-scoped write key.",
+    inputSchema: {
+      monthly_qualified_install_cap: z.number().int().min(1e4).max(Number.MAX_SAFE_INTEGER).nullable(),
+      alert_email: z.string().trim().email().max(320).nullable(),
+      idempotency_key: idempotencyKeySchema
+    }
+  }, async ({
+    monthly_qualified_install_cap,
+    alert_email,
+    idempotency_key
+  }) => {
+    if (monthly_qualified_install_cap === null !== (alert_email === null)) {
+      return {
+        content: [{
+          type: "text",
+          text: "AttrKit usage-cap validation error: set both cap and alert email, or pass null for both to clear them."
+        }],
+        isError: true
+      };
+    }
+    return toToolResult(await call("/api/v1/workspace/usage-cap", {
+      method: "PATCH",
+      idempotencyKey: idempotency_key,
+      body: {
+        monthly_qualified_install_cap,
+        alert_email
+      }
+    }));
+  });
   server.registerTool("list_apps", {
     title: "List apps",
-    description: "List the iOS and Android apps in your AttriKit workspace (id, name, platform, bundle id, store id, status).",
+    description: "List the iOS and Android apps in your AttrKit workspace (id, name, platform, bundle id, store id, status).",
     inputSchema: {}
   }, async () => toToolResult(await call("/api/v1/apps")));
   server.registerTool("create_app", {
@@ -267,7 +304,7 @@ function createServer(config, fetchImpl) {
   })));
   server.registerTool("get_campaign_decision", {
     title: "Get campaign decisions (scale / cut / hold)",
-    description: "Return AttriKit's profit DECISIONS for your campaigns: the scale/cut/hold call and confidence, computed by the attribution engine. Report the `call` VERBATIM — do not recompute or override it; when it says not_enough_data, say so. This is the tool to drive budget automation.",
+    description: "Return AttrKit's profit DECISIONS for your campaigns: the scale/cut/hold call and confidence, computed by the attribution engine. Report the `call` VERBATIM — do not recompute or override it; when it says not_enough_data, say so. This is the tool to drive budget automation.",
     inputSchema: { app_id: appIdSchema }
   }, async ({ app_id }) => toToolResult(await call("/api/v1/decisions", { query: { appId: app_id } })));
   server.registerTool("record_campaign_decision", {
@@ -531,7 +568,7 @@ function createServer(config, fetchImpl) {
   }, async ({ connection_id }) => toToolResult(await call(`/api/v1/integrations/${encodeURIComponent(connection_id)}`, { method: "DELETE" })));
   server.registerTool("get_revenuecat", {
     title: "Get RevenueCat configuration",
-    description: "Return redacted RevenueCat status and the AttriKit webhook URL.",
+    description: "Return redacted RevenueCat status and the AttrKit webhook URL.",
     inputSchema: { app_id: requiredAppIdSchema }
   }, async ({ app_id }) => toToolResult(await call(`/api/v1/apps/${encodeURIComponent(app_id)}/revenuecat`)));
   server.registerTool("configure_revenuecat", {

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@attrkit/mcp",
-  "version": "0.2.0",
-  "description": "AttriKit's stdio MCP server for its public management API",
+  "version": "0.3.1",
+  "description": "AttrKit's stdio MCP server for its public Management API",
+  "keywords": [
+    "attrkit",
+    "attribution",
+    "mcp",
+    "model-context-protocol",
+    "automation",
+    "agent-tools"
+  ],
+  "homepage": "https://attrikit.io/en/docs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KamyarTaher/attrikit.git",
+    "directory": "packages/mcp"
+  },
+  "license": "UNLICENSED",
   "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
   "bin": {
-    "attrkit-mcp": "./dist/cli.js"
+    "attrkit-mcp": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -12,6 +30,7 @@
   ],
   "scripts": {
     "build": "bun build ./src/cli.ts --outdir ./dist --target=node --format=esm --external @modelcontextprotocol/sdk --external zod",
+    "prepack": "bun run build",
     "typecheck": "../../node_modules/typescript-7/bin/tsc --noEmit",
     "test": "cd ../.. && vitest run packages/mcp/src/index.test.ts"
   },
@@ -24,5 +43,8 @@
     "@types/node": "26.1.1",
     "typescript": "6.0.3",
     "vitest": "4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }