@hanna84/mcp-writing 2.5.0 → 2.6.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.6.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.5.1...v2.6.0)
+
+- feat(styleguide): improve AI navigation with next_step hints and identifier validation [`#89`](https://github.com/hannasdev/mcp-writing.git
+/pull/89)
+
+#### [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)
 
+> 26 April 2026
+
 - feat(styleguide): add prose styleguide bootstrap suggestions [`#87`](https://github.com/hannasdev/mcp-writing.git
 /pull/87)
+- Release 2.5.0 [`3e93d31`](https://github.com/hannasdev/mcp-writing.git
+/commit/3e93d319212a9e8182bc4a272a8c97d806d605f8)
 
 #### [v2.4.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.3.0...v2.4.0)

package/README.md

@@ -10,9 +10,10 @@ Designed to work with [OpenClaw](https://github.com/openclaw/openclaw) but compa
 
 Instead of feeding an entire manuscript to an AI and hoping it fits in the context window, `mcp-writing` builds a structured index from your scene files. The AI queries that index first — finding relevant characters, beats, and loglines — then loads only the specific prose it needs.
 
-**Phase 1:** Read-only analysis. Ask questions about your project.
-**Phase 2:** Metadata write-back. Answers stay accurate as the manuscript evolves.
-**Phase 3 (current):** AI-assisted prose editing with confirmation and version history.
+**Current status:**
+- **Phase 1-3 completed:** Metadata-first analysis, sidecar-backed metadata maintenance, and AI-assisted prose editing with confirmation + git history.
+- **Phase 4 delivered in part:** Review bundles and Scrivener Direct extraction are complete; embedding search and reference-doc querying are intentionally deferred.
+- **Phase 5 in progress:** OpenClaw runtime integration is active.
 
 ## Who it is for
 

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,6 +845,10 @@ async function gracefulShutdown(signal) {
   process.exit(0);
 }
 
+function maxScenesNextStep(matchedCount) {
+  return `Re-run with max_scenes set to at least ${matchedCount}.`;
+}
+
 // ---------------------------------------------------------------------------
 // MCP server factory
 // ---------------------------------------------------------------------------
@@ -1226,6 +1230,7 @@ function createMcpServer() {
             matched_scenes: targetScenes.length,
             max_scenes,
             project_id,
+            next_step: maxScenesNextStep(targetScenes.length),
           }
         );
       }
@@ -1485,6 +1490,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 +1526,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 +1638,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 +1680,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 +1897,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 +2527,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 +2601,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.0",
+  "version": "2.6.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.`,
+        },
       },
     };
   }