feat: filter frame counters + tool descriptions (PR-FRAME-3)

[HumanBean17]

Scope

Implements plans/PLAN-MCP-FRAME.md PR-FRAME-3: process-local fail-loud counters (mcp_v2.py), refreshed MCP tool descriptions (server.py), agent guide strict-frame + identifier fallback (docs/AGENT-GUIDE.md), and four counter tests (tests/test_mcp_v2.py).

Related: propose/MCP-FILTER-FRAME-PROPOSE.md (revisit trigger §3.4.6, identifier fallback §3.4.7).

Changes

• _fail_loud_counts / _fail_loud_lock, _log_fail_loud(category), filter_frame_counters() in mcp_v2.py; wired on filter ValidationError, applicability, and wildcard paths in search_v2, find_v2, neighbors_v2.
• All four MCP tool description= strings updated in server.py.
• docs/AGENT-GUIDE.md: strict frame contract, identifier-resolution pattern (search + describe per candidate until resolve), corrected neighbors.filter semantics.

Tests

PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python -m pytest tests/test_mcp_v2.py tests/test_mcp_tools.py -q
PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python -m pytest tests -q

Manual evidence

With an initialized Kuzu graph (same as MCP), fail-loud events increment counters:

import sys; sys.path.insert(0, ".")
from mcp_v2 import find_v2, filter_frame_counters

find_v2("symbol", {"path_prefix": "/api"}, graph=<your KuzuGraph>)
find_v2("symbol", {"fqn_prefix": "com.foo.*"}, graph=<your KuzuGraph>)

counters = filter_frame_counters()
assert counters.get("applicability", 0) >= 1
assert counters.get("wildcard", 0) >= 1

Without graph=, find_v2 may fail on DB open before filter validation; use MCP host context or tests.

Ontology / reindex

None.

Made with Cursor