Prompt file imported from ncastaldi/nexus-mcp (.github/prompts/plan-saveReportTool.prompt.md). Copyright stays with the author.

Plan: Add save_report Tool to nexus-mcp

TL;DR

Add a new save_report MCP tool that accepts a title and markdown content, then writes it as a .md file to the configured reports directory (./documentation/output-reports/). Implemented as a new reports.py shard — consistent with the existing shard pattern and aligned with the pre-staged generate_* tools referenced in the README. All dependencies (aiofiles, ReportConfig) are already present.

Branch Identity

• Branch name: feat/add-save-report-tool

Steps

Phase 1 — Create the shard

1. Create nexus-mcp/src/shards/reports.py
   • Define register(mcp: FastMCP) -> None
   • Inside, define save_report(title, content, subfolder, filename) as @mcp.tool() async fn
   • Use ReportConfig from lib/config.py for output_dir
   • Slugify title → safe filename; add ISO timestamp suffix to avoid collisions
   • mkdir(parents=True, exist_ok=True) on resolved path
   • Write file using aiofiles.open(..., "w")
   • Return {"status": "saved", "path": str(abs_path), "filename": final_filename, "size_bytes": N}

Phase 2 — Register the shard in main.py

2. In nexus-mcp/src/main.py:
   • Import the new shard: from shards import reports
   • Add conditional registration block (matches existing pattern): if os.getenv("ENABLE_REPORTS", "true").lower() == "true": reports.register(mcp)
   • Placement: after the existing shard registrations, before audit middleware wrapping

Phase 3 — Environment config

3. Add ENABLE_REPORTS=true to nexus-mcp/.env (if file exists; else note it as optional)

Relevant Files

• nexus-mcp/src/shards/reports.py — NEW file to create
• nexus-mcp/src/main.py — add shard import + conditional registration
• nexus-mcp/lib/config.py — reuse ReportConfig (specifically output_dir: Path)
• nexus-mcp/.env — add ENABLE_REPORTS=true
• nexus-mcp/pyproject.toml — no changes needed (aiofiles, jinja2, tabulate already listed)

Verification

1. Restart nexus-mcp server; tool list should include save_report
2. Call save_report(title="Test Report", content="# Hello\nThis is a test.") from Claude
3. Verify file appears at nexus-mcp/reports/test-report-<timestamp>.md
4. Call nexus_audit_recent and confirm a save_report entry was logged
5. Run existing tests: cd nexus-mcp && python -m pytest tests/

Decisions

• New shard (reports.py) over adding to main.py — keeps built-ins minimal, aligns with planned generate_* tools
• aiofiles for async writes — already a dependency, correct for async tool context
• Timestamp in filename — prevents silent overwrite collisions
• Default ENABLE_REPORTS=true — safe; no external API calls, pure local I/O
• Scope: only save_report — user requested this one tool; generate_* stubs are out of scope

Out of Scope

• Implementing planned generate_* tools
• A list_reports or delete_report tool
• Any templating (Jinja2) or formatting logic beyond saving raw markdown