aixischeck-mcp 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# aixischeck-mcp
+
+A local [MCP](https://modelcontextprotocol.io) server that lets Claude Desktop create
+documents straight into your [AIxisCheck](https://aixischeck.com) workspace — no manual
+upload. Generate an HTML one-pager in chat, and it lands in your workspace, rendered.
+
+## Tools
+
+- **`list_workspaces`** — lists the workspaces you can write to (`id`, `name`, `role`).
+- **`create_doc`** — `{ workspace_id, title?, content, doc_type? }`. Creates a doc and
+  returns its URL. `doc_type` defaults to `"html"` (a rendered prototype); pass
+  `"markdown"` for a markdown doc.
+
+## Setup
+
+1. In the AIxisCheck web app, go to **Settings → Claude integrations → Generate token**.
+   Copy the token (it's shown once).
+2. Add this to your Claude Desktop config
+   (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+   ```json
+   {
+     "mcpServers": {
+       "aixischeck": {
+         "command": "npx",
+         "args": ["-y", "aixischeck-mcp"],
+         "env": {
+           "AIXIS_TOKEN": "<paste your token from Settings>",
+           "AIXIS_URL": "https://zsmcmjdbncacemtkuzdh.supabase.co"
+         }
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Desktop.
+
+## Use
+
+In Claude Desktop:
+
+> Create an HTML one-pager about our Q3 launch and save it to my workspace.
+
+Claude calls `list_workspaces`, then `create_doc`, and replies with the doc's URL. Open it
+in AIxisCheck — it appears in your doc list (with an "Exploration" pill for HTML) and
+renders faithfully.
+
+## Security
+
+- `AIXIS_TOKEN` is a long-lived, revocable credential — treat it like a password. Revoke it
+  anytime in **Settings → Claude integrations**.
+- The token is only ever stored as a SHA-256 hash on the server; the plaintext lives only in
+  your Claude Desktop config.
+- The server talks to AIxisCheck over HTTPS via a Supabase Edge Function and acts strictly as
+  you — it can only touch workspaces you're a member of.
+
+## Env
+
+| Variable      | Description                                              |
+| ------------- | -------------------------------------------------------- |
+| `AIXIS_TOKEN` | Token from web Settings → Claude integrations.           |
+| `AIXIS_URL`   | Your Supabase project URL (`https://<ref>.supabase.co`). |
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # builds, then runs node:test unit tests
+```
+
+Stdio transport only — no network listener.

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// aixischeck-mcp — a local stdio MCP server for AIxisCheck.
+//
+// Lets Claude Desktop (or any MCP client) create docs straight into an
+// AIxisCheck workspace. Auth is a long-lived opaque token generated in
+// web Settings → Claude integrations, passed as AIXIS_TOKEN. Each tool
+// call hits a Supabase Edge Function that validates the token and acts
+// under the user's identity (RLS-enforced).
+//
+// Env:
+//   AIXIS_TOKEN  — token from web Settings (treat like a password)
+//   AIXIS_URL    — Supabase project URL, e.g. https://<ref>.supabase.co
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildCreateDocBody, createDocShape, edgeErrorMessage, functionUrl } from "./lib.js";
+const AIXIS_TOKEN = process.env.AIXIS_TOKEN ?? "";
+const AIXIS_URL = process.env.AIXIS_URL ?? "";
+if (!AIXIS_TOKEN || !AIXIS_URL) {
+    console.error("aixischeck-mcp: set AIXIS_TOKEN (from web Settings → Claude integrations) and AIXIS_URL (your Supabase project URL).");
+    process.exit(1);
+}
+async function callEdge(name, method, body) {
+    const res = await fetch(functionUrl(AIXIS_URL, name), {
+        method,
+        headers: {
+            Authorization: `Bearer ${AIXIS_TOKEN}`,
+            "Content-Type": "application/json",
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    let payload = null;
+    try {
+        payload = await res.json();
+    }
+    catch {
+        // non-JSON response; leave payload null
+    }
+    if (!res.ok)
+        throw new Error(edgeErrorMessage(res.status, payload));
+    return payload;
+}
+function errorResult(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+const server = new McpServer({ name: "aixischeck-mcp", version: "0.1.0" });
+server.registerTool("list_workspaces", {
+    description: "List the AIxisCheck workspaces you can write to. Returns each workspace's id, name, and your role. Call this first to get a workspace_id for create_doc.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const data = await callEdge("mcp-list-workspaces", "GET");
+        const workspaces = (data && data.workspaces) || [];
+        return { content: [{ type: "text", text: JSON.stringify(workspaces, null, 2) }] };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.registerTool("create_doc", {
+    description: "Create a document in an AIxisCheck workspace from generated content. Defaults to an HTML prototype (doc_type='html'); pass doc_type='markdown' for a markdown doc. Use list_workspaces first to get a workspace_id. Returns the URL of the new doc.",
+    inputSchema: createDocShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-create-doc", "POST", buildCreateDocBody(args));
+        return { content: [{ type: "text", text: `Created. View it at ${data.url}` }] };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lib.js

@@ -0,0 +1,43 @@
+// Pure helpers for the aixischeck-mcp server. Kept free of I/O so they
+// can be unit-tested with node:test (see test/lib.test.mjs).
+import { z } from "zod";
+// Build the Supabase Edge Function URL for a given function name.
+// AIXIS_URL is the project URL (e.g. https://<ref>.supabase.co).
+export function functionUrl(baseUrl, name) {
+    return `${baseUrl.replace(/\/+$/, "")}/functions/v1/${name}`;
+}
+// Input shape for create_doc, shared between the MCP tool registration
+// and validation. doc_type is optional here; the body builder defaults
+// it to 'html' (the Shaed prototype-capture flow).
+export const createDocShape = {
+    workspace_id: z.string().min(1, "workspace_id is required"),
+    title: z.string().optional(),
+    content: z.string().min(1, "content is required"),
+    doc_type: z.enum(["html", "markdown"]).optional(),
+};
+export const CreateDocSchema = z.object(createDocShape);
+// Shape the POST body for the mcp-create-doc edge function, applying
+// the doc_type='html' default and normalizing an absent title to ''.
+export function buildCreateDocBody(input) {
+    return {
+        workspace_id: input.workspace_id,
+        title: input.title ?? "",
+        content: input.content,
+        doc_type: input.doc_type ?? "html",
+    };
+}
+// Map an edge-function error response to a clear, human-readable
+// message for the MCP client. Prefers the server's own { error }
+// string when present.
+export function edgeErrorMessage(status, payload) {
+    const detail = payload && typeof payload === "object" && typeof payload.error === "string"
+        ? payload.error
+        : "";
+    if (status === 401)
+        return detail || "Authentication failed — check AIXIS_TOKEN.";
+    if (status === 403)
+        return detail || "Not allowed to create docs in that workspace.";
+    if (status >= 500)
+        return detail || "AIxisCheck server error. Try again.";
+    return detail || `Request failed (HTTP ${status}).`;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "aixischeck-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for AIxisCheck — create docs in your workspace from Claude Desktop.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aixischeck-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "aixischeck",
+    "claude"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.4.0"
+  }
+}