@hanna84/mcp-writing 2.5.1 → 2.7.0

package/CHANGELOG.md

@@ -4,11 +4,31 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.7.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.6.0...v2.7.0)
+
+- feat(workflows): add describe_workflows entry-point tool [`#90`](https://github.com/hannasdev/mcp-writing.git
+/pull/90)
+
+#### [v2.6.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.5.1...v2.6.0)
+
+> 26 April 2026
+
+- feat(styleguide): improve AI navigation with next_step hints and identifier validation [`#89`](https://github.com/hannasdev/mcp-writing.git
+/pull/89)
+- Release 2.6.0 [`1083d55`](https://github.com/hannasdev/mcp-writing.git
+/commit/1083d556f1d7b23a1c1290b84735014878187b47)
+
 #### [v2.5.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.5.0...v2.5.1)
 
+> 26 April 2026
+
 - docs(prd): update README phase status and add refactoring PRD [`#88`](https://github.com/hannasdev/mcp-writing.git
 /pull/88)
+- Release 2.5.1 [`4c78109`](https://github.com/hannasdev/mcp-writing.git
+/commit/4c781092152e3ae52715bfe05dbfda143f9c37c7)
 
 #### [v2.5.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.4.0...v2.5.0)

package/importer.js

@@ -32,6 +32,16 @@ export function validateProjectId(projectId) {
   return { ok: true };
 }
 
+export function validateUniverseId(universeId) {
+  if (typeof universeId !== "string" || universeId.trim().length === 0) {
+    return { ok: false, reason: "universe_id must be a non-empty string." };
+  }
+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(universeId)) {
+    return { ok: false, reason: "universe_id may contain only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen." };
+  }
+  return { ok: true };
+}
+
 // Parse "NNN Title [binder_id].txt" -> { seq, rawTitle, binderId, ext } or null
 function parseFilename(filename) {
   const m = filename.match(/^(\d+)\s+(.+?)\s*\[(\d+)\]\.(txt|md)$/);

package/index.js

@@ -15,7 +15,7 @@ import { openDb } from "./db.js";
 import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, getFileWriteDiagnostics, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
 import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit, getHeadCommitHash } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
