idiolect-mcp 0.5.0 → 0.5.2

package/README.md

@@ -1,7 +1,8 @@
 # idiolect-mcp
 
-MCP server that makes any MCP-compatible AI (Claude Desktop, Claude Code, …)
-write in **your** voice, using your [Idiolect AI](https://idiolect.app) Voice Card.
+Idiolect AI creates and revises writing through MCP-compatible AI tools. A Writing Profile
+personalizes the result using writing samples, stated preferences, and learned patterns.
+Writing requests do not need a brand mention or an existing profile.
 
 ## Setup
 
@@ -46,8 +47,8 @@ Remote OAuth and account-mode stdio advertise the same user-facing tools.
 Setup state, evidence approval, retries, and idempotency stay inside the server;
 clients receive one `next` action and never coordinate workflow versions or locks.
 
-- **`write`** — writes new prose in the user's Writing Profile or own style.
-- **`rewrite`** — rewrites supplied prose in the user's Writing Profile.
+- **`write`** — drafts writing from requests, facts, notes, or outlines.
+- **`rewrite`** — corrects, summarizes, expands, simplifies, paraphrases, or repurposes existing text.
 - **`refine_writing`** — changes returned writing, applies a template, or records its outcome.
 - **`view_writing_profile`** — lists Writing Profiles and shows the selected or current profile.
 - **`list_writing_samples`** — lists the writing behind one profile.
@@ -61,6 +62,11 @@ clients receive one `next` action and never coordinate workflow versions or lock
 - **`remove_writing_sample`** — revokes one ready or waiting sample.
 - **`delete_writing_profile`** — deletes a selected profile.
 
+Profile creation, approved samples, and lasting preferences can be part of writing and
+revision workflows. They do not require a separate profile-management request. Inferred
+patterns can contribute approved authored examples; they must not become user-stated rules.
+See [the MCP content standard](../docs/MCP-CONTENT-STANDARD.md) for writing and review rules.
+
 Cached account-mode tool names remain callable but are not advertised. Slug mode keeps its
 legacy local-samples catalogue; locally configured samples are used only for stateless scoring
 and are not stored.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "idiolect-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "mcpName": "app.idiolect/idiolect-ai",
   "type": "module",
   "bin": {
     "idiolect-mcp": "server.mjs"
   },
-  "description": "MCP server that gives any MCP-compatible AI (Claude, etc.) your Idiolect AI voice — make AI write as you. https://idiolect.app",
+  "description": "MCP server that gives any MCP-compatible AI (Claude, etc.) your Idiolect AI voice \u2014 make AI write as you. https://idiolect.app",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -24,6 +24,7 @@
   "license": "MIT",
   "files": [
     "server.mjs",
+    "public-contract.js",
     "progressive-catalog.json",
     "README.md"
   ],

package/progressive-catalog.json

@@ -1,10 +1,10 @@
 {
-  "instructions": "Idiolect AI writes prose with the authenticated user's Writing Profile. It changes profile settings only when the user asks.\n\nWriting: call `write` when the user explicitly asks for Idiolect AI, asks to use their Writing Profile, or asks to use their established personal style for new prose. Call `rewrite` for supplied prose under the same trigger. Never use them for ambient writing, code, factual lookup, repository work, sending, publishing, or another person's style.\n\nWhen `write` or `rewrite` returns `needs_setup`, keep the task unchanged and follow `next.action`. If `next.action` is `choose_setup`: Show all five `setupOptions` in the supplied order, numbered 1–5. Keep each label and one-line description. Open with \"How should Idiolect AI write this?\" and lead with the write-now option. End with: Reply with a number, a name, or just write it. Your request is saved; you don't need to repeat it. Then wait for the user to answer. An answer in the chat is enough. Map a number to the option you actually displayed in this conversation, including an older or reordered menu. Map a template name directly. If no template is named, ask which template. Map 'whatever', 'just write it', and 'skip' to `plain`. Do not ask for confirmation. If the user does not want a Writing Profile or a template, select `plain`. If the user explicitly wants a template for all their writing, add `alwaysUse` true to that template; otherwise leave it unset. If they abandon profile setup for plain or a named template, complete the same held request with that choice immediately. Then call the same writing tool with the selected option. For `check_context` or `ask_user`, follow the returned message instead; do not show the five-option setup menu. Set a persistent default only when the user requests one.\n\nWhen a result returns `needs_evidence`, offer three choices. The user may paste writing, answer a few short questions, or approve a search in one source. When the user selects a source, ask permission before access. Show the exact excerpts or answers before sending. Send only approved material. Set `source` and `userApproved`. Exclude AI text, prompts, templates, signatures, quotations, and forwarded text. If the user declines, finish the held request with plain style or their selected template.\n\nWhen the user requests a change to returned writing, call `refine_writing` with its reference. Record an outcome only after the user reports it. Send `finalText` only when their exact final wording is known. Do not request a rating.\n\nWhen the user asks Idiolect AI to remember authored prose, call `add_writing_samples`; if they have no Writing Profile yet, call `create_writing_profile` with it instead. Confirm authorship and storage permission. When the user states a lasting rule, call `add_writing_rule`. A rule without `profile` applies to all profiles. Do not infer a lasting rule from an ordinary conversation or one task.\n\nWhen the user asks to inspect their profiles, call `view_writing_profile`. Call `list_writing_samples` for the writing behind one profile. When the user asks for a profile change, call the one action-led profile tool for that change. Describe the change before calling. The host confirmation for a destructive tool is sufficient; do not add a second confirmation step. Profile tools do not write prose.\n\nPreserve supplied facts and protected wording. Keep the source narrator unless the user requests a change. Ask only for necessary facts, consent, or unresolved ambiguity. Never invent facts, positions, experiences, or opinions.\n\nHost context boundary: use memory, prior chats, connected sources, or files only after the user approves access for this request. After access, show the exact excerpts and ask which may be sent. Send only approved excerpts. Do not send broad history or extra context. The connector never directs another plugin or connector to gather material.",
+  "instructions": "Idiolect AI creates and revises writing for the user. A Writing Profile personalizes the result using writing samples, stated preferences, and learned patterns. The profile tools support continued personalization throughout writing and revision.\n\nUse Idiolect AI for requested writing tasks, including the writing portion of a larger workflow. These span personal, professional, technical, academic, and creative content. Examples include messages, reports, applications, speeches, product copy, and articles. These are examples, not required formats. The user does not need to name Idiolect AI or request a Writing Profile.\n\nFor new writing from requests, facts, notes, or outlines, call `write`. For existing text, call `rewrite`. Changes include corrections, summarization, expansion, simplification, paraphrasing, restructuring, and changes of tone, style, audience, or format. Preserve requests such as 'make this sound like me' or 'make this less AI-written' in `instructions`. An existing Writing Profile is not required to start. Call the writing tool without first checking profile state.\n\nWhen `write` or `rewrite` returns `needs_setup`, keep the task unchanged. Follow `next.action`. For `choose_setup`, follow these steps. Show all five `setupOptions` in the supplied order, numbered 1–5. Keep each label and one-line description. Open with \"How should Idiolect AI write this?\" and lead with the write-now option. End with: Reply with a number, a name, or just write it. Your request is saved; you don't need to repeat it. Then wait for the user to answer. An answer in the chat is enough. Map a number to the option you actually displayed in this conversation, including an older or reordered menu. Map a template name directly. If no template is named, ask which template. Map 'whatever', 'just write it', and 'skip' to `plain`. Do not ask for confirmation. If the user does not want a Writing Profile or a template, select `plain`. If the user explicitly wants a template for all their writing, add `alwaysUse` true to that template; otherwise leave it unset. If they abandon profile setup for plain or a named template, complete the same held request with that choice immediately. Then call the same writing tool with the selected option. For `check_context` or `ask_user`, follow the returned message instead of the setup menu. Set a persistent default only when the user requests one.\n\nWhen a result returns `needs_evidence`, offer pasted writing or short questions. If host rules permit another source, the user can approve access to that source. Before sending material, show the exact excerpts or answers and obtain the required approval. Reuse approval already given for that exact material and purpose. Send only approved material. Set `source` and `userApproved` accurately. Exclude AI text, prompts, templates, signatures, quotations, and forwarded text from learning evidence. If the user declines, finish the held request with plain style or their selected template.\n\nWhen the user requests a change to returned writing, call `refine_writing` with its reference. The user does not need to name Idiolect AI again. Record an outcome only after the user reports it. Send `finalText` only when their exact final wording is known. Do not request a rating.\n\nDevelop personalization during writing and revision workflows, within the user's permission for that material and purpose. When approved authored examples are available, call `add_writing_samples`. If no Writing Profile exists, use `create_writing_profile` instead. A separate profile-management request is not required. When the user states a lasting writing preference, call `add_writing_rule`. Keep their words and stated scope. A rule without `profile` applies to all profiles. For an inferred pattern, contribute its approved authored examples rather than recording an inference as a user-stated rule. Directions for one piece belong to that writing task, not a lasting rule.\n\nWhen profile details are needed for the user's request, call `view_writing_profile`. Use `list_writing_samples` when the supporting writing is needed. Use profile actions to complete authorized writing or personalization workflows. Describe a persistent settings change before calling its tool. The host's destructive-action confirmation is sufficient; do not add another confirmation. Profile tools support writing workflows; they do not themselves generate the requested draft.\n\nPreserve supplied facts and protected wording unless the user requests changes. Keep the source narrator unless the user requests a change. Ask only for necessary facts, required permission, or unresolved ambiguity. Never invent facts, positions, experiences, or opinions. Writing tools return text; they do not send messages or publish content. Respect the user's tool choice and the host's permissions.\n\nHost context boundary: use the current request and data already stored in Idiolect AI. For another source, follow the host's rules and obtain the required approval before access. Show the exact excerpts before sending them. Send only approved, task-relevant material. If the host's source rules are unknown, use only the current request and stored Idiolect AI data. The connector never directs another plugin or connector to gather material.",
   "tools": [
     {
       "name": "write",
       "title": "Write",
-      "description": "Use this when the user asks for new writing in their Writing Profile or their own style.",
+      "description": "Use this when the user needs new writing from a request, facts, notes, or an outline. It returns a draft for the requested purpose, audience, and format. A Writing Profile personalizes the draft when available. If the tool returns a setup step, follow that step.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -37,6 +37,12 @@
             "maxLength": 8000,
             "description": "The user's exact directions about tone, length, structure, or exclusions. Omit when none were given. Put content in `request` and a named output form in `format`."
           },
+          "language": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "The language for the finished writing, in plain words (for example 'French'). Set it only when the user asked for a specific language. Omit it to follow the request's language, or the source text's language for a rewrite."
+          },
           "effects": {
             "type": "array",
             "maxItems": 20,
@@ -1184,7 +1190,7 @@
     {
       "name": "rewrite",
       "title": "Rewrite",
-      "description": "Use this when the user gives text and asks for it in their Writing Profile.",
+      "description": "Use this when the user wants existing text changed, from a small correction to a complete rewrite. Changes include grammar, clarity, length, structure, tone, style, audience, and format. It can shorten, summarize, expand, simplify, paraphrase, or repurpose the supplied text. Requests include 'make this sound like me' and 'make this less AI-written'. A Writing Profile personalizes the result when available. Preserve supplied facts and protected wording unless the user requests changes.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1215,6 +1221,12 @@
             "maxLength": 8000,
             "description": "The user's exact change request. Keep it separate from the prose. Use `changeScope` for the amount of change. Do not replace their words with an effect label."
           },
+          "language": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "The language for the finished writing, in plain words (for example 'French'). Set it only when the user asked for a specific language. Omit it to follow the request's language, or the source text's language for a rewrite."
+          },
           "changeScope": {
             "type": "string",
             "enum": [
@@ -2371,7 +2383,7 @@
     {
       "name": "refine_writing",
       "title": "Refine writing",
-      "description": "Use this when the user asks to change a piece Idiolect AI returned, asks to restyle it with a ready-made template, or reports what they did with it.",
+      "description": "Use this when the user requests changes to an identified piece that Idiolect AI returned. It continues the writing task through further revisions or a selected template. It can also record the user's reported outcome or exact final wording. Use the returned writing reference.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2641,7 +2653,7 @@
     {
       "name": "view_writing_profile",
       "title": "View writing profile",
-      "description": "Use this when the user asks about their Writing Profiles. Without `profile` it lists all profiles and shows the current one in full.",
+      "description": "Use this when profile details are needed to answer the user or resolve a writing or personalization task. Without `profile`, it lists all profiles and shows the current one in full.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2979,7 +2991,7 @@
     {
       "name": "list_writing_samples",
       "title": "List writing samples",
-      "description": "Use this when the user asks which writing a profile was built from.",
+      "description": "Use this when the writing behind a profile is needed for inspection or an authorized personalization workflow.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3321,7 +3333,7 @@
     {
       "name": "create_writing_profile",
       "title": "Create writing profile",
-      "description": "Use this when the user wants a new Writing Profile from writing or answers they approved. It never changes an existing profile.",
+      "description": "Use this when personalization requires a new Writing Profile and approved writing samples or answers are available. It can continue a writing task that is waiting for a profile. It never changes an existing profile.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3747,7 +3759,7 @@
     {
       "name": "add_writing_samples",
       "title": "Add writing samples",
-      "description": "Use this when the user wants more of their own writing added to a profile.",
+      "description": "Use this when additional approved examples of the user's writing are available for an existing Writing Profile. This includes examples supplied during writing and revision workflows.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -5172,7 +5184,7 @@
     {
       "name": "add_writing_rule",
       "title": "Add writing rule",
-      "description": "Use this when the user states a lasting writing rule in their own words.",
+      "description": "Use this when the user states a lasting writing preference, including during a writing task. Save the preference in their words with its stated scope.",
       "inputSchema": {
         "not": {
           "required": [

package/public-contract.js

@@ -0,0 +1,85 @@
+// Generated from lib/mcp/public-contract.js by `npm run mcp:generate-public-artifacts`. Do not edit.
+export const PUBLIC_MCP_TOOL_NAMES = Object.freeze([
+  "get_my_voice",
+  "create_my_voice",
+  "draft_in_voice",
+  "rewrite_in_voice",
+  "score_voice",
+  "record_voice_feedback",
+  "learn_writing_style",
+  "list_writing_profiles",
+  "list_writing_profile_samples",
+  "create_writing_profile",
+  "add_samples_to_writing_profile",
+  "replace_samples_in_writing_profile",
+  "remove_sample_from_writing_profile",
+  "set_current_writing_profile",
+  "delete_writing_profile",
+]);
+
+// Decision for the 2026-08-10 high-arrival review: keep measurement available,
+// but tell hosts to invoke it only when the user explicitly asks for a check.
+// Unmeasured results must continue to say why and expose scorer provenance.
+export const SCORE_VOICE_ADVERTISING_DECISION = Object.freeze({
+  advertised: true,
+  invocation: "explicit_request_only",
+});
+
+const PUBLIC_STATES = new Set([
+  "ready",
+  "missing",
+  "thin",
+  "stale",
+  "complete",
+  "failed",
+]);
+const NEXT_ACTIONS = new Set([
+  "collect_evidence",
+  "reload_voice",
+  "continue_writing",
+  "ask_feedback",
+  "retry",
+  "done",
+]);
+const NEXT_TOOLS = new Set([
+  "create_my_voice",
+  "get_my_voice",
+  "record_voice_feedback",
+  null,
+]);
+const SERVER_ONLY_KEYS = new Set([
+  "workflowId",
+  "baseVersion",
+  "idempotencyKey",
+  "onboardingIdempotencyKey",
+  "leaseToken",
+  "fencingToken",
+  "attemptToken",
+  "buildBindingId",
+]);
+
+function stripServerOnly(value) {
+  if (Array.isArray(value)) return value.map(stripServerOnly);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => !SERVER_ONLY_KEYS.has(key))
+      .map(([key, nested]) => [key, stripServerOnly(nested)]),
+  );
+}
+
+/**
+ * Build the only model-visible state/continuation envelope. Details are copied
+ * through a denylist so internal coordination receipts cannot leak by spread.
+ */
+export function publicMcpState(state, message, next, details = {}) {
+  if (!PUBLIC_STATES.has(state)) throw new TypeError(`Unknown public MCP state: ${state}`);
+  if (!next || !NEXT_ACTIONS.has(next.action) || !NEXT_TOOLS.has(next.tool)) {
+    throw new TypeError("Invalid public MCP next action");
+  }
+  const safeDetails = stripServerOnly(details);
+  delete safeDetails.state;
+  delete safeDetails.message;
+  delete safeDetails.next;
+  return { state, message, ...safeDetails, next: { action: next.action, tool: next.tool } };
+}

package/server.mjs

@@ -34,7 +34,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import {
   publicMcpState,
-} from "../lib/mcp/public-contract.js";
+} from "./public-contract.js";
 
 const progressiveCatalog = JSON.parse(
   readFileSync(new URL("./progressive-catalog.json", import.meta.url), "utf8"),
@@ -489,6 +489,18 @@ const BRIEF_AUTHOR_SCHEMA = {
   description:
     "Who wrote the brief. `user` only when the person wrote it themselves; `host` when you (the assistant) drafted it; `other` for a third party's text. Leave it out if unsure.",
 };
+const CALIBRATION_SCHEMA = {
+  type: "object",
+  properties: {
+    direction: {
+      type: "string",
+      enum: ["direct", "balanced", "gentle"],
+      description: "The user's answer to the single task-local calibration question.",
+    },
+  },
+  required: ["direction"],
+  additionalProperties: false,
+};
 
 /** Validates `sourceAuthor`/`briefAuthor` and defaults an absent one to `"unknown"` on the
  * returned copy of `args`. Returns a tool error, never throws. */
@@ -1049,9 +1061,16 @@ const accountToolDefinitions = [
           description:
                         "The user's actual change request — length, tone, audience, what to cut or keep, make it sound less AI-written, roughen it up, or make it sound like I am talking. Kept separate from `text`: put the request here, never inside the prose to rewrite. `changeScope` carries magnitude; `instructions` carries the requested change.",
         },
+        language: {
+          type: "string",
+          minLength: 1,
+          maxLength: 100,
+          description: "The language for the finished writing, in plain words (for example 'French'). Set it only when the user asked for a specific language. Omit it to follow the request's language, or the source text's language for a rewrite.",
+        },
         changeScope: CHANGE_SCOPE_SCHEMA,
         effects: EFFECTS_SCHEMA,
         sourceAuthor: SOURCE_AUTHOR_SCHEMA,
+        calibration: CALIBRATION_SCHEMA,
         profileId: { type: "string", format: "uuid", description: "Use this owned Writing Profile for this piece only. Select an exact profileId; this does not change the account default." },
       },
       required: ["text"],
@@ -1088,8 +1107,15 @@ const accountToolDefinitions = [
           description:
             "`instructions` is the user's actual direction: how to write the piece — tone, length, format, structure, and what to leave out. Optional; omit it when the user gave none. Never paste directions into `brief`, which carries the material, and never put material here. A named output shape goes in `format`.",
         },
+        language: {
+          type: "string",
+          minLength: 1,
+          maxLength: 100,
+          description: "The language for the finished writing, in plain words (for example 'French'). Set it only when the user asked for a specific language. Omit it to follow the request's language, or the source text's language for a rewrite.",
+        },
         effects: EFFECTS_SCHEMA,
         briefAuthor: BRIEF_AUTHOR_SCHEMA,
+        calibration: CALIBRATION_SCHEMA,
         profileId: { type: "string", format: "uuid", description: "Use this owned Writing Profile for this piece only. Select an exact profileId; this does not change the account default." },
       },
       required: ["brief"],
@@ -1611,6 +1637,9 @@ export async function handleToolRequest(req) {
       const instructions = typeof args.instructions === "string" && args.instructions.trim()
         ? args.instructions.trim()
         : undefined;
+      const language = typeof args.language === "string" && args.language.trim()
+        ? args.language.trim()
+        : undefined;
       const invalidChangeRequest = changeRequestError(args, "rewrite_in_voice");
       if (invalidChangeRequest) return invalidChangeRequest;
       const invalidSourceAuthor = authorProvenanceError(args, "rewrite_in_voice", "sourceAuthor");
@@ -1618,6 +1647,7 @@ export async function handleToolRequest(req) {
       const changeScope = args.changeScope === "polish" ? "light_edit" : args.changeScope;
       const effects = args.effects;
       const sourceAuthor = args.sourceAuthor;
+      const calibration = args.calibration;
       if (!text) {
         return { content: [{ type: "text", text: "rewrite_in_voice: provide `text` to rewrite." }], isError: true };
       }
@@ -1640,9 +1670,11 @@ export async function handleToolRequest(req) {
             ...(profileId !== undefined ? { voice: profileId } : {}),
             ...(targetRegister ? { targetRegister } : {}),
             ...(instructions ? { instructions } : {}),
+            ...(language ? { language } : {}),
             ...(changeScope !== undefined ? { changeScope } : {}),
             ...(effects !== undefined ? { effects } : {}),
             ...(sourceAuthor !== undefined ? { sourceAuthor } : {}),
+            ...(calibration !== undefined ? { calibration } : {}),
           },
           toolName: "rewrite_in_voice",
         });
@@ -1670,6 +1702,9 @@ export async function handleToolRequest(req) {
       const instructions = typeof args.instructions === "string" && args.instructions.trim()
         ? args.instructions.trim()
         : undefined;
+      const language = typeof args.language === "string" && args.language.trim()
+        ? args.language.trim()
+        : undefined;
       const formats = new Set(["linkedin", "x_post", "x_thread", "newsletter", "generic"]);
       const invalidChangeRequest = changeRequestError(args, "draft_in_voice");
       if (invalidChangeRequest) return invalidChangeRequest;
@@ -1678,6 +1713,7 @@ export async function handleToolRequest(req) {
       const changeScope = args.changeScope === "polish" ? "light_edit" : args.changeScope;
       const effects = args.effects;
       const briefAuthor = args.briefAuthor;
+      const calibration = args.calibration;
       if (!brief) {
         return { content: [{ type: "text", text: "draft_in_voice: provide `brief` to draft from." }], isError: true };
       }
@@ -1700,9 +1736,11 @@ export async function handleToolRequest(req) {
             ...(profileId !== undefined ? { voice: profileId } : {}),
             ...(format ? { format } : {}),
             ...(instructions ? { instructions } : {}),
+            ...(language ? { language } : {}),
             ...(changeScope !== undefined ? { changeScope } : {}),
             ...(effects !== undefined ? { effects } : {}),
             ...(briefAuthor !== undefined ? { briefAuthor } : {}),
+            ...(calibration !== undefined ? { calibration } : {}),
           },
           toolName: "draft_in_voice",
         });