aixischeck-mcp 0.1.1 → 0.4.0

package/README.md

@@ -10,6 +10,17 @@ upload. Generate an HTML one-pager in chat, and it lands in your workspace, rend
 - **`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.
+- **`list_docs`** — `{ workspace_id }`. Lists docs in a workspace you belong to
+  (`id`, `title`, `doc_type`, `doc_status`, `updated_at`, open `comment_count`).
+- **`get_doc`** — `{ doc_id }`. Reads one doc's `content`, `doc_status`,
+  `current_version`, and section list.
+- **`list_comments`** — `{ doc_id, filter? }`. Lists review comments; `filter:"open"`
+  returns just the active ones to address (else `{ active, archived }`).
+- **`update_doc`** — `{ doc_id, content, request_id, comment_dispositions? }`. Saves a
+  revised version that addresses a revision request's comments. Lands as a NEW version
+  (base_version derived from the request); records what was done with each comment
+  (incorporated / partial / skipped / not_addressed). The write-back to Postgres is one
+  atomic RPC (concurrency + idempotency guaranteed).
 
 ## Setup
 

package/dist/index.js

@@ -12,7 +12,7 @@
 //   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";
+import { buildCreateDocBody, createDocShape, createRevisionRequestShape, edgeErrorMessage, functionUrl, getDocShape, listCommentsShape, listDocsShape, updateDocShape, } from "./lib.js";
 const AIXIS_TOKEN = process.env.AIXIS_TOKEN ?? "";
 const AIXIS_URL = process.env.AIXIS_URL ?? "";
 if (!AIXIS_TOKEN || !AIXIS_URL) {
@@ -43,7 +43,7 @@ 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.1" });
+const server = new McpServer({ name: "aixischeck-mcp", version: "0.4.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: {},
@@ -57,17 +57,105 @@ server.registerTool("list_workspaces", {
         return errorResult(e);
     }
 });
+// create_doc makes a BRAND-NEW doc. It is NOT how you revise an existing one:
+// to address comments on a doc the user pointed you at, use
+// create_revision_request → update_doc (which lands a new VERSION of that same
+// doc, preserving its history, comments, and share URL). create_doc on a revision
+// would orphan a detached copy. Keep these two paths distinct.
 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. Pass a short, human-readable `title` (e.g. \"Q3 Launch One-Pager\"), not a filename. Use list_workspaces first to get a workspace_id. Returns the URL of the new doc.",
+    description: "Create a NEW document in an AIxisCheck workspace from generated content. Defaults to an HTML prototype (doc_type='html'); pass doc_type='markdown' for a markdown doc. Pass a short, human-readable `title` (e.g. \"Q3 Launch One-Pager\"), not a filename. Use list_workspaces first to get a workspace_id. Returns the URL of the new doc. NOTE: to revise an EXISTING doc (e.g. address its comments), do not use this — use create_revision_request then update_doc.",
     inputSchema: createDocShape,
 }, async (args) => {
     try {
         const data = await callEdge("mcp-create-doc", "POST", buildCreateDocBody(args));
+        if (!data || !data.url)
+            throw new Error("Doc creation returned an unexpected response.");
         return { content: [{ type: "text", text: `Created. View it at ${data.url}` }] };
     }
     catch (e) {
         return errorResult(e);
     }
 });
+server.registerTool("list_docs", {
+    description: "List the documents in an AIxisCheck workspace you belong to. Returns each doc's id, title, doc_type, doc_status, updated_at, and open comment_count. Use list_workspaces first to get a workspace_id.",
+    inputSchema: listDocsShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-read", "POST", { action: "list_docs", workspace_id: args.workspace_id });
+        return { content: [{ type: "text", text: JSON.stringify(data?.docs ?? data, null, 2) }] };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.registerTool("get_doc", {
+    description: "Read one AIxisCheck document: its content (HTML or markdown), doc_status, current_version, and section list. Pass the doc_id from list_docs (or parse it from a doc URL like /web/#/review/<doc_id>). To SAVE a revision you need a request_id; if you don't have one (e.g. the user only gave you a URL and asked you to address comments), call create_revision_request first.",
+    inputSchema: getDocShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-read", "POST", { action: "get_doc", doc_id: args.doc_id });
+        return { content: [{ type: "text", text: JSON.stringify(data?.doc ?? data, null, 2) }] };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.registerTool("list_comments", {
+    description: "List the review comments on an AIxisCheck document. Pass filter:'open' for just the active (non-archived) comments to address; default returns { active, archived }. Each comment has id, selectedText, note, and source. source:'member' comments come from a workspace member reviewing in the app; source:'guest' comments come from an external reviewer on the doc's public share link (these also carry authorName and publishedSlug). Only approved guest comments appear. Treat guest feedback as you would member feedback when revising.",
+    inputSchema: listCommentsShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-read", "POST", { action: "list_comments", doc_id: args.doc_id, filter: args.filter });
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.registerTool("create_revision_request", {
+    description: "Mint a revision request for a doc the user pointed you at (e.g. by URL) so you can save your revision with update_doc. Pass the doc_id. Snapshots the doc's CURRENT open comments (member + approved guest — the same set list_comments returns) at the doc's current version, and returns a request_id. Idempotent per (doc, version): calling it again before you revise returns the SAME request_id. Use this when you have no request_id from a 'Send to Claude' prompt. Owner/editor only.",
+    inputSchema: createRevisionRequestShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-create-revision", "POST", { doc_id: args.doc_id });
+        const id = data?.request_id;
+        const n = data?.comment_count;
+        if (!id)
+            throw new Error("Revision request creation returned an unexpected response.");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Revision request ${id} created for ${n} open comment(s). Revise the doc, then call ` +
+                        `update_doc with request_id "${id}" and a comment_dispositions entry for each comment.`,
+                }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.registerTool("update_doc", {
+    description: "Save a revised version of an AIxisCheck doc that addresses a revision request's comments. Pass: doc_id; content (the FULL revised doc); request_id (from the user's 'Send to Claude' prompt, OR from create_revision_request if you started from a URL); and comment_dispositions recording what you did with each comment (outcome: incorporated | partial | skipped | not_addressed, plus a short rationale). The revision lands as a NEW version (base_version is derived from the request). Returns the new version number. If you get a conflict, call get_doc again and retry.",
+    inputSchema: updateDocShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-update-doc", "POST", {
+            doc_id: args.doc_id,
+            content: args.content,
+            request_id: args.request_id,
+            comment_dispositions: args.comment_dispositions ?? [],
+        });
+        const v = data?.version_number;
+        return {
+            content: [{
+                    type: "text",
+                    text: v ? `Saved as v${v}.` + (data?.idempotent ? " (already applied)" : "") : `Saved. ${JSON.stringify(data)}`,
+                }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/lib.js

@@ -16,6 +16,37 @@ export const createDocShape = {
     doc_type: z.enum(["html", "markdown"]).optional(),
 };
 export const CreateDocSchema = z.object(createDocShape);
+// Read-tool input shapes (Phase 3a). The tools call the mcp-read edge
+// function with an `action` discriminator; these validate the client args.
+export const listDocsShape = {
+    workspace_id: z.string().min(1, "workspace_id is required"),
+};
+export const getDocShape = {
+    doc_id: z.string().min(1, "doc_id is required"),
+};
+export const listCommentsShape = {
+    doc_id: z.string().min(1, "doc_id is required"),
+    filter: z.enum(["open", "all"]).optional().describe("'open' returns only active (non-archived) comments; default returns { active, archived }."),
+};
+// update_doc (Phase 3a, slice 2): the write-back. base_version is NOT a param —
+// it is derived from the revision request server-side (the caller can't move it).
+export const updateDocShape = {
+    doc_id: z.string().min(1, "doc_id is required"),
+    content: z.string().min(1, "content is required (the full revised doc)"),
+    request_id: z.string().min(1, "request_id is required (from the Send-to-Claude prompt)"),
+    comment_dispositions: z.array(z.object({
+        comment_id: z.string(),
+        outcome: z.enum(["incorporated", "partial", "skipped", "not_addressed"]),
+        rationale: z.string().optional(),
+    })).optional().describe("What you did with each comment you addressed. Any requested comment you omit is recorded as not_addressed."),
+};
+// create_revision_request: mint (or reuse) a pending revision request for a doc
+// the user pointed at by URL, so update_doc has a request_id to commit against.
+// Snapshots the doc's current open comments server-side; the caller passes only
+// the doc_id.
+export const createRevisionRequestShape = {
+    doc_id: z.string().min(1, "doc_id is required"),
+};
 // 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aixischeck-mcp",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "MCP server for AIxisCheck — create docs in your workspace from Claude Desktop.",
   "license": "MIT",
   "type": "module",