@hanna84/mcp-writing 3.5.4 → 3.6.0

package/CHANGELOG.md

@@ -4,9 +4,23 @@ 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.6.0](https://github.com/hannasdev/mcp-writing/compare/v3.5.5...v3.6.0)
+
+- feat(search): normalize metadata-read tool response envelopes [`#189`](https://github.com/hannasdev/mcp-writing/pull/189)
+
+#### [v3.5.5](https://github.com/hannasdev/mcp-writing/compare/v3.5.4...v3.5.5)
+
+> 9 May 2026
+
+- fix: suppress epigraph titles and refine review replies [`#187`](https://github.com/hannasdev/mcp-writing/pull/187)
+- Release 3.5.5 [`26aa8f8`](https://github.com/hannasdev/mcp-writing/commit/26aa8f88d44dc49b0ee4c44a65b00274de73641c)
+
 #### [v3.5.4](https://github.com/hannasdev/mcp-writing/compare/v3.5.3...v3.5.4)
 
+> 8 May 2026
+
 - chore(skills): add reusable post-merge cleanup skill [`#186`](https://github.com/hannasdev/mcp-writing/pull/186)
+- Release 3.5.4 [`b17e35d`](https://github.com/hannasdev/mcp-writing/commit/b17e35d98d74a963bfca901e880e5d0965de7047)
 
 #### [v3.5.3](https://github.com/hannasdev/mcp-writing/compare/v3.5.2...v3.5.3)
 

package/README.md

@@ -86,12 +86,39 @@ Safe parsing pattern:
 
 ```js
 const parsed = JSON.parse(toolText);
+if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
 const scenes = parsed.results ?? [];
 const totalCount = parsed.total_count ?? scenes.length;
 const warning = parsed.warning ?? null;
 const nextStep = parsed.next_step ?? null;
 ```
 
+### `get_character_sheet`, `get_place_sheet`, `list_scene_references`, `get_relationship_arc` response-shape standardization
+
+These metadata-read tools now return structured envelopes instead of flat objects or raw arrays.
+
+- `get_character_sheet` and `get_place_sheet`: previously returned a flat object of field values; now return `{ results: [row], total_count: 1, next_step }`.
+- `list_scene_references`: previously returned `{ references, scene_id, project_id }`; now returns `{ results, total_count, scene_id, project_id }`.
+- `get_relationship_arc`: previously returned a raw JSON array; now returns `{ results, total_count, from_character, to_character }`.
+
+Safe parsing pattern for sheet tools:
+
+```js
+const parsed = JSON.parse(toolText);
+if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
+const sheet = parsed.results?.[0] ?? {};
+const nextStep = parsed.next_step ?? null;
+```
+
+Safe parsing pattern for list/arc tools:
+
+```js
+const parsed = JSON.parse(toolText);
+if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
+const items = parsed.results ?? [];
+const totalCount = parsed.total_count ?? items.length;
+```
+
 ## Usage scenarios
 
 ### 1) Continuity pass before sending chapters to beta readers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.5.4",
+  "version": "3.6.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/review-bundles/review-bundles-renderer.js

@@ -374,6 +374,18 @@ function renderProseWithInlineEmphasis(doc, prose, {
   doc.font(bodyFont).fontSize(fontSize);
 }
 
+function isEpigraphScene(scene) {
+  const tags = Array.isArray(scene?.tags)
+    ? scene.tags
+      .map(tag => String(tag ?? "").trim().toLowerCase())
+      .filter(Boolean)
+    : [];
+  if (tags.includes("epigraph")) return true;
+
+  const title = String(scene?.title ?? "").trim();
+  return /^epigraph(?:\b|\s|[-:])/i.test(title);
+}
+
 function renderSceneBlock(scene, options) {
   const {
     profile,
@@ -384,7 +396,7 @@ function renderSceneBlock(scene, options) {
   } = options;
 
   const isBetaProfile = profile === "beta_reader_personalized";
-  const isEpigraph = isBetaProfile && scene.tags?.includes("epigraph");
+  const isEpigraph = isBetaProfile && isEpigraphScene(scene);
 
   const parts = [];
 
@@ -733,7 +745,7 @@ export function renderReviewBundlePdfWithMetadata(dbHandle, plan, { generatedAt,
         }
 
         // Skip title rendering for epigraphs in beta profile
-        const isEpigraph = isBetaProfile && scene.tags?.includes("epigraph");
+        const isEpigraph = isBetaProfile && isEpigraphScene(scene);
         if (!isEpigraph) {
           doc.fontSize(isBetaProfile ? 13 : 14).font(sceneHeadingFont);
           let heading = scene.title || scene.scene_id;

package/src/tools/search.js

@@ -371,7 +371,7 @@ export function registerSearchTools(s, {
   // ---- get_character_sheet -------------------------------------------------
   s.tool(
     "get_character_sheet",
-    "Get full character details: role, arc_summary, traits, the canonical sheet content, and any adjacent support notes when the character uses a folder-based layout. Use this when the reasoning task needs the character's canonical profile rather than only their scene progression.",
+    "Get full character details: role, arc_summary, traits, the canonical sheet content, and any adjacent support notes when the character uses a folder-based layout. Use this when the reasoning task needs the character's canonical profile rather than only their scene progression. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
     {
       character_id: z.string().describe("The character_id to look up (e.g. 'char-sebastian'). Use list_characters to find valid IDs."),
     },
@@ -402,9 +402,17 @@ export function registerSearchTools(s, {
         traits,
         notes: notes || undefined,
         supporting_notes: supportingNotes.length ? supportingNotes : undefined,
-        next_step: "Use get_arc with this character_id to trace scene-level progression, then open specific scenes with get_scene_prose when prose evidence is needed.",
       };
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            results: [result],
+            total_count: 1,
+            next_step: "Use get_arc with this character_id to trace scene-level progression, then open specific scenes with get_scene_prose when prose evidence is needed.",
+          }, null, 2),
+        }],
+      };
     }
   );
 
@@ -444,7 +452,7 @@ export function registerSearchTools(s, {
   // ---- get_place_sheet -----------------------------------------------------
   s.tool(
     "get_place_sheet",
-    "Get full place details: associated_characters, tags, the canonical sheet content, and any adjacent support notes when the place uses a folder-based layout. Use this when the current scene or question makes the place itself materially relevant.",
+    "Get full place details: associated_characters, tags, the canonical sheet content, and any adjacent support notes when the place uses a folder-based layout. Use this when the current scene or question makes the place itself materially relevant. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
     {
       place_id: z.string().describe("The place_id to look up (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
     },
@@ -480,9 +488,17 @@ export function registerSearchTools(s, {
         tags: tags.length ? tags : undefined,
         notes: notes || undefined,
         supporting_notes: supportingNotes.length ? supportingNotes : undefined,
-        next_step: "Use find_scenes with related filters to locate scenes where this place matters, then open targeted scenes with get_scene_prose when prose context is needed.",
       };
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            results: [result],
+            total_count: 1,
+            next_step: "Use find_scenes with related filters to locate scenes where this place matters, then open targeted scenes with get_scene_prose when prose context is needed.",
+          }, null, 2),
+        }],
+      };
     }
   );
 
@@ -635,7 +651,7 @@ export function registerSearchTools(s, {
   // ---- list_scene_references -----------------------------------------------
   s.tool(
     "list_scene_references",
-    "List direct reference documents linked from a scene via metadata (for example, reference_ids). Returns only one-hop scene -> reference links and does not recursively traverse related references. If scene IDs are reused across projects, omitting project_id returns CONFLICT with candidate project_ids.",
+    "List direct reference documents linked from a scene via metadata (for example, reference_ids). Returns only one-hop scene -> reference links and does not recursively traverse related references. If scene IDs are reused across projects, omitting project_id returns CONFLICT with candidate project_ids. Response shape note: returns a structured envelope (`results`, `total_count`) plus the resolved `scene_id` and `project_id` context.",
     {
       scene_id: z.string().describe("Scene ID to inspect."),
       project_id: z.string().optional().describe("Optional project ID to disambiguate duplicate scene IDs across projects."),
@@ -714,9 +730,10 @@ export function registerSearchTools(s, {
         content: [{
           type: "text",
           text: JSON.stringify({
+            results: references,
+            total_count: references.length,
             scene_id: scene.scene_id,
             project_id: scene.project_id,
-            references,
           }, null, 2),
         }],
       };
@@ -869,7 +886,7 @@ export function registerSearchTools(s, {
   // ---- get_relationship_arc ------------------------------------------------
   s.tool(
     "get_relationship_arc",
-    "Show how the relationship between two characters evolves across scenes, in order. Uses explicitly recorded relationship entries — returns nothing if no entries exist yet. Use list_characters to get character_id values.",
+    "Show how the relationship between two characters evolves across scenes, in order. Uses explicitly recorded relationship entries — returns a NO_RESULTS error if no entries exist yet. Use list_characters to get character_id values. Response shape note: returns a structured envelope { results, total_count, from_character, to_character }.",
     {
       from_character: z.string().describe("character_id of the first character (e.g. 'char-sebastian')."),
       to_character:   z.string().describe("character_id of the second character (e.g. 'char-mira-nystrom')."),
@@ -892,7 +909,7 @@ export function registerSearchTools(s, {
       if (rows.length === 0) {
         return errorResponse("NO_RESULTS", `No relationship data found between '${from_character}' and '${to_character}'.`);
       }
-      return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+      return { content: [{ type: "text", text: JSON.stringify({ results: rows, total_count: rows.length, from_character, to_character }, null, 2) }] };
     }
   );