-import { importScrivenerSync, validateProjectId } from "./importer.js";
+import { importScrivenerSync, validateProjectId, validateUniverseId } from "./importer.js";
 import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
 import {
   STYLEGUIDE_CONFIG_BASENAME,
@@ -845,12 +845,160 @@ async function gracefulShutdown(signal) {
   process.exit(0);
 }
 
+function maxScenesNextStep(matchedCount) {
+  return `Re-run with max_scenes set to at least ${matchedCount}.`;
+}
+
+const WORKFLOW_CATALOGUE = [
+  {
+    id: "first_time_setup",
+    label: "First-time setup",
+    use_when: "Connecting to a project for the first time or verifying the runtime is correctly configured.",
+    steps: [
+      { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
+      { tool: "sync", note: "Index scenes from disk." },
+    ],
+  },
+  {
+    id: "styleguide_setup_new",
+    label: "Styleguide setup (new project)",
+    use_when: "No prose styleguide config exists and you want to create one based on the manuscript's existing conventions.",
+    steps: [
+      { tool: "describe_workflows", note: "Check context.scene_count; use that value as max_scenes in the next call." },
+      { tool: "bootstrap_prose_styleguide_config", note: "Detect dominant conventions. Confirm suggestions with the user before applying." },
+      { tool: "setup_prose_styleguide_config", note: "Create config at project_root scope if context.styleguide_exists.project_root is false. Requires language (e.g. 'english_us')." },
+      { tool: "update_prose_styleguide_config", note: "Apply the fields accepted from bootstrap suggestions." },
+    ],
+  },
+  {
+    id: "styleguide_drift_check",
+    label: "Styleguide drift check",
+    use_when: "A styleguide config exists and you want to check whether recent scenes conform to it.",
+    steps: [
+      { tool: "get_prose_styleguide_config", note: "Confirm the currently resolved config." },
+      { tool: "check_prose_styleguide_drift", note: "Detect non-conforming scenes. Pass project_id from context.project_id and set max_scenes from context.scene_count." },
+      { tool: "update_prose_styleguide_config", note: "If drift found and user approves, update config or note the outliers." },
+    ],
+  },
+  {
+    id: "manuscript_exploration",
+    label: "Manuscript exploration",
+    use_when: "Answering questions about the manuscript, finding scenes, or getting an overview.",
+    steps: [
+      { tool: "find_scenes", note: "Filter by character, beat, tag, part, chapter, or POV. No filters returns all scenes." },
+      { tool: "get_scene_prose", note: "Load prose for specific scenes identified by find_scenes." },
+      { tool: "get_chapter_prose", note: "Load all prose for a chapter. Use sparingly — large chapters can overflow context." },
+      { tool: "search_metadata", note: "Full-text search across scene metadata fields." },
+    ],
+  },
+  {
+    id: "prose_editing",
+    label: "Prose editing",
+    use_when: "Revising scene prose. All edits require explicit user confirmation before writing.",
+    steps: [
+      { tool: "find_scenes", note: "Identify the target scene." },
+      { tool: "get_scene_prose", note: "Load the current prose." },
+      { tool: "propose_edit", note: "Stage a revision; returns a diff preview and a proposal_id." },
+      { tool: "commit_edit", note: "Write the revision after the user confirms. Runs preflight checks before writing." },
+      { tool: "discard_edit", note: "Reject the revision if the user does not approve." },
+    ],
+  },
+  {
+    id: "character_management",
+    label: "Character management",
+    use_when: "Finding characters, reading their sheets, or updating character details.",
+    steps: [
+      { tool: "list_characters", note: "Find character_id values." },
+      { tool: "get_character_sheet", note: "Read full character details." },
+      { tool: "create_character_sheet", note: "Create a new character. Requires exactly one of project_id or universe_id." },
+      { tool: "update_character_sheet", note: "Edit character metadata." },
+    ],
+  },
+  {
+    id: "place_management",
+    label: "Place management",
+    use_when: "Finding locations, reading place sheets, or updating place details.",
+    steps: [
+      { tool: "list_places", note: "Find place_id values." },
+      { tool: "get_place_sheet", note: "Read full place details." },
+      { tool: "create_place_sheet", note: "Create a new place. Requires exactly one of project_id or universe_id." },
+      { tool: "update_place_sheet", note: "Edit place metadata." },
+    ],
+  },
+  {
+    id: "review_bundle",
+    label: "Review bundle",
+    use_when: "Preparing a formatted bundle for human review (outline, editorial, or beta read profile).",
+    steps: [
+      { tool: "preview_review_bundle", note: "Check which scenes would be included and the estimated size. Requires project_id and profile." },
+      { tool: "create_review_bundle", note: "Generate the bundle. Requires project_id." },
+    ],
+  },
+  {
+    id: "async_job_tracking",
+    label: "Async job tracking",
+    use_when: "A tool returned a job_id instead of an immediate result (e.g. import_scrivener_sync_async).",
+    steps: [
+      { tool: "get_async_job_status", note: "Poll with the job_id until status is 'completed' or 'failed'." },
+      { tool: "sync", note: "Call after a completed job that modified files on disk." },
+    ],
+  },
+];
+
 // ---------------------------------------------------------------------------
 // MCP server factory
 // ---------------------------------------------------------------------------
 function createMcpServer() {
   const s = new McpServer({ name: "mcp-writing", version: MCP_SERVER_VERSION });
 
+  // ---- describe_workflows --------------------------------------------------
+  s.tool(
+    "describe_workflows",
+    "Return a map of available task workflows and the current project context. Call this at the start of a session or whenever you are unsure what to do next. Never write scripts to invoke tools — call them directly.",
+    {},
+    async () => {
+      const projectRow = db.prepare(
+        `SELECT project_id FROM scenes GROUP BY project_id ORDER BY COUNT(*) DESC, project_id ASC LIMIT 1`
+      ).get();
+      const project_id = projectRow?.project_id ?? null;
+
+      const sceneCountRow = db.prepare(`SELECT COUNT(*) as count FROM scenes`).get();
+      const scene_count = sceneCountRow?.count ?? 0;
+
+      const syncRootConfigPath = path.join(SYNC_DIR, STYLEGUIDE_CONFIG_BASENAME);
+      const projectRootConfigPath = project_id
+        ? path.join(resolveProjectRoot(project_id), STYLEGUIDE_CONFIG_BASENAME)
+        : null;
+      const universeSegment = project_id?.includes("/") ? project_id.split("/")[0] : null;
+      const universeRootConfigPath = universeSegment
+        ? path.join(SYNC_DIR, "universes", universeSegment, STYLEGUIDE_CONFIG_BASENAME)
+        : null;
+
+      return jsonResponse({
+        ok: true,
+        context: {
+          project_id,
+          scene_count,
+          sync_dir: SYNC_DIR_ABS,
+          styleguide_exists: {
+            sync_root: fs.existsSync(syncRootConfigPath),
+            universe_root: universeRootConfigPath !== null && fs.existsSync(universeRootConfigPath),
+            project_root: projectRootConfigPath !== null && fs.existsSync(projectRootConfigPath),
+          },
+          git_available: GIT_AVAILABLE,
+          pending_proposals: pendingProposals.size,
+        },
+        workflows: WORKFLOW_CATALOGUE,
+        notes: [
+          "Never write JavaScript or shell scripts to invoke tools. Call them directly.",
+          "If a tool returns a next_step field (in a success or error response), follow it before trying anything else.",
+          "Use find_scenes without filters to discover what project_ids are indexed.",
+          "When calling bootstrap_prose_styleguide_config or check_prose_styleguide_drift, set max_scenes to context.scene_count to avoid the default limit.",
+        ],
+      });
+    }
+  );
+
   // ---- sync ----------------------------------------------------------------
   s.tool("sync", "Re-scan the sync folder and update the scene/character/place index from disk. Call this after making edits in Scrivener or updating sidecar files outside the MCP.", {}, async () => {
     const result = syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
@@ -1226,6 +1374,7 @@ function createMcpServer() {
             matched_scenes: targetScenes.length,
             max_scenes,
             project_id,
+            next_step: maxScenesNextStep(targetScenes.length),
           }
         );
       }
@@ -1485,6 +1634,7 @@ function createMcpServer() {
         config: draft.config,
         inferred_defaults: draft.inferred_defaults,
         warnings: draft.warnings,
+        next_step: "Config created. Call update_prose_styleguide_config to apply field updates.",
       });
     }
   );
