clutter-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clutter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# clutter-mcp — Clutter MCP server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) **stdio** server that lets an AI agent
+drive the whole [Clutter](https://clutter.run) pipeline — invent a believable synthetic company,
+mass-produce the documents, spreadsheets, emails, images and datasets it would really have, poll for
+completion, and fetch download URLs — through Clutter's public REST API, authenticated with an API key.
+
+Use it to fill dev/test/demo systems (SharePoint, CRMs, file shares) with realistic content, or to
+give an agent believable data to reason over — without using real data.
+
+It's a thin HTTPS client with **no dependency on the rest of the Clutter codebase**.
+
+## Quick start
+
+1. Create a free account at **https://clutter.run**, open **Settings**, and mint an API key
+   (`clt_live_…`, shown once).
+2. Add the server to your MCP client config (Claude Code, Claude Desktop, etc.):
+
+```json
+{
+  "mcpServers": {
+    "clutter": {
+      "command": "npx",
+      "args": ["-y", "clutter-mcp"],
+      "env": {
+        "CLUTTER_API_KEY": "clt_live_…"
+      }
+    }
+  }
+}
+```
+
+That's it — `CLUTTER_API_URL` defaults to `https://clutter.run/api`, so only the key is required.
+
+## Configuration
+
+| Env var           | Required | Default                   | Notes                                          |
+| ----------------- | -------- | ------------------------- | ---------------------------------------------- |
+| `CLUTTER_API_KEY` | yes      | —                         | `clt_live_…` key (web app → **Settings**)      |
+| `CLUTTER_API_URL` | no       | `https://clutter.run/api` | Override only to target another deployment      |
+
+## Run directly
+
+```bash
+CLUTTER_API_KEY=clt_live_… npx -y clutter-mcp
+```
+
+## Typical agent flow
+
+1. `build_org` — describe a company in a sentence → returns an `orgId` (omit `projectId` to
+   auto-create a project). Free.
+2. `wait_for_org` — block until the company build is `ready`.
+3. `create_run` — generate content against the company:
+   - `doc_generator` → a batch of documents (`docx`/`pdf`/`xlsx`/`eml`/`jpg`), folder-organised.
+   - `data_generator` → one tabular dataset (`xlsx`/`csv`/`json`) with an exact row count.
+   - `doc_metadata_gen` → one metadata record per document of a prior doc run.
+4. `wait_for_run` — block until the run is `complete`.
+5. `list_run_documents` + `get_document_url`, or `build_zip` + `get_zip_url` for the whole run as a
+   single ZIP (folder tree preserved — ready to drop into SharePoint or a file share).
+
+## Tools
+
+- **Identity / usage:** `clutter_whoami`, `get_usage`
+- **Projects:** `list_projects`, `create_project`
+- **Companies:** `list_orgs`, `build_org`, `get_org`, `wait_for_org`, `query_org`, `delete_org`
+- **Runs:** `list_runs`, `create_run`, `get_run`, `wait_for_run`, `list_run_documents`,
+  `get_document_url`, `build_zip`, `get_zip_url`, `delete_run`
+
+`build_org` and `create_run` are asynchronous (return an id immediately); use the `wait_for_*` tools
+to block until a terminal state, or poll `get_org` / `get_run`. Each tool maps to a REST endpoint and
+returns the raw JSON response.
+
+## Billing
+
+Company builds, metadata and "ask the company" are free. New accounts get 10 free documents + 100
+free data rows, then pay-as-you-go ($0.10/document, $0.06/10 data rows). A `402` from `create_run`
+means insufficient credit — top up at https://clutter.run/billing.
+
+## Reference
+
+Full REST API: **https://clutter.run/api/docs** (Swagger UI) · machine-readable guide:
+**https://clutter.run/llms.txt**
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+export declare class ClutterClient {
+    private readonly base;
+    private readonly key;
+    constructor(baseUrl: string, apiKey: string);
+    static fromEnv(): ClutterClient;
+    request(method: string, path: string, body?: unknown): Promise<unknown>;
+    get(path: string): Promise<unknown>;
+    post(path: string, body?: unknown): Promise<unknown>;
+    del(path: string): Promise<unknown>;
+}
+export declare class ClutterApiError extends Error {
+    status: number;
+    data?: unknown | undefined;
+    constructor(status: number, message: string, data?: unknown | undefined);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AASA,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C,MAAM,CAAC,OAAO,IAAI,aAAa;IAOzB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB7E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAGnC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAGpD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGpC;AAED,qBAAa,eAAgB,SAAQ,KAAK;IAE/B,MAAM,EAAE,MAAM;IAEd,IAAI,CAAC,EAAE,OAAO;gBAFd,MAAM,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACR,IAAI,CAAC,EAAE,OAAO,YAAA;CAIxB"}

package/dist/client.js

@@ -0,0 +1,70 @@
+/**
+ * Tiny REST client for the Clutter API, used by the MCP server. Deliberately has NO dependency on
+ * @clutter/core — the MCP server is a standalone process an AI agent runs locally, talking to the
+ * deployed API over HTTPS with an API key. Configured from env:
+ *   CLUTTER_API_URL  base URL including the /api prefix. Defaults to https://clutter.run/api
+ *                    (the public deployment); override only to target another deployment.
+ *   CLUTTER_API_KEY  a clt_live_… key minted in the web app (Settings) or POST /api-keys (required).
+ */
+const DEFAULT_API_URL = "https://clutter.run/api";
+export class ClutterClient {
+    base;
+    key;
+    constructor(baseUrl, apiKey) {
+        this.base = baseUrl.replace(/\/+$/, "");
+        this.key = apiKey;
+    }
+    static fromEnv() {
+        const base = process.env.CLUTTER_API_URL || DEFAULT_API_URL;
+        const key = process.env.CLUTTER_API_KEY;
+        if (!key)
+            throw new Error("CLUTTER_API_KEY is not set (mint one in the web app → Settings)");
+        return new ClutterClient(base, key);
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.key}`,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        const data = text ? safeJson(text) : undefined;
+        if (!res.ok) {
+            const detail = data && typeof data === "object" && "error" in data
+                ? String(data.error)
+                : res.statusText;
+            throw new ClutterApiError(res.status, detail, data);
+        }
+        return data;
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    post(path, body) {
+        return this.request("POST", path, body ?? {});
+    }
+    del(path) {
+        return this.request("DELETE", path);
+    }
+}
+export class ClutterApiError extends Error {
+    status;
+    data;
+    constructor(status, message, data) {
+        super(`HTTP ${status}: ${message}`);
+        this.status = status;
+        this.data = data;
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ClutterApiError, ClutterClient } from "./client.js";
+/**
+ * Clutter MCP server (Phase 6). A stdio MCP server that lets an AI agent drive the whole Clutter
+ * pipeline — create a project, build a synthetic org, generate documents/data/metadata, poll for
+ * completion, and fetch download URLs — by calling the public REST API with an API key.
+ *
+ * Run it from any MCP client (Claude Desktop/Code, etc.) with:
+ *   CLUTTER_API_URL=https://<host>/api  CLUTTER_API_KEY=clt_live_…  clutter-mcp
+ *
+ * Each tool maps 1:1 to a REST endpoint and returns the raw JSON response as text. The async
+ * contract is exposed both as raw poll tools (get_org/get_run) and as convenience waiters
+ * (wait_for_org/wait_for_run) that block until a terminal state so an agent needn't hand-roll a loop.
+ */
+const client = ClutterClient.fromEnv();
+const server = new McpServer({ name: "clutter", version: "1.0.0" });
+const ok = (data) => ({
+    content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }],
+});
+const fail = (message) => ({
+    content: [{ type: "text", text: message }],
+    isError: true,
+});
+/** Wrap a tool body so any API/network error becomes a clean isError result the agent can read. */
+function tool(name, config, run) {
+    server.registerTool(name, config, async (args) => {
+        try {
+            return ok(await run(args));
+        }
+        catch (err) {
+            if (err instanceof ClutterApiError) {
+                return fail(`Clutter API error (${err.status}): ${err.message}`);
+            }
+            return fail(`Error: ${err.message}`);
+        }
+    });
+}
+const enc = encodeURIComponent;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// ---- Identity + usage ----
+tool("clutter_whoami", {
+    title: "Who am I",
+    description: "Return the authenticated Clutter user for the configured API key.",
+    inputSchema: {},
+}, () => client.get("/me"));
+tool("get_usage", {
+    title: "Get API usage",
+    description: "Your Clutter API usage (request counts by route) over a rolling window + the daily quota.",
+    inputSchema: { windowHours: z.number().int().min(1).max(720).optional() },
+}, (a) => client.get(`/usage${a.windowHours ? `?windowHours=${a.windowHours}` : ""}`));
+// ---- Projects ----
+tool("list_projects", {
+    title: "List projects",
+    description: "List all of your Clutter projects (top-level tenant containers).",
+    inputSchema: {},
+}, () => client.get("/projects"));
+tool("create_project", {
+    title: "Create project",
+    description: "Create a new Clutter project. Returns the project (with its id).",
+    inputSchema: { name: z.string().min(1).max(200) },
+}, (a) => client.post("/projects", { name: a.name }));
+// ---- Organisations ----
+tool("list_orgs", {
+    title: "List organisations",
+    description: "List the synthetic organisations in a project.",
+    inputSchema: { projectId: z.string() },
+}, (a) => client.get(`/orgs?projectId=${enc(String(a.projectId))}`));
+tool("build_org", {
+    title: "Build organisation (async)",
+    description: "Start building a synthetic organisation from a prompt. Returns 202 with an orgId. The build " +
+        "runs in the background (minutes) — then poll get_org, or call wait_for_org to block until ready. " +
+        "Omit projectId to auto-create a project (named after the generated company) — the simplest path.",
+    inputSchema: {
+        prompt: z.string().min(1),
+        projectId: z.string().optional().describe("Existing project to build into; OMIT to auto-create one"),
+        projectName: z.string().max(200).optional().describe("Name for the auto-created project (optional)"),
+        locale_language: z.string().optional().describe("BCP-47, e.g. en-US"),
+        target_systems: z.array(z.string()).optional(),
+        ref_org_id: z.string().optional().describe("Build a variant FROM an existing org"),
+        web_search: z
+            .boolean()
+            .optional()
+            .describe("Use web search for real-world grounding (default true; set false to disable)"),
+    },
+}, (a) => client.post("/orgs", {
+    prompt: a.prompt,
+    projectId: a.projectId,
+    projectName: a.projectName,
+    locale_language: a.locale_language,
+    target_systems: a.target_systems,
+    ref_org_id: a.ref_org_id,
+    web_search: a.web_search,
+}));
+tool("get_org", {
+    title: "Get organisation",
+    description: "Get an organisation including its full org.json structure. Check `org.status`.",
+    inputSchema: { orgId: z.string() },
+}, (a) => client.get(`/orgs/${enc(String(a.orgId))}`));
+tool("wait_for_org", {
+    title: "Wait for organisation build",
+    description: "Poll an org until its build reaches a terminal state (ready/failed) or the timeout. " +
+        "Returns the final org summary.",
+    inputSchema: {
+        orgId: z.string(),
+        timeoutSeconds: z.number().int().min(5).max(900).optional().describe("default 600"),
+    },
+}, async (a) => {
+    const deadline = Date.now() + (Number(a.timeoutSeconds) || 600) * 1000;
+    for (;;) {
+        const res = (await client.get(`/orgs/${enc(String(a.orgId))}`));
+        const status = res?.org?.status;
+        if (status === "ready" || status === "failed")
+            return res;
+        if (Date.now() >= deadline)
+            return { timedOut: true, lastStatus: status, org: res?.org };
+        await sleep(5000);
+    }
+});
+tool("query_org", {
+    title: "Query organisation",
+    description: "Ask a grounded natural-language question about an organisation (synchronous answer).",
+    inputSchema: {
+        orgId: z.string(),
+        message: z.string().min(1),
+        locale_language: z.string().optional(),
+    },
+}, (a) => client.post(`/orgs/${enc(String(a.orgId))}/query`, {
+    message: a.message,
+    locale_language: a.locale_language,
+}));
+tool("delete_org", {
+    title: "Delete organisation",
+    description: "Delete an organisation and ALL its runs/artefacts (S3 + DB). Irreversible.",
+    inputSchema: { orgId: z.string() },
+}, (a) => client.del(`/orgs/${enc(String(a.orgId))}`));
+// ---- Runs ----
+tool("list_runs", {
+    title: "List runs",
+    description: "List the generation runs under an organisation.",
+    inputSchema: { orgId: z.string() },
+}, (a) => client.get(`/runs?orgId=${enc(String(a.orgId))}`));
+tool("create_run", {
+    title: "Create generation run (async)",
+    description: "Launch a generation run. Returns 202 with a runId — poll get_run or call wait_for_run.\n" +
+        "kind + params:\n" +
+        "• doc_generator → { prompt, doc_number (≤300), file_types:[docx|pdf|xlsx|eml|jpg], " +
+        "structure:'flat'|'nested', target_system?, allow_underscores? }\n" +
+        "• data_generator → { prompt, row_count (≤2000), data_format:'xlsx'|'csv'|'json', data_fields?, target_system? }\n" +
+        "• doc_metadata_gen → { sourceRunId (a completed doc_generator run), data_format, data_fields?, target_system? }",
+    inputSchema: {
+        orgId: z.string(),
+        kind: z.enum(["doc_generator", "data_generator", "doc_metadata_gen"]),
+        params: z.record(z.unknown()).optional(),
+    },
+}, (a) => client.post("/runs", { orgId: a.orgId, kind: a.kind, params: a.params ?? {} }));
+tool("get_run", {
+    title: "Get run status",
+    description: "Get a run's status + progress counts. Poll this until status is terminal.",
+    inputSchema: { runId: z.string() },
+}, (a) => client.get(`/runs/${enc(String(a.runId))}`));
+tool("wait_for_run", {
+    title: "Wait for run",
+    description: "Poll a run until it reaches a terminal state (complete/partial/failed) or the timeout. " +
+        "Returns the final run status.",
+    inputSchema: {
+        runId: z.string(),
+        timeoutSeconds: z.number().int().min(5).max(900).optional().describe("default 600"),
+    },
+}, async (a) => {
+    const deadline = Date.now() + (Number(a.timeoutSeconds) || 600) * 1000;
+    const terminal = new Set(["complete", "partial", "failed"]);
+    for (;;) {
+        const res = (await client.get(`/runs/${enc(String(a.runId))}`));
+        const status = res?.run?.status;
+        if (status && terminal.has(status))
+            return res;
+        if (Date.now() >= deadline)
+            return { timedOut: true, lastStatus: status, run: res?.run };
+        await sleep(5000);
+    }
+});
+tool("list_run_documents", {
+    title: "List run documents",
+    description: "List the documents generated by a run (title, format, folderPath, status).",
+    inputSchema: { runId: z.string() },
+}, (a) => client.get(`/runs/${enc(String(a.runId))}/documents`));
+tool("get_document_url", {
+    title: "Get document download URL",
+    description: "Get a short-lived presigned download URL for a single generated document.",
+    inputSchema: { documentId: z.string() },
+}, (a) => client.get(`/documents/${enc(String(a.documentId))}/url`));
+tool("build_zip", {
+    title: "Build run ZIP (async)",
+    description: "Start building a single ZIP of all of a run's documents. Poll get_zip_url after.",
+    inputSchema: { runId: z.string() },
+}, (a) => client.post(`/runs/${enc(String(a.runId))}/zip`));
+tool("get_zip_url", {
+    title: "Get run ZIP URL",
+    description: "Get a presigned download URL for a run's ZIP (409 until the build is ready).",
+    inputSchema: { runId: z.string() },
+}, (a) => client.get(`/runs/${enc(String(a.runId))}/zip/url`));
+tool("delete_run", {
+    title: "Delete run",
+    description: "Delete a run and its artefacts (S3 + DB). Leaves the parent org intact. Irreversible.",
+    inputSchema: { runId: z.string() },
+}, (a) => client.del(`/runs/${enc(String(a.runId))}`));
+// ---- Boot ----
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// Stay alive on stdio; log to stderr so stdout remains a clean MCP channel.
+process.stderr.write("clutter-mcp: connected (stdio)\n");
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "clutter-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Clutter — let an AI agent generate believable synthetic companies, documents, data and metadata (e.g. to fill SharePoint or other test/demo systems) via the Clutter API.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "clutter",
+    "synthetic-data",
+    "test-data",
+    "dummy-data",
+    "synthetic-documents",
+    "sharepoint",
+    "ai-agent",
+    "llm"
+  ],
+  "homepage": "https://clutter.run",
+  "bugs": {
+    "url": "https://clutter.run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelhologram/clutter.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "clutter-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  }
+}