aixischeck-mcp 0.3.0 → 0.5.0

package/README.md

@@ -21,6 +21,15 @@ upload. Generate an HTML one-pager in chat, and it lands in your workspace, rend
   (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).
+- **`create_comments`** — `{ doc_id, origin, items[] }`. Bulk-creates review comments,
+  e.g. from a transcript of a reviewer narrating feedback while reading (such as a
+  Granola recording). Each item needs `section_index` (0-based, from `get_doc`'s
+  `sections`) and an EXACT verbatim `selected_text` quote from that section —
+  paraphrased quotes are rejected, not force-matched. `origin` is `'ai-transcribed'`
+  (matched from a human transcript) or `'ai-generated'`. Up to 20 items per call;
+  each item succeeds or fails independently (`created`/`rejected`, with a reason).
+  Every created comment lands **unconfirmed** — the reviewer must confirm it in the
+  AIxisCheck sidebar before it counts as a real review comment.
 
 ## 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, getDocShape, listCommentsShape, listDocsShape, updateDocShape, } from "./lib.js";
+import { buildCreateDocBody, createCommentsShape, 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.3.0" });
+const server = new McpServer({ name: "aixischeck-mcp", version: "0.5.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,8 +57,13 @@ 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 {
@@ -84,7 +89,7 @@ server.registerTool("list_docs", {
     }
 });
 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. current_version is the value to echo as base_version when revising via update_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 {
@@ -96,7 +101,7 @@ server.registerTool("get_doc", {
     }
 });
 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, and note.",
+    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 {
@@ -107,8 +112,30 @@ server.registerTool("list_comments", {
         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); 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.",
+    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 {
@@ -130,5 +157,31 @@ server.registerTool("update_doc", {
         return errorResult(e);
     }
 });
+server.registerTool("create_comments", {
+    description: "Bulk-create review comments on an AIxisCheck doc — e.g. from a transcript of a reviewer narrating feedback while reading (such as a Granola recording). Call get_doc FIRST to read the doc's actual content and section list: each item's selected_text must be an EXACT, verbatim substring of the target section — do not paraphrase. Set origin:'ai-transcribed' when the feedback came from a human transcript, or 'ai-generated' otherwise. Up to 20 items per call. Items that don't match verbatim (or match ambiguously — the same phrase appears more than once in that section) are rejected individually; the rest of the batch still succeeds. Every created comment lands UNCONFIRMED in the sidebar — the reviewer must confirm it there before it counts as a real review comment.",
+    inputSchema: createCommentsShape,
+}, async (args) => {
+    try {
+        const data = await callEdge("mcp-create-comments", "POST", {
+            doc_id: args.doc_id,
+            origin: args.origin,
+            items: args.items,
+        });
+        const created = Array.isArray(data?.created) ? data.created : [];
+        const rejected = Array.isArray(data?.rejected) ? data.rejected : [];
+        const parts = [`Created ${created.length} comment(s).`];
+        if (rejected.length) {
+            const detail = rejected
+                .map((r) => `item ${r.item_index} (${r.reason})`)
+                .join(", ");
+            parts.push(`${rejected.length} rejected: ${detail}. Re-check each quote against the section's actual ` +
+                "text (via get_doc) and retry those items if needed.");
+        }
+        return { content: [{ type: "text", text: parts.join(" ") }] };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/lib.js

@@ -40,6 +40,34 @@ export const updateDocShape = {
         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"),
+};
+// create_comments (bulk comment import, 2026-07-09): write a batch of
+// AI-matched comments onto a doc's existing sections. section_index is the
+// 0-based index into get_doc's `sections` array (its sections[].id is this
+// same index, stringified) — NOT a free-form id. selected_text must be an
+// EXACT substring of that section's content; the edge function rejects
+// items that don't match verbatim (or match ambiguously) rather than
+// guessing. Every item in one call shares an `origin`, which becomes the
+// created annotation's `source` and determines nothing else server-side —
+// all AI-created comments land unconfirmed regardless of origin.
+export const createCommentsShape = {
+    doc_id: z.string().min(1, "doc_id is required"),
+    origin: z.enum(["ai-transcribed", "ai-generated"]).describe("'ai-transcribed' if these comments were matched from a human transcript (e.g. a Granola recording of the reviewer narrating feedback while reading); 'ai-generated' if there was no human transcript source."),
+    items: z.array(z.object({
+        section_index: z.number().int().min(0).describe("0-based index into the sections array returned by get_doc (sections[].id is this same index, stringified)."),
+        selected_text: z.string().min(1).describe("An EXACT, verbatim substring of that section's content — read the doc with get_doc first; do not paraphrase."),
+        prefix_context: z.string().optional().describe("A few characters immediately before selected_text, to disambiguate if the phrase repeats in the section."),
+        suffix_context: z.string().optional().describe("A few characters immediately after selected_text, to disambiguate if the phrase repeats in the section."),
+        note: z.string().min(1, "note is required"),
+    })).min(1).max(20, "at most 20 comments per call — split larger batches into multiple calls"),
+};
+export const CreateCommentsSchema = z.object(createCommentsShape);
 // 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.3.0",
+  "version": "0.5.0",
   "description": "MCP server for AIxisCheck — create docs in your workspace from Claude Desktop.",
   "license": "MIT",
   "type": "module",