@@ -1520,7 +1670,7 @@ function createMcpServer() {
         ok: true,
         styleguide: resolved,
         next_step: resolved.setup_required
-          ? "No prose-styleguide.config.yaml was found. Run setup to create one at sync root or project root."
+          ? "No prose-styleguide.config.yaml was found. Call setup_prose_styleguide_config (with language e.g. 'en') to create one at sync root or project root."
           : "Config resolved successfully.",
       });
     }
@@ -1632,7 +1782,12 @@ function createMcpServer() {
         return errorResponse(
           "VALIDATION_ERROR",
           `Matched ${targetScenes.length} scenes, which exceeds max_scenes=${max_scenes}.`,
-          { matched_scenes: targetScenes.length, max_scenes, project_id }
+          {
+            matched_scenes: targetScenes.length,
+            max_scenes,
+            project_id,
+            next_step: maxScenesNextStep(targetScenes.length),
+          }
         );
       }
 
@@ -1669,7 +1824,7 @@ function createMcpServer() {
         checked_scenes: sceneSignals.length,
         unreadable_scenes: unreadableScenes,
         suggested_config: suggestedConfig,
-        next_step: "Review suggested_config, then write accepted fields via update_prose_styleguide_config.",
+        next_step: `To apply: (1) If no project-scoped config exists yet, call setup_prose_styleguide_config first with scope=project_root, project_id=${project_id}, and language (e.g. 'en'). (2) Then call update_prose_styleguide_config with the fields from suggested_config you want to apply.`,
         scene_signals: include_scene_signals ? sceneSignals : undefined,
       });
     }
