Skip to content

MCP typed_walk tool: handles only, CLI limits, refuse unknown edge type (MN-REQ-14.7 slice, #247) - #256

Merged
chouswei merged 8 commits into
masterfrom
feat/typed-walk-mcp
Nov 4, 2026
Merged

chouswei merged 8 commits into
masterfrom
feat/typed-walk-mcp

Conversation

@chouswei

@chouswei chouswei commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Why

Owner goal (t999u, 2026-11-04 13:03 TPE): LLM agents can run typed walks over MCP, with handles only. No real id ever appears on the LLM MCP surface, and handles are opaque. The limits match the CLI. An unknown edge type is refused instead of returning an empty walk. This is the MN-REQ-14.7 slice for typed walks, #247 item 2.

What

  • New MCP tool typed_walk. Its arguments are start, edge_type, direction="out", min_hops=1, max_hops=1, where=None, limit=50, session, caller. It routes query typed-walk --json-handles, so it works in-process and through TCP serve. serve.py, serve_pool.py and upgrade.py are not touched.
  • Reply on success. {ok, exit_code, session_id, errors, walk:{type,dir,hops,limit}, rows:[{row,hops,start:{kind,handle},steps:[{edge:{type,dir,handle},node:{kind,handle[,props]}}]}], stats:{rows,truncated,cursor:null}}.
    • Only the END node of each row carries props, with id, hid and elementId removed.
    • Any value that is a live nickname or hid is dropped. An id inside a longer value is masked.
  • Reply on error. {ok:false, error:{code,message}}. The error text is scrubbed of ids.
  • Handles. A handle is h_ plus 26 base32 chars of HMAC-SHA256 keyed by the session id, over the node or edge nickname (or the hid when a node has no nickname).
    • A handle is one-way, so it is opaque.
    • A handle from another session never resolves (stale_handle). Neither does a handle of a deleted node.
    • No new table, and no change to the snapshot format.
    • start accepts a handle or a nickname from find.
  • Limits. The tool reuses the typed_walk.py constants: limit 1..500 (default 50), 20,000 typed edge reads and 1,048,576 reply bytes. Truncation shows up in stats.truncated as limit, budget or bytes.
  • Fold-in. An edge type that no edge in the session has is now refused unknown_relation in the engine, so the CLI and MCP both refuse it.
  • Model. CI's model check needed two small edits, so they are in this PR:
    • typed_walk is listed in the requirements.sysml READ-SURFACES block and in tests/evict_surfaces.py.
    • Two verify.sysml test refs are renamed to match the updated typed-walk tests.

Proof

  • Real proof. I started a real memnet serve on :38765 and connected a real memnet-mcp over stdio with MEMNET_MCP_TRANSPORT=tcp.
    • A 3-hop walk from a nickname returned 3 rows with handles.
    • Continuing from row 1's end handle worked.
    • The same handle sent to a second session was refused stale_handle.
    • NO_SUCH was refused unknown_relation, and limit=501 was refused limit_out_of_range.
    • limit=1 set truncated: limit. The default limit came back as 50.
    • A scan of every reply found no real id (nickname, edge id or _elN).
  • Tests. The full suite passes: 1,582 on master, about 1,602 on this branch, with 0 failures. ruff check and ruff format pass on the CI paths. The new file tests/test_typed_walk_mcp.py has 18 tests. Each protection was removed in turn to confirm a test fails without it.

LATER

  • The full 14.7 work: find, mutate, pin_map and the other tools still return real ids. A persisted HandleTable is still needed.
  • Handles for nodes without a nickname come from the process-local hid, so they don't survive save and load. Nicknamed nodes are stable.
  • The unknown_relation check is an O(E) scan. An O(1) per-relation count needs a mem_store.py edit.
  • requirements.sysml 14.3 still says MCP waits for 14.7, and 14.7 is still marked PROPOSAL. Both need a model follow-up.
  • The .cursor/skills/mcp-memnet tool table doesn't list typed_walk yet.

@chouswei
chouswei merged commit 318cbc0 into master Nov 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants