# Reported issues for Writing MCP

Pod holds 16 of 17 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Writing MCP](/mcp/writing-mcp).

## Most discussed

### Tooling usability: publish 2.x -> 3.0.0 migration guide and canonical map

## What to build

Produce the authoritative migration guide for the tooling convention transition from `2.x` to `3.0.0`, including canonical naming, parameter changes, response envelope changes, and example rewrites.

## Acceptance criteria

- [ ] Migration guide maps old tool IDs to canonical names.
- [ ] Migration guide maps legacy parameter variants to canonical parameters.
- [ ] Migration guide documents response envelope changes expected in `3.0.0`.
- [ ] Guide includes before/after example

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/156) · 2026-04-30 · closed · 1 comment

### Tooling usability: enforce preview-first flow for risky or large writes

## What to build

Implement and document preview-first behavior for risky or large write operations so users/agents confirm intent before applying impactful changes.

## Acceptance criteria

- [ ] Risky/large write operations have a preview-first path (`*.preview` or equivalent).
- [ ] Non-preview write attempts provide actionable guidance when preview is expected.
- [ ] Error responses include clear `next_step` guidance for safe continuation.
- [ ] Integration tests validate preview->apply flow

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/155) · 2026-04-30 · closed · 1 comment

### Tooling usability: add parameter normalization wrappers for priority workflows

## What to build

Add compatibility wrappers in `2.x` that normalize legacy parameter variants into the new canonical parameter shapes for priority workflows (scenes, edits, review bundles, styleguide).

## Acceptance criteria

- [ ] Canonical parameter naming is documented and accepted for priority workflows.
- [ ] Legacy parameter variants continue to function in `2.x` and map to canonical inputs.
- [ ] Validation/error messages point users toward canonical parameter names.
- [ ] Unit/integrat

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/154) · 2026-04-30 · closed · 1 comment

### Tooling usability: expose alias metadata in 2.x while preserving legacy IDs

## What to build

Expose canonical alias naming in server metadata and docs in `2.x` while keeping existing legacy tool IDs fully supported for compatibility.

## Acceptance criteria

- [ ] Alias metadata is available for tool discovery surfaces in `2.x`.
- [ ] Legacy IDs remain functional and unchanged in runtime behavior.
- [ ] Canonical alias naming is consistently preferred in examples/docs.
- [ ] Integration tests verify both canonical alias metadata presence and legacy ID compatibility.

#

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/153) · 2026-04-30 · closed · 1 comment

### Tooling usability: tiered docs surface and beginner menu

## What to build

Update docs/discovery surfaces to consistently present tool tiers (`core`, `advanced`, `admin`) and a beginner-first menu, while preserving full reference access.

## Acceptance criteria

- [ ] Tool documentation clearly tags each tool with its tier.
- [ ] Beginner menu is documented and aligned with the PRD core list.
- [ ] Full reference remains available without removing advanced/admin visibility.
- [ ] `describe_workflows` and related discoverability docs reflect tiering la

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/152) · 2026-04-30 · closed · 1 comment

### Tooling usability: deterministic recommend_next_tool MVP

## What to build

Implement an MVP `recommend_next_tool` helper that routes common user goals to a recommended tool and starter arguments using deterministic mapping/rules (not free-form suggestion logic).

## Acceptance criteria

- [ ] `recommend_next_tool` tool exists and returns deterministic recommendations for an initial curated goal set.
- [ ] Output includes: `recommended_tool`, `arguments`, `why`, `alternatives` (0-3), `next_step_on_success`, `next_step_on_error`.
- [ ] Unknown goals ret

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/151) · 2026-04-30 · closed · 1 comment

### Define release-log rollover in release workflow

## Summary

Our `docs/release-log.md` uses an `## Unreleased` section, but we do not currently have a formal release step that rolls those entries into a versioned section at release time.

## Problem

Without a defined rollover step, the release log can drift from actual published versions and become harder to trust over time.

## Proposal

Add an explicit maintainer workflow step for release-log rollover when cutting a new release.

## Scope

- Define the expected release-log structure before 

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/149) · 2026-04-30 · closed · 0 comments

### Init project flow: scaffold + guided first sync setup

## Summary
Reduce first-time setup friction with an `init_project` flow for folder scaffolding and guided sync setup.

## Problem
New users currently need multiple manual setup steps before first useful workflow, increasing failure rate.

## Scope
- Define minimum project scaffold expected by writing workflows.
- Add an initialization flow/tool that creates required structure safely.
- Provide guided next steps for Scrivener External Folder Sync and verification.
- Ensure the flow is idempotent 

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/138) · 2026-04-29 · open · 0 comments

## Most recent