@@ -1886,7 +2041,12 @@ function createMcpServer() {
         return errorResponse(
           "VALIDATION_ERROR",
           `Matched ${targetScenes.length} scenes, which exceeds max_scenes=${max_scenes}.`,
-          { matched_scenes: targetScenes.length, max_scenes, project_id }
+          {
+            matched_scenes: targetScenes.length,
+            max_scenes,
+            project_id,
+            next_step: maxScenesNextStep(targetScenes.length),
+          }
         );
       }
 
@@ -2511,9 +2671,19 @@ function createMcpServer() {
       if (!SYNC_DIR_WRITABLE) {
         return errorResponse("READ_ONLY", "Cannot create character sheet: sync dir is read-only.");
       }
-      if ((project_id && universe_id) || (!project_id && !universe_id)) {
+      const hasProjectId = project_id !== undefined;
+      const hasUniverseId = universe_id !== undefined;
+      if ((hasProjectId && hasUniverseId) || (!hasProjectId && !hasUniverseId)) {
         return errorResponse("VALIDATION_ERROR", "Provide exactly one of project_id or universe_id.");
       }
+      if (hasProjectId) {
+        const check = validateProjectId(project_id);
+        if (!check.ok) return errorResponse("INVALID_PROJECT_ID", check.reason, { project_id });
+      }
+      if (hasUniverseId) {
+        const check = validateUniverseId(universe_id);
+        if (!check.ok) return errorResponse("INVALID_UNIVERSE_ID", check.reason, { universe_id });
+      }
 
       try {
         const result = createCanonicalWorldEntity({
@@ -2575,9 +2745,19 @@ function createMcpServer() {
       if (!SYNC_DIR_WRITABLE) {
         return errorResponse("READ_ONLY", "Cannot create place sheet: sync dir is read-only.");
       }
-      if ((project_id && universe_id) || (!project_id && !universe_id)) {
+      const hasProjectId = project_id !== undefined;
+      const hasUniverseId = universe_id !== undefined;
+      if ((hasProjectId && hasUniverseId) || (!hasProjectId && !hasUniverseId)) {
         return errorResponse("VALIDATION_ERROR", "Provide exactly one of project_id or universe_id.");
       }
+      if (hasProjectId) {
+        const check = validateProjectId(project_id);
+        if (!check.ok) return errorResponse("INVALID_PROJECT_ID", check.reason, { project_id });
+      }
+      if (hasUniverseId) {
+        const check = validateUniverseId(universe_id);
+        if (!check.ok) return errorResponse("INVALID_UNIVERSE_ID", check.reason, { universe_id });
+      }
 
       try {
         const result = createCanonicalWorldEntity({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",

package/prose-styleguide.js

@@ -391,7 +391,12 @@ function prepareStyleguideConfigUpdate({ syncDir, scope, projectId, updates = {}
       error: {
         code: "STYLEGUIDE_CONFIG_NOT_FOUND",
         message: "Cannot update styleguide config because no config exists at the requested scope.",
-        details: { file_path: filePath, scope, project_id: projectId ?? null },
+        details: {
+          file_path: filePath,
+          scope,
+          project_id: projectId ?? null,
+          next_step: `Call setup_prose_styleguide_config first (scope=${scope}${projectId ? `, project_id=${projectId}` : ""}, language=<e.g. 'en'>), then retry update_prose_styleguide_config.`,
+        },
       },
     };
   }