SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: port MCP retrieval and write hardening

Browse Source 
- align os MCP/runtime/docs with ra-h contract
- add safe direct node lookup and context-optional flows
- gate edge and context writes behind confirmation
This commit is contained in:
“BeeRad”
2026-04-14 20:57:07 +10:00
parent d825e7a783
commit 929423cb21
35 changed files with 1172 additions and 534 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/8_mcp.md
+12 -3
View File
@@ -7,8 +7,12 @@ RA-H exposes MCP tools for direct graph work against the local database or app A
- `queryNodes` is the primary tool for direct node retrieval when the user is trying to find a specific existing node.
- `retrieveQueryContext` is the primary retrieval entrypoint for substantive current-turn work when the agent needs graph context to support a broader answer.
- `getContext` returns graph orientation: stats, contexts, hubs, and skills.
- `createNode` and `updateNode` accept optional `context_id` but do not require context. Omitting `context_id` is the normal default.
- `createNode`, `updateNode`, and `queryNodes` leave context blank by default.
- If context is intentionally provided, prefer `context_name`.
- `context_id` is an internal implementation detail, not the normal agent-facing field.
- `writeContext` writes one confirmed durable context node and must never be called before explicit user approval.
- `createEdge` is a post-confirmation execution tool. Agents should propose likely edges first and only write them after the user explicitly confirms.
- `updateEdge` is also a post-confirmation execution tool. Agents should only correct an edge after the user explicitly confirms the corrected relationship.
- `queryNodes` searches title, description, and source, with optional context filters.
- `dimensions` are removed from the MCP contract.
@@ -40,8 +44,13 @@ Write:
- Always search before creating.
- If the user is trying to find a specific existing node, use `queryNodes` first.
- If the user is asking a broader question that would benefit from graph context, use `retrieveQueryContext`.
- Prefer explicit context assignment only when the primary scope is clear and a real context is already known.
- Do not send `context_id: null` unless the tool call is intentionally clearing an existing context.
- Optional user memory reinforcement can help, but the MCP tools, instructions, skills, and docs should be enough for the core retrieval and writeback contract to work.
- Prefer explicit context assignment only when the user clearly wants it and a real context is already known.
- Use `context_name` when context is intentionally provided.
- Do not assume the agent needs to think about context during normal node creation, lookup, or update flows.
- Do not assume the server will infer a best-fit context.
- If the user explicitly asked to save or update something and the target artifact is clear, the agent can write after duplicate/update checks.
- If the agent is only suggesting a save, it should propose the node first and wait for confirmation.
- When obvious relationships appear, propose candidate edges briefly rather than writing them automatically.
- Judge graph quality by node quality and edges, not taxonomy completeness.
- Keep writeback prompts terse and selective. The goal is not to ask constantly whether every useful sentence should be saved.