@hanna84/mcp-writing 3.24.1 → 3.25.0

package/CHANGELOG.md

@@ -4,9 +4,16 @@ 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).
 
+#### [v3.25.0](https://github.com/hannasdev/mcp-writing/compare/v3.24.1...v3.25.0)
+
+- feat: clarify M1 workflow and relationship responses [`#235`](https://github.com/hannasdev/mcp-writing/pull/235)
+
 #### [v3.24.1](https://github.com/hannasdev/mcp-writing/compare/v3.24.0...v3.24.1)
 
+> 6 June 2026
+
 - test: add relationship boundary release readiness coverage [`#234`](https://github.com/hannasdev/mcp-writing/pull/234)
+- Release 3.24.1 [`158ff88`](https://github.com/hannasdev/mcp-writing/commit/158ff8817e7bb3aefc92b2c4c05c8c2b36c83ef3)
 
 #### [v3.24.0](https://github.com/hannasdev/mcp-writing/compare/v3.23.2...v3.24.0)
 

package/README.md

@@ -58,7 +58,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 
 ### `describe_workflows` surface redesign
 
-`describe_workflows` now exposes an outcome-first, discovery-first workflow map. This is a breaking change if your prompts or automation depend on previous workflow IDs or ordering.
+`describe_workflows` now exposes an outcome-first, discovery-first workflow map. This was a breaking change if your prompts or automation depend on previous workflow IDs or ordering; the newer `recommended_next_actions` tier is additive and appears before the full catalogue.
 
 Update integrations using this mapping:
 
@@ -153,7 +153,7 @@ Goal: keep indexes accurate without manually re-tagging everything.
 
 1. After rewriting scenes, call `enrich_scene` to re-derive lightweight metadata from current prose.
 2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags). It rejects scene `characters` and `places`; use `connect_character_place_evidence` when a scene proves paired sheet-backed character/place evidence, `connect_scene_character_evidence` for character-only evidence, and `connect_scene_place_evidence` for place-only evidence. Use `audit_relationship_metadata` for retained sidecar/frontmatter relationship fields. Use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering.
-3. Use `search_metadata` and `find_scenes` to verify scenes are discoverable under the expected filters.
+3. Use `search_metadata` for keyword/FTS metadata searches across indexed titles, loglines, tags, characters, places, and versions, and use `find_scenes` to verify scenes are discoverable under structured filters. After identifying likely scenes, use `get_scene_prose` for prose context.
 
 Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.24.1",
+  "version": "3.25.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/index.js

@@ -327,6 +327,100 @@ function maxScenesNextStep(matchedCount) {
   return `Re-run with max_scenes set to at least ${matchedCount}.`;
 }
 
+function buildRecommendedNextActions({
+  sceneCount,
+  setupContract,
+  dbMigrationWarnings,
+}) {
+  const recommendations = [];
+
+  if (dbMigrationWarnings.length > 0) {
+    recommendations.push({
+      id: "refresh_index_after_migration_warning",
+      label: "Refresh indexed state",
+      tool: "sync",
+      workflow_id: "parity_recovery",
+      priority: 10,
+      reason: "Database migration warnings are present, so indexed metadata may need a sync before other work.",
+      next_step: "Call sync, then re-run describe_workflows before mutating project state.",
+    });
+  }
+
+  if (sceneCount === 0) {
+    recommendations.push({
+      id: "index_project_content",
+      label: "Index project content",
+      tool: "sync",
+      workflow_id: "first_time_setup",
+      priority: 20,
+      reason: "No scenes are indexed yet, so discovery and scene-reading tools have no project content to inspect.",
+      next_step: "Call sync to index the configured writing folder, then use find_scenes without filters to confirm project_ids.",
+    });
+    recommendations.push({
+      id: "inspect_runtime_configuration",
+      label: "Inspect runtime configuration",
+      tool: "get_runtime_config",
+      workflow_id: "first_time_setup",
+      priority: 30,
+      reason: "Runtime paths and writable state determine whether sync can index the intended manuscript folder.",
+      next_step: "Call get_runtime_config if sync still indexes no scenes or the configured writing folder looks wrong.",
+    });
+    recommendations.push({
+      id: "diagnose_empty_index",
+      label: "Diagnose indexed structure",
+      tool: "diagnose_structure",
+      workflow_id: "parity_recovery",
+      priority: 35,
+      reason: "If sync does not discover scenes, structure diagnostics can explain missing or ambiguous manuscript representations.",
+      next_step: "Call diagnose_structure after sync if the index is still empty or project structure looks unexpected.",
+    });
+  } else {
+    recommendations.push({
+      id: "discover_indexed_scenes",
+      label: "Discover indexed scenes",
+      tool: "find_scenes",
+      workflow_id: "question_driven_discovery",
+      priority: 20,
+      reason: "Scenes are indexed; metadata-first discovery is the safest starting point for most manuscript questions.",
+      next_step: "Call find_scenes with project_id or lightweight filters before loading prose.",
+    });
+    recommendations.push({
+      id: "keyword_metadata_search",
+      label: "Search metadata keywords",
+      tool: "search_metadata",
+      workflow_id: "question_driven_discovery",
+      priority: 30,
+      reason: "Use keyword/FTS metadata search when you know likely titles, logline words, tags, characters, places, or versions.",
+      next_step: "Search exact metadata keywords, then open likely scenes with get_scene_prose if prose context is needed.",
+    });
+    recommendations.push({
+      id: "read_likely_scene",
+      label: "Read a likely scene",
+      tool: "get_scene_prose",
+      workflow_id: "targeted_scene_reading",
+      priority: 35,
+      reason: "Prose should be loaded only after metadata has identified a likely scene.",
+      next_step: "Call get_scene_prose with a specific scene_id and project_id once discovery has narrowed the target.",
+    });
+  }
+
+  if (setupContract?.setup_recommended) {
+    recommendations.push({
+      id: "review_styleguide_setup",
+      label: "Review styleguide setup",
+      tool: "setup_prose_styleguide_config",
+      workflow_id: "styleguide_setup_new",
+      priority: 40,
+      reason: `Styleguide setup status is ${setupContract.styleguide_setup_status}.`,
+      next_step: "Follow context.setup_contract.plan_preview before running styleguide drift checks or enforcement workflows.",
+    });
+  }
+
+  return recommendations
+    .sort((a, b) => a.priority - b.priority)
+    .slice(0, 5);
+}
+
 // ---------------------------------------------------------------------------
 // MCP server factory
 // ---------------------------------------------------------------------------
@@ -444,6 +538,11 @@ function createMcpServer() {
           pending_proposals: pendingProposals.size,
           db_migration_warnings: DB_STARTUP_WARNINGS,
         },
+        recommended_next_actions: buildRecommendedNextActions({
+          sceneCount: scene_count,
+          setupContract: setupContractContextCheck.value,
+          dbMigrationWarnings: DB_STARTUP_WARNINGS,
+        }),
         workflows: WORKFLOW_CATALOGUE,
         notes: [
           "Never write JavaScript or shell scripts to invoke tools. Call them directly.",

package/src/tools/metadata.js

@@ -130,6 +130,40 @@ function buildRelationshipMetadataBoundaryDetails({ projectId, sceneId, blockedF
   };
 }
 
+function relationshipEvidenceNotFoundDetails({ lookupKind, input, projectId, sceneId }) {
+  const details = {
+    lookup_kind: lookupKind,
+    input,
+    project_id: projectId,
+  };
+  if (sceneId !== undefined) {
+    details.scene_id = sceneId;
+  }
+
+  if (lookupKind === "scene") {
+    return {
+      ...details,
+      next_step: "Use find_scenes with the project_id to confirm the canonical scene_id, then retry the relationship evidence tool.",
+    };
+  }
+
+  if (lookupKind === "character") {
+    return {
+      ...details,
+      next_step: "Use list_characters to find the stable character_id for this project or universe, then retry the relationship evidence tool.",
+    };
+  }
+
+  return {
+    ...details,
+    next_step: "Use list_places to find the stable place_id for this project or universe, then retry the relationship evidence tool.",
+  };
+}
+
+function alreadyLinkedRelationshipNextStep({ entityKind }) {
+  return `This ${entityKind} was already linked to the scene, so no canonical relationship rows changed. Use the scene_relationships field in this response to inspect current links; call get_scene_prose with the scene_id and project_id if prose context is needed.`;
+}
+
 function persistReferenceDocLink({ filePath, syncDir, targetDocId, relation }) {
   const syncDirAbs = path.resolve(syncDir);
   const syncDirReal = resolveBoundaryRootReal(syncDirAbs);
@@ -862,16 +896,42 @@ export function registerMetadataTools(s, {
       WHERE scene_id = ? AND project_id = ?
     `).get(scene_id, project_id);
     if (!scene) {
-      return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+      return errorResponse(
+        "NOT_FOUND",
+        `Scene '${scene_id}' not found in project '${project_id}'.`,
+        relationshipEvidenceNotFoundDetails({
+          lookupKind: "scene",
+          input: scene_id,
+          projectId: project_id,
+        })
+      );
     }
 
     const character = resolveCharacterForProject(db, { characterId: character_id, projectId: project_id });
     if (!character) {
-      return errorResponse("NOT_FOUND", `Character '${character_id}' is not indexed for project '${project_id}' or its universe.`);
+      return errorResponse(
+        "NOT_FOUND",
+        `Character '${character_id}' is not indexed for project '${project_id}' or its universe.`,
+        relationshipEvidenceNotFoundDetails({
+          lookupKind: "character",
+          input: character_id,
+          projectId: project_id,
+          sceneId: scene_id,
+        })
+      );
     }
     const place = resolvePlaceForProject(db, { placeId: place_id, projectId: project_id });
     if (!place) {
-      return errorResponse("NOT_FOUND", `Place '${place_id}' is not indexed for project '${project_id}' or its universe.`);
+      return errorResponse(
+        "NOT_FOUND",
+        `Place '${place_id}' is not indexed for project '${project_id}' or its universe.`,
+        relationshipEvidenceNotFoundDetails({
+          lookupKind: "place",
+          input: place_id,
+          projectId: project_id,
+          sceneId: scene_id,
+        })
+      );
     }
 
     const before = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
@@ -1005,12 +1065,29 @@ export function registerMetadataTools(s, {
       WHERE scene_id = ? AND project_id = ?
     `).get(scene_id, project_id);
     if (!scene) {
-      return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+      return errorResponse(
+        "NOT_FOUND",
+        `Scene '${scene_id}' not found in project '${project_id}'.`,
+        relationshipEvidenceNotFoundDetails({
+          lookupKind: "scene",
+          input: scene_id,
+          projectId: project_id,
+        })
+      );
     }
 
     if (!resolveEntity(entity_id)) {
       const label = entityKind[0].toUpperCase() + entityKind.slice(1);
-      return errorResponse("NOT_FOUND", `${label} '${entity_id}' is not indexed for project '${project_id}' or its universe.`);
+      return errorResponse(
+        "NOT_FOUND",
+        `${label} '${entity_id}' is not indexed for project '${project_id}' or its universe.`,
+        relationshipEvidenceNotFoundDetails({
+          lookupKind: entityKind,
+          input: entity_id,
+          projectId: project_id,
+          sceneId: scene_id,
+        })
+      );
     }
 
     const before = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
@@ -1095,7 +1172,11 @@ export function registerMetadataTools(s, {
     return jsonResponse({
       ok: true,
       action: "connected",
+      outcome: alreadyLinked ? "no_op" : "connected",
       already_linked: alreadyLinked,
+      ...(alreadyLinked
+        ? { next_step: alreadyLinkedRelationshipNextStep({ entityKind }) }
+        : {}),
       scene_id,
       project_id,
       [idField]: entity_id,

package/src/tools/search.js

@@ -662,9 +662,9 @@ export function registerSearchTools(s, {
   // ---- search_metadata -----------------------------------------------------
   s.tool(
     "search_metadata",
-    "Full-text search across scene titles, loglines (synopsis/logline text fields), and metadata keywords (tags/characters/places/versions). Use this when you don't know the exact scene_id or chapter but want to find scenes by topic, theme, or metadata keyword. Not a prose search — use get_scene_prose to read actual text. Supports pagination via page/page_size and auto-paginates large result sets with total_count.",
+    "Keyword/FTS metadata search across scene titles, loglines (synopsis/logline text fields), and indexed metadata keywords (tags/characters/places/versions). Use this when you know likely words or exact metadata values but do not know the scene_id or chapter. This is not semantic search and does not search prose text; use find_scenes for structured filters and get_scene_prose after identifying likely scenes. Supports pagination via page/page_size and auto-paginates large result sets with total_count.",
     {
-      query: z.string().describe("Search terms (e.g. 'hospital' or 'Sebastian feeding'). FTS5 syntax supported."),
+      query: z.string().describe("Keyword search terms from indexed metadata (e.g. 'hospital' or a quoted character/place/tag phrase). FTS5 syntax supported."),
       page: z.number().int().min(1).optional().describe("Optional page number for paginated responses (1-based)."),
       page_size: z.number().int().min(1).max(200).optional().describe("Optional page size for paginated responses (default: 20, max: 200)."),
     },
@@ -682,7 +682,11 @@ export function registerSearchTools(s, {
       }
 
       if (totalCount === 0) {
-        return errorResponse("NO_RESULTS", "No scenes matched the search query.");
+        return errorResponse("NO_RESULTS", "No scenes matched the keyword metadata search query.", {
+          search_type: "keyword_metadata_fts",
+          searched_fields: ["scene.title", "scene.logline", "tags", "characters", "places", "versions"],
+          next_step: "Try exact metadata keywords, quoted character/place/tag names, or find_scenes structured filters. After finding likely scenes, use get_scene_prose for prose context; search_metadata is not semantic or prose search.",
+        });
       }
 
       const shouldPaginate = totalCount > DEFAULT_METADATA_PAGE_SIZE || page !== undefined || page_size !== undefined;

package/src/workflows/workflow-catalogue.js

@@ -5,7 +5,7 @@ export const WORKFLOW_CATALOGUE = [
     use_when: "Start here for most sessions: when the user has a manuscript question, you need to narrow scope, or you are not yet sure which scene matters.",
     steps: [
       { tool: "find_scenes", note: "Use structured metadata filters first when the question already suggests characters, beats, tags, parts, chapters, or POV; numeric chapter values are read-scope aliases, while structure changes require canonical chapter_id workflows." },
-      { tool: "search_metadata", note: "Use this when the question is thematic, fuzzy, or keyword-driven rather than cleanly filterable." },
+      { tool: "search_metadata", note: "Use this when likely title, logline, tag, character, place, or version keywords are known but structured filters are not cleanly available; it is not semantic or prose search." },
       { tool: "get_scene_prose", note: "Escalate to prose only after likely scenes have been identified and metadata is no longer enough." },
       { tool: "flag_scene", note: "Use only when the current task naturally leads to recording a follow-up note for later editorial attention." },
     ],