@hanna84/mcp-writing 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ 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)

package/index.js

@@ -849,12 +849,156 @@ 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 });

package/package.json

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