### Continuity checker MVP for scene/entity consistency

## Summary
Design and implement a continuity-checker MVP for draft cleanup.

## Problem
Continuity mismatches currently require manual discovery and are easy to miss in larger projects.

## Scope
- Define initial continuity checks with low false-positive risk, e.g.:
  - character appears in scene prose but not linked in metadata;
  - place appears in scene prose but not linked in metadata;
  - obvious timeline sequence anomalies from indexed metadata.
- Decide delivery surface (new tool vs exten

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/137) · 2026-04-29 · open · 0 comments

### Reference docs Phase 4A: lightweight indexing + search_reference

## Summary
Implement Phase 4A lightweight reference-doc indexing and querying.

## Problem
Reference notes (world/research/continuity) are hard to query consistently; users need searchable metadata-level access.

## Scope
- Add minimal `reference_docs` indexing schema.
- Add folder-based type inference (`world`, `continuity`, `style`, `research`).
- Add lightweight FTS on titles/tags (not full doc content).
- Add `search_reference(query, type?, tag?)` tool returning metadata and file path.
- Add

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/136) · 2026-04-29 · closed · 0 comments

### Embeddings Phase 4A: semantic search baseline + backend decision

## Summary
Run a Phase 4A embeddings spike to compare semantic retrieval quality/cost/latency against current FTS5 behavior and select a backend direction.

## Problem
Current search is keyword-driven; semantic intent queries remain weak.

## Scope
- Define representative semantic query benchmark set.
- Compare baseline FTS5 vs candidate embedding approaches.
- Evaluate backend tradeoffs (OpenAI vs Ollama vs Hugging Face).
- Recommend initial backend with rationale and operational constraints.

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/135) · 2026-04-29 · closed · 0 comments

### OpenClaw M4: doctor diagnostics for integration failures

## Summary
Add OpenClaw-focused doctor diagnostics to self-diagnose common integration failures.

## Problem
Users can detect failures, but there is limited guided diagnosis for runtime/transport/bundle misconfiguration.

## Scope
- Extend doctor coverage for OpenClaw-related checks.
- Validate runtime prerequisites and transport reachability.
- Validate bundle/skill presence and discoverability.
- Provide transport-specific failure guidance.

## Acceptance Criteria
- Doctor output distinguishes

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/134) · 2026-04-29 · open · 0 comments

### OpenClaw M3: setup helper CLI (preview + write modes)

## Summary
Add an OpenClaw setup helper CLI to reduce first-run setup friction.

## Problem
Current setup is manual and error-prone across transport/config/runtime choices.

## Scope
- Implement setup helper command(s) for OpenClaw integration.
- Support both:
  - print/review mode (show generated config without writing), and
  - automatic write mode (apply recommended config).
- Provide transport-aware setup output and next-step verification guidance.

## Acceptance Criteria
- A user can run on

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/133) · 2026-04-29 · open · 0 comments

### OpenClaw M2: bundle + skill packaging for workflow guidance

## Summary
Ship OpenClaw bundle + skill packaging that teaches intended `mcp-writing` workflows (metadata-first, explicit edit flow, review-bundle flow).

## Problem
Raw MCP tool exposure does not encode safe/intended workflow order for agents.

## Scope
- Add OpenClaw-detectable bundle structure in repo.
- Include `skills/` packaging for OpenClaw usage guidance.
- Provide install instructions for local directory/packaged bundle use.
- Ensure skill guidance aligns with actual tool contract.

## 

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/132) · 2026-04-29 · open · 0 comments

### OpenClaw M1: official manual integration paths (stdio + SSE)

## Summary
Officially support manual OpenClaw integration with two documented transport paths: `stdio` (recommended local default) and `HTTP/SSE` (persistent service / Docker / homeserver).

## Problem
OpenClaw users can connect MCP servers, but setup/verification is fragmented and transport choice is unclear.

## Scope
- Add/align docs for `stdio` registration path.
- Add/align docs for `HTTP/SSE` registration path.
- Add a single verification checklist for both transports.
- Document when to p

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/131) · 2026-04-29 · open · 0 comments

### refactor: remove root compatibility shims after src/core migration

## Summary

Remove temporary root compatibility shims introduced during root-structure reorganization, and switch remaining internal imports to final src-owned module paths.

## Why

Phase 2 intentionally preserved root shims for compatibility. Keeping them indefinitely risks accidental root coupling and can hide path regressions.

## Scope

- Move remaining core modules into src/core/.
- Update internal imports to final src paths (no runtime/tool/script imports from root shim modules).
- Remove

[Read the thread](https://github.com/hannasdev/mcp-writing/issues/121) · 2026-04-28 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/hannasdev/mcp-writing/issues).