nathan
8727257605
- Update prompt model frontmatter in code-review and feature-add prompts to Claude Sonnet 4.6 (copilot) - Add a save_report implementation plan prompt to support next-session delivery and clearer handoff context
67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# 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
|