@rubytech/create-maxy-code 0.1.167 → 0.1.170

package/payload/premium-plugins/writer-craft/mcp/src/index.ts

@@ -0,0 +1,289 @@
+import { initStderrTee } from "../../../../platform/lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("writer-craft");
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { voiceTagContent, AUTHORSHIP_MODES, type AuthorshipMode } from "./tools/voice-tag-content.js";
+import { voiceDistilProfile } from "./tools/voice-distil-profile.js";
+import { voiceRetrieveConditioning } from "./tools/voice-retrieve-conditioning.js";
+import { voiceRecordFeedback } from "./tools/voice-record-feedback.js";
+import { closeDriver } from "./lib/neo4j.js";
+
+const server = new McpServer({
+  name: "maxy-writer-craft",
+  version: "0.1.0",
+});
+
+// Plugin-system boot tolerance — module-init must never throw. Per-call
+// refusal preserves account isolation. Mirrors the memory plugin's
+// pattern (Task 202).
+const accountId = process.env.ACCOUNT_ID ?? null;
+const adminUserIdEnv = process.env.ADMIN_USER_ID ?? null;
+process.stderr.write(
+  `[writer-craft] boot accountId=${accountId ?? "null"} adminUserId=${adminUserIdEnv ?? "null"}\n`,
+);
+
+function refuseNoAccount(toolName: string) {
+  process.stderr.write(
+    `[writer-craft] tool=${toolName} refuse reason=no-account-context\n`,
+  );
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `${toolName} cannot execute: this MCP instance was launched without ACCOUNT_ID. Per-account graph access requires ACCOUNT_ID at spawn.`,
+      },
+    ],
+    isError: true as const,
+  };
+}
+
+function resolveAdminUserId(): string | null {
+  // ADMIN_USER_ID is stamped by the admin session manager at spawn time.
+  // When absent (e.g. specialist subagents), the operator must pass it as
+  // a tool argument or the tools refuse rather than orphan a profile.
+  return adminUserIdEnv;
+}
+
+server.tool(
+  "voice-tag-content",
+  "Stamp authorshipMode on one or many content nodes (:KnowledgeDocument | :Message | :SocialPost) the operator owns. Email threads live as :KnowledgeDocument {source:'email'} since Task 321. Valid modes: human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown.",
+  {
+    nodeIds: z.array(z.string()).min(1).describe("Element IDs of nodes to tag"),
+    mode: z
+      .enum([
+        "human-only",
+        "human-led-agent-assisted",
+        "agent-led-human-reviewed",
+        "agent-only",
+        "unknown",
+      ])
+      .describe("Authorship mode to apply"),
+  },
+  async ({ nodeIds, mode }) => {
+    if (!accountId) return refuseNoAccount("voice-tag-content");
+    try {
+      const result = await voiceTagContent({
+        nodeIds,
+        mode: mode as AuthorshipMode,
+        accountId,
+      });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-tag: mode=${mode} updated=${result.updated} skipped=${result.skipped}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-tag-content failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.tool(
+  "voice-distil-profile",
+  "Two-mode tool (Task 424). mode='sample' (default) walks the operator's human-only corpus, returns the exemplars + recent operator-edit intents for the agent to read. mode='write' persists the YAML style card the agent composed from the sample-mode response. Cadence-guarded: returns skip in 'write' mode without writing if corpus didn't grow ≥20% AND <30 days passed (pass force=true to override).",
+  {
+    adminUserId: z
+      .string()
+      .optional()
+      .describe(
+        "Operator AdminUser identifier. Defaults to ADMIN_USER_ID env from spawn context.",
+      ),
+    force: z
+      .boolean()
+      .optional()
+      .describe("Override cadence guard; rebuild even if recent."),
+    mode: z
+      .enum(["sample", "write"])
+      .optional()
+      .describe("'sample' returns corpus exemplars + feedback for in-turn distillation; 'write' persists the agent-produced styleCardYaml."),
+    styleCardYaml: z
+      .string()
+      .optional()
+      .describe("Required for mode='write'. The YAML style card the agent composed from the sample-mode exemplars + feedback intents."),
+  },
+  async ({ adminUserId, force, mode, styleCardYaml }) => {
+    if (!accountId) return refuseNoAccount("voice-distil-profile");
+    const resolvedAdminUserId = adminUserId ?? resolveAdminUserId();
+    if (!resolvedAdminUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              "voice-distil-profile: adminUserId required (no ADMIN_USER_ID in spawn env).",
+          },
+        ],
+        isError: true,
+      };
+    }
+    try {
+      const result = await voiceDistilProfile({
+        accountId,
+        adminUserId: resolvedAdminUserId,
+        force: force === true,
+        mode,
+        styleCardYaml,
+      });
+      const summary = result.skipped
+        ? (result.exemplars
+            ? `voice-distil sample: corpusSize=${result.corpusSize} exemplars=${result.exemplars.length} feedbackEntries=${result.feedbackEntries}\n${JSON.stringify({ exemplars: result.exemplars, feedbackIntents: result.feedbackIntents }, null, 2)}`
+            : `voice-distil: skipped reason=${result.skipReason} corpusSize=${result.corpusSize}`)
+        : `voice-distil: ok profileId=${result.profileId} corpusSize=${result.corpusSize} feedbackEntries=${result.feedbackEntries} generatedAt=${result.generatedAt}`;
+      return { content: [{ type: "text" as const, text: summary }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-distil-profile failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.tool(
+  "voice-retrieve-conditioning",
+  "Return the operator's style card and K voice-matched exemplars for a drafting brief. K=5 short-form, K=15 long-form. Token-budget bounded. Returns empty {styleCard:null,exemplars:[]} when no profile exists.",
+  {
+    adminUserId: z
+      .string()
+      .optional()
+      .describe("Operator AdminUser identifier. Defaults to ADMIN_USER_ID env."),
+    topic: z
+      .string()
+      .optional()
+      .describe("Drafting topic keyword (filters exemplars to relevant ones)"),
+    format: z
+      .enum(["short", "long"])
+      .describe("Short = email/post (K=5, 16k tokens); long = brochure/prospectus (K=15, 96k tokens)"),
+    register: z.string().optional().describe("Optional register hint"),
+    tokenBudget: z.number().int().positive().optional(),
+  },
+  async ({ adminUserId, topic, format, register, tokenBudget }) => {
+    if (!accountId) return refuseNoAccount("voice-retrieve-conditioning");
+    const resolvedAdminUserId = adminUserId ?? resolveAdminUserId();
+    if (!resolvedAdminUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ styleCard: null, exemplars: [] }),
+          },
+        ],
+      };
+    }
+    try {
+      const result = await voiceRetrieveConditioning({
+        accountId,
+        adminUserId: resolvedAdminUserId,
+        brief: { topic, format, register },
+        tokenBudget,
+      });
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(result) },
+        ],
+      };
+    } catch (err) {
+      // Graceful degradation: callers expect {styleCard:null,exemplars:[]}
+      // on failure, never an error response.
+      process.stderr.write(
+        `[voice-retrieve] tool error: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ styleCard: null, exemplars: [] }),
+          },
+        ],
+      };
+    }
+  },
+);
+
+server.tool(
+  "voice-record-feedback",
+  "Capture an operator's edit on an agent draft. Writes :VoiceEdit linked to :VoiceProfile via :FEEDBACK_FOR. The calling agent supplies `intent` (one sentence describing what the operator changed and what voice preference it reveals); Task 424 moved the diff-intent summarisation into the agent's turn.",
+  {
+    adminUserId: z.string().optional(),
+    originalText: z.string().min(1),
+    editedText: z.string().min(1),
+    intent: z
+      .string()
+      .min(1)
+      .describe("One sentence summarising what changed and what voice preference it reveals — produced by the calling agent in-turn from originalText vs editedText (Task 424)."),
+    skill: z.string().optional().describe("Calling skill name, for provenance"),
+    brief: z.string().optional().describe("Drafting brief that produced the original"),
+  },
+  async ({ adminUserId, originalText, editedText, intent, skill, brief }) => {
+    if (!accountId) return refuseNoAccount("voice-record-feedback");
+    const resolvedAdminUserId = adminUserId ?? resolveAdminUserId();
+    if (!resolvedAdminUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "voice-record-feedback: adminUserId required (no ADMIN_USER_ID in spawn env).",
+          },
+        ],
+        isError: true,
+      };
+    }
+    try {
+      const result = await voiceRecordFeedback({
+        accountId,
+        adminUserId: resolvedAdminUserId,
+        originalText,
+        editedText,
+        intent,
+        context: { skill, brief },
+      });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-record-feedback: editId=${result.editId} intent="${result.intent}" hadProfile=${result.hadProfile}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-record-feedback failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+process.on("SIGTERM", async () => {
+  await closeDriver();
+  process.exit(0);
+});
+
+// Surface AUTHORSHIP_MODES for downstream callers / docs.
+export { AUTHORSHIP_MODES };

package/payload/premium-plugins/writer-craft/mcp/src/lib/neo4j.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal neo4j driver wrapper for the writer-craft MCP server.
+ *
+ * Mirrors the public surface of `platform/plugins/memory/mcp/src/lib/neo4j.ts`:
+ * `getSession()` returns a session, `closeDriver()` releases the singleton.
+ * Password resolution follows the same `PLATFORM_ROOT/config/.neo4j-password`
+ * convention, with an explicit `NEO4J_URI` requirement to avoid silent
+ * cross-account orphaning.
+ */
+import neo4j, { Driver, Session } from "neo4j-driver";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+let driver: Driver | null = null;
+
+function readPassword(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+  const passwordFile = resolve(
+    process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../../../platform"),
+    "config/.neo4j-password",
+  );
+  try {
+    return readFileSync(passwordFile, "utf-8").trim();
+  } catch {
+    throw new Error(
+      `Neo4j password not found. Expected at ${passwordFile} or in NEO4J_PASSWORD env var.`,
+    );
+  }
+}
+
+export function getDriver(): Driver {
+  if (!driver) {
+    const uri = process.env.NEO4J_URI;
+    if (!uri) {
+      throw new Error(
+        "[writer-craft] NEO4J_URI unset — refusing to default to bolt://localhost:7687",
+      );
+    }
+    const user = process.env.NEO4J_USER ?? "neo4j";
+    const password = readPassword();
+    process.stderr.write(`[writer-craft] resolved neo4j_uri=${uri}\n`);
+    driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+  }
+  return driver;
+}
+
+export function getSession(): Session {
+  return getDriver().session();
+}
+
+export async function closeDriver(): Promise<void> {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+}

package/payload/premium-plugins/writer-craft/mcp/src/lib/voice-corpus.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared corpus-filter clause for the voice-mirror tools.
+ *
+ * Imported by `voice-distil-profile` (count + sample walks) and
+ * `voice-retrieve-conditioning` (exemplar walk). The single load-bearing
+ * filter — when the corpus rules change, this is the only place to edit.
+ *
+ * Two predicates:
+ *
+ *   1. `authorshipMode IN ['human-only', 'human-led-agent-assisted']`.
+ *      `human-only` is the operator's own writing verbatim;
+ *      `human-led-agent-assisted` is operator-authored with light agent
+ *      polish, which still carries voice signal (the operator chose the
+ *      claims and the structure). Including this expands the available
+ *      corpus to match how most modern writing actually happens.
+ *
+ *   2. Label is one of the four primary content labels OR is a
+ *      conversation-document `:Section` chunk (unguarded chat voice from
+ *      WhatsApp / Telegram / Signal / Granola / Otter / Circleback etc.
+ *      archives). After the Task 324 collapse, conversation transcripts
+ *      land as `:KnowledgeDocument` parents carrying `conversationIdentity`
+ *      with plain `:Section` children — no `:Conversation` secondary label.
+ *      Conversation-document sections are identified by their parent's
+ *      `conversationIdentity` property via an EXISTS sub-pattern.
+ *      Chat captures voice in a way email rarely does — this is the
+ *      single highest-leverage corpus addition for voice fidelity.
+ *
+ * The clause expects `$accountId` to be bound in the calling cypher
+ * parameters. It does not bind any other parameters.
+ */
+export const VOICE_CORPUS_WHERE = `n.accountId = $accountId
+  AND n.authorshipMode IN ['human-only', 'human-led-agent-assisted']
+  AND (
+    any(lbl IN labels(n) WHERE lbl IN ['KnowledgeDocument', 'Message', 'SocialPost'])
+    OR ('Section' IN labels(n) AND EXISTS {
+      MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
+      WHERE parent.conversationIdentity IS NOT NULL
+    })
+  )`;
+
+/**
+ * The label set the tag tool accepts when stamping `authorshipMode`.
+ * Mirrors the label predicate inside VOICE_CORPUS_WHERE so the tag tool
+ * and the corpus walk stay in lockstep. The tag tool does not filter
+ * by authorshipMode (that's the property it's setting).
+ *
+ * `:Email` retired with Task 321 — email threads now land as
+ * `:KnowledgeDocument {source:'email'}` and are already covered.
+ */
+export const TAGGABLE_PRIMARY_LABELS = [
+  "KnowledgeDocument",
+  "Message",
+  "SocialPost",
+] as const;