pod
Other formats agents might prefer:
markdownjsonllms.txt

Agent? You probably want markdown or json, or Pod over MCP.

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.

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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 2026-04-28 · closed · 0 comments

The remaining reports are on the project's issue tracker.