diff --git a/CHANGELOG.md b/CHANGELOG.md index ff88f65..26c8164 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,20 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### Added +- **MCP tool metadata (WP13)** — every server tool now ships + `ToolAnnotations` (`readOnlyHint`/`destructiveHint`/`idempotentHint`, + `openWorldHint=False`), a description for every inputSchema parameter + (previously 0% coverage — bare type hints), and when-to-use guidance with + sibling cross-references and side-effect disclosure (extraction on add, + first-call model download, lazy proposal expiry on queue listing). + Tool names, parameters, and call behavior are unchanged, except that + `memory_search.k` and `memory_review_queue.limit` now declare a schema + minimum of 1 (nonsensical values are rejected at validation instead of + passing through). + Contract pinned in `tests/test_mcp_tool_metadata.py`. Motivated by the + Glama directory audit scoring `memory_search`/`memory_add` 3.2–3.3/5 on + exactly these axes. + - **Update-integrity benchmark (WP2)** — `bench/update_integrity.py`: ten scripted supersession scenarios through the public API (current-truth top-1, retirement flags, `as_of` readback, restart persistence), rendered diff --git a/docs/superpowers/workpackets.md b/docs/superpowers/workpackets.md index 2e4a545..650ee32 100644 --- a/docs/superpowers/workpackets.md +++ b/docs/superpowers/workpackets.md @@ -45,6 +45,7 @@ on the same files). | Memory UI | `worktree-memory-ui` | D | — | — | **MERGED** (2026-07-14: PR #2 → main 9d840b6; console 125 + core 141 green on merged main; lane D released) | | WP12 mcp 2.0 migration | `worktree-wp12-mcp2-migration` | A | — | none — dependency-driven | **MERGED** (2026-07-29: PR #10 → main 4efe4ca; dual-path compat, pin widened to mcp>=1.2,<3; fixed the 2.0 worker-thread SQLite crash (check_same_thread=False, serialized); all four suite combos green locally, CI green on fresh-resolved 2.0; ship as v0.2.3 pending user go-ahead; lane A released) | | WP11 Write-time restatement dedupe | `worktree-wp11-restatement-dedup` | A | — | — | **MERGED** (2026-07-29: PR #7 → main 52d21fd; core 289 + console 153 green on merged branch; rode along: mcp>=1.2,<2 pin for the mcp 2.0.0 fastmcp removal, gated WP9 LLM-judge design doc; lane A released) | +| WP13 MCP tool metadata (Glama audit) | `worktree-wp12-mcp-tool-metadata` | A | — | — | claimed 2026-07-29 (branch name predates the renumber: claimed as WP12 concurrently with the mcp 2.0 migration, renumbered on merge) — annotations + param descriptions + usage guidance on all 7 server tools; no behavior change beyond k/limit schema minimums; contract pinned in `tests/test_mcp_tool_metadata.py` | Lanes: **A** = engine/API surface (`src/lean_memory/` hot zone — strictly sequential within the lane). **B** = benchmarks (`bench/` — parallel-safe with diff --git a/src/lean_memory/mcp_server.py b/src/lean_memory/mcp_server.py index 71cf906..0026906 100644 --- a/src/lean_memory/mcp_server.py +++ b/src/lean_memory/mcp_server.py @@ -20,7 +20,10 @@ import os import sys from pathlib import Path -from typing import Any, Optional +from typing import Annotated, Any, Optional + +from mcp.types import ToolAnnotations +from pydantic import Field from ._mcp_compat import make_stdio_server @@ -152,17 +155,114 @@ def _namespace_path(namespace: str) -> Path: return _mem().root / f"{safe}.db" -@mcp.tool() -def memory_add(namespace: str, text: str) -> str: - """Ingest text into the namespace's memory. Returns how many facts were written.""" +# Directory graders and agent clients read tool quality off exactly what +# `tools/list` ships: description + inputSchema + annotations. The contract +# (annotations honest per tool, every parameter described, siblings +# cross-referenced, side effects disclosed) is pinned by +# tests/test_mcp_tool_metadata.py — keep it green when editing metadata here. + +# Every tool takes `namespace`; the semantics are identical everywhere, so the +# schema description is shared. Each namespace is one SQLite file (BET 4). +_NS = Annotated[ + str, + Field( + description=( + "Isolation key for one memory store. Each namespace is a separate " + "local SQLite file under LM_DATA_ROOT (default ~/.lean_memory); " + "namespaces never see each other's facts. Use one per agent, " + "project, or user whose memory must stay separate. Created on " + "first access." + ) + ), +] + +# Local-engine annotation baseline: everything operates on local SQLite files — +# a closed world (openWorldHint=False on every tool). + + +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=False, + destructiveHint=False, + idempotentHint=False, + openWorldHint=False, + ) +) +def memory_add( + namespace: _NS, + text: Annotated[ + str, + Field( + description=( + "Natural-language text to remember (a message, note, or " + "observation). It is distilled into discrete facts, not " + "stored verbatim." + ) + ), + ], +) -> str: + """Distill durable facts from text and write them to a namespace's memory. + + The raw text is NOT stored verbatim: an extraction pass distills it into + discrete facts, which are embedded and indexed for memory_search. Returns + how many facts were written (possibly 0 if nothing extractable). Additive + only — never overwrites or deletes existing facts; contradictions are + handled by supersession, with full history retained. Creates the namespace + on first write. + + Use it after learning durable information worth recalling in later + sessions (preferences, decisions, biographical facts) — not for transient + chatter, and not to re-state facts already in memory (use memory_search to + check what is already known; use memory_clear to delete a namespace). + With the [extract]/[models] extras installed, the first call in a fresh + environment downloads model weights (one-time, can take minutes); the call + blocks until done. + """ written = _mem(namespace).add(namespace, text) n = len(written) return f"wrote {n} fact{'s' if n != 1 else ''}" -@mcp.tool() -def memory_search(namespace: str, query: str, k: int = 5) -> str: - """Search a namespace's memory and return the top-k facts as a bulleted list.""" +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=True, + openWorldHint=False, + ) +) +def memory_search( + namespace: _NS, + query: Annotated[ + str, + Field( + description=( + "Natural-language search query; matched against stored facts " + "by hybrid vector + full-text retrieval, then reranked." + ) + ), + ], + k: Annotated[ + int, + Field( + description="Maximum number of facts to return (top-k after reranking).", + ge=1, + ), + ] = 5, +) -> str: + """Retrieve the facts most relevant to a query from a namespace's memory. + + Read-only with respect to memory content: it never modifies or deletes + stored facts (searching a namespace that does not exist yet returns + "No facts found.", though the empty store file is created as a side + effect). Returns up to k facts as a bulleted list, + deduplicated, most relevant first. + + Use it before answering anything that may depend on prior context — + preferences, past decisions, earlier sessions. Facts only exist here if + something wrote them via memory_add; memory_clear deletes a whole + namespace. With the [models] extra installed, the first call in a fresh + environment downloads model weights (one-time); the call blocks until + done. + """ hits = _mem(namespace).search(namespace, query, k=k) if not hits: return "No facts found." @@ -180,9 +280,20 @@ def memory_search(namespace: str, query: str, k: int = 5) -> str: return "\n".join(bullets) -@mcp.tool() -def memory_clear(namespace: str) -> str: - """Delete all memory for a namespace by removing its SQLite file. Irreversible. +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=False, + destructiveHint=True, + idempotentHint=True, + openWorldHint=False, + ) +) +def memory_clear(namespace: _NS) -> str: + """Delete ALL memory for a namespace by removing its SQLite file. Irreversible. + + Use only when the namespace's entire history should be forgotten; there is + no per-fact deletion. Idempotent — clearing a missing namespace succeeds as + a no-op. Other namespaces are untouched. Refuses (returns an explanatory message, changing nothing) while a LIVE maintenance lease with a fresh heartbeat is held for the namespace (spec §7.3): a POSIX unlink @@ -229,8 +340,28 @@ def memory_clear(namespace: str) -> str: # CLI. memory_maintenance_status is provably model-free (it never calls _mem()). -@mcp.tool() -def memory_maintenance_run(namespace: str, apply: bool = False) -> dict[str, Any]: +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=False, + destructiveHint=False, + idempotentHint=False, + openWorldHint=False, + ) +) +def memory_maintenance_run( + namespace: _NS, + apply: Annotated[ + bool, + Field( + description=( + "False (default): dry-run — compute the full would-do report " + "with zero writes. True: claim the maintenance lease, apply " + "the provably-safe auto band, and stage judgment-call " + "proposals for review via memory_review_queue." + ) + ), + ] = False, +) -> dict[str, Any]: """Run one sleep-time maintenance pass on a namespace (§6.3). DRY-RUN by default (apply=False): computes the full would-do report with ZERO @@ -247,8 +378,13 @@ def memory_maintenance_run(namespace: str, apply: bool = False) -> dict[str, Any return _report_to_dict(namespace, report, apply=apply, auto_only=False) -@mcp.tool() -def memory_maintenance_status(namespace: str) -> dict[str, Any]: +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=True, + openWorldHint=False, + ) +) +def memory_maintenance_status(namespace: _NS) -> dict[str, Any]: """Report a namespace's maintenance ledger — runs + pending proposals (§6.3). MODEL-FREE by contract: this reads the namespace DB directly and NEVER builds the @@ -258,27 +394,74 @@ def memory_maintenance_status(namespace: str) -> dict[str, Any]: return mcp_support.read_status(_data_root(), namespace) -@mcp.tool() +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=False, # listing lazily EXPIRES overdue proposals — a write + destructiveHint=False, + openWorldHint=False, + ) +) def memory_review_queue( - namespace: str, kind: Optional[str] = None, limit: int = 20 + namespace: _NS, + kind: Annotated[ + Optional[str], + Field( + description=( + "Filter to one proposal kind: 'dedup_near' | 'summarize' | " + "'evict'. Omit (null) for all kinds." + ) + ), + ] = None, + limit: Annotated[ + int, + Field(description="Maximum number of proposals returned.", ge=1), + ] = 20, ) -> str: """List pending maintenance proposals, grouped by entity, with evidence (§6.3). Each group carries the subject entity and its proposals; each proposal includes its - parsed `payload` (the evidence) so a reviewer sees what would change. `kind` filters - to one of 'dedup_near' | 'summarize' | 'evict'. Overdue proposals lazily expire. - Returns a JSON string (the grouped list). + parsed `payload` (the evidence) so a reviewer sees what would change. Not fully + read-only: overdue proposals lazily expire (are marked expired) as a side effect of + listing. Returns a JSON string (the grouped list). Use memory_review_decide to act + on a listed proposal. """ groups = _mem(namespace).review_queue(namespace, kind=kind, limit=limit) return json.dumps(groups, sort_keys=True, default=str) -@mcp.tool() +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=False, + destructiveHint=False, # ADD-only spine: approvals supersede, never erase + idempotentHint=False, + openWorldHint=False, + ) +) def memory_review_decide( - namespace: str, - proposal_id: str, - decision: str, - edited_text: Optional[str] = None, + namespace: _NS, + proposal_id: Annotated[ + str, + Field(description="ID of a pending proposal, as listed by memory_review_queue."), + ], + decision: Annotated[ + str, + Field( + description=( + "One of 'approve' | 'reject' | 'edit' | 'promote'. 'edit' is " + "valid only for summarize proposals; 'promote' only for evict " + "proposals." + ) + ), + ], + edited_text: Annotated[ + Optional[str], + Field( + description=( + "Human-edited replacement summary text. Required when " + "decision='edit'; ignored otherwise." + ) + ), + ] = None, ) -> str: """Decide a maintenance proposal: approve | reject | edit | promote (§6.3). diff --git a/tests/test_mcp_tool_metadata.py b/tests/test_mcp_tool_metadata.py new file mode 100644 index 0000000..69b6475 --- /dev/null +++ b/tests/test_mcp_tool_metadata.py @@ -0,0 +1,106 @@ +"""Tool metadata contract for the MCP server (WP13). + +MCP directories (e.g. Glama) grade each tool on exactly what the server sends +over `tools/list`: the description and the inputSchema. Three things they (and +real agents) need are pinned here: + +* **Annotations** — `readOnlyHint` / `destructiveHint` / `idempotentHint` / + `openWorldHint` so a client knows what a call does to the world before + making it. +* **Parameter descriptions** — FastMCP builds the schema from type hints; + bare hints ship a schema with 0% description coverage. Every parameter + must carry a non-empty description. +* **Usage guidance** — each memory tool's description names its sibling + tools so an agent can pick between alternatives, and discloses non-obvious + behavior (extraction on add, the first-call model download). + +Offline: metadata lives on the FastMCP registry; no Memory is ever built. +""" + +from __future__ import annotations + +import pytest + +pytest.importorskip("mcp", reason="optional [mcp] extra not installed") + + +@pytest.fixture(scope="module") +def tools(tmp_path_factory): + import os + + os.environ.setdefault("LM_DATA_ROOT", str(tmp_path_factory.mktemp("lm"))) + import lean_memory.mcp_server as srv + + return {t.name: t for t in srv.mcp._tool_manager.list_tools()} + + +# What each tool does to the world. memory_review_queue is NOT read-only: +# listing lazily expires overdue proposals (a write). memory_maintenance_run +# defaults to dry-run but apply=True writes, so it cannot claim read-only. +EXPECTED_HINTS = { + "memory_add": {"readOnlyHint": False, "destructiveHint": False}, + "memory_search": {"readOnlyHint": True}, + "memory_clear": { + "readOnlyHint": False, + "destructiveHint": True, + "idempotentHint": True, + }, + "memory_maintenance_run": {"readOnlyHint": False, "destructiveHint": False}, + "memory_maintenance_status": {"readOnlyHint": True}, + "memory_review_queue": {"readOnlyHint": False, "destructiveHint": False}, + "memory_review_decide": {"readOnlyHint": False, "destructiveHint": False}, +} + + +def test_metadata_covers_the_whole_tool_surface(tools): + """EXPECTED_HINTS goes RED the moment a tool is added or dropped.""" + assert set(tools) == set(EXPECTED_HINTS) + + +@pytest.mark.parametrize("name", sorted(EXPECTED_HINTS)) +def test_tool_declares_behavior_annotations(tools, name): + ann = tools[name].annotations + assert ann is not None, f"{name}: no ToolAnnotations declared" + # Wire names, valid on both SDK majors: mcp 1.x fields ARE camelCase; + # mcp 2.0 renamed them snake_case with camelCase serialization aliases. + dumped = ann.model_dump(by_alias=True) + for hint, want in EXPECTED_HINTS[name].items(): + assert dumped.get(hint) is want, f"{name}: {hint} should be {want}" + # Everything operates on local SQLite under LM_DATA_ROOT — a closed world. + assert dumped.get("openWorldHint") is False, f"{name}: openWorldHint should be False" + + +@pytest.mark.parametrize("name", sorted(EXPECTED_HINTS)) +def test_every_parameter_has_a_description(tools, name): + props = (tools[name].parameters or {}).get("properties", {}) + assert props, f"{name}: schema has no properties" + missing = [p for p, spec in props.items() if not spec.get("description", "").strip()] + assert not missing, f"{name}: parameters without descriptions: {missing}" + + +def test_namespace_is_defined_wherever_it_appears(tools): + """Every tool takes `namespace`; each must say what a namespace IS (an + isolation key for a separate local store), not just repeat the name.""" + for name, tool in tools.items(): + desc = tool.parameters["properties"]["namespace"]["description"] + assert "isolat" in desc.lower(), f"{name}: namespace description lacks isolation semantics: {desc!r}" + + +def test_memory_tools_cross_reference_alternatives(tools): + """'When to use X vs Y' guidance: each core memory tool names a sibling.""" + assert "memory_search" in tools["memory_add"].description + assert "memory_add" in tools["memory_search"].description + assert "memory_clear" in tools["memory_search"].description or ( + "memory_clear" in tools["memory_add"].description + ) + + +def test_descriptions_disclose_side_effects(tools): + add = tools["memory_add"].description + search = tools["memory_search"].description + # add does NOT store raw text — it extracts facts (surprising, disclose it). + assert "extract" in add.lower() + # First call with the [models]/[extract] extras downloads model weights. + assert "download" in add.lower() or "download" in search.lower() + # search must say it never modifies stored memory. + assert "read-only" in search.lower()