feat: sync open-source context and capsule removal
- remove legacy contexts surfaces from the app, MCP bridge, standalone server, and docs - keep getContext and retrieveQueryContext while aligning the simplified graph-only contract - harden dev startup migration behavior and disable the accidental chat surface in open source Generated with Codex
This commit is contained in:
“BeeRad”
+39
-150
@@ -1,116 +1,41 @@
|
||||
# MCP Surface
|
||||
|
||||
This is the full practical setup page for the standalone open-source MCP path.
|
||||
RA-H exposes MCP tools for direct graph work against the local database or app API.
|
||||
|
||||
## 1. What MCP Gives You In RA-H OS
|
||||
Important runtime distinction:
|
||||
|
||||
MCP lets an external agent:
|
||||
- search your existing graph
|
||||
- ground a broader task in relevant graph context
|
||||
- create or update nodes
|
||||
- propose and confirm edges
|
||||
- read and write shared skills
|
||||
|
||||
The graph contract is:
|
||||
- no runtime `dimensions`
|
||||
- optional `contexts`
|
||||
- direct lookup first
|
||||
- broader retrieval only when useful
|
||||
- confirmation-gated durable writeback and edge changes
|
||||
|
||||
## 2. Choose Your Assistant / Client
|
||||
|
||||
Best-supported path:
|
||||
- Claude Code
|
||||
- Claude Desktop
|
||||
|
||||
Also reasonable:
|
||||
- Cursor and similar MCP-capable coding assistants
|
||||
|
||||
Prefer a client that:
|
||||
- supports local stdio MCP servers well
|
||||
- reliably restarts after config changes
|
||||
- lets you pin one package version in config
|
||||
|
||||
## 3. Install The Standalone MCP Server
|
||||
|
||||
Requirements:
|
||||
- Node.js 18-22 LTS recommended
|
||||
- existing RA-H DB created by running the app once
|
||||
- pinned package version in client config
|
||||
|
||||
Package:
|
||||
|
||||
```bash
|
||||
npx --yes ra-h-mcp-server@2.1.2
|
||||
```
|
||||
|
||||
If `better-sqlite3` fails to load:
|
||||
- use Node 18-22 LTS
|
||||
- rebuild native modules if you are developing locally
|
||||
|
||||
## 4. Configure The Assistant With A Pinned Version
|
||||
|
||||
Claude config example:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "npx",
|
||||
"args": ["--yes", "ra-h-mcp-server@2.1.2"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Contributor local-path example:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/absolute/path/to/ra-h_os/apps/mcp-server-standalone/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Restart And Verify The Tools Are Available
|
||||
|
||||
After editing config:
|
||||
- fully restart the client
|
||||
- do not trust a soft window close
|
||||
- ask the assistant whether RA-H tools are available
|
||||
|
||||
Healthy verification usually means you can see tools like:
|
||||
- `queryNodes`
|
||||
- `retrieveQueryContext`
|
||||
- `createNode`
|
||||
- `readSkill`
|
||||
- the app MCP surface talks to the running app/API
|
||||
- the standalone MCP surface talks directly to an existing SQLite DB file
|
||||
- standalone MCP can read and write nodes/edges without the app running, but it does not own chunking or embedding
|
||||
- if standalone MCP writes `nodes.source` while the app is closed, the app later processes that node through startup recovery
|
||||
|
||||
## Core MCP Contract
|
||||
|
||||
- `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`, `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.
|
||||
- `updateEdge` is also post-confirmation only.
|
||||
- `queryNodes` searches title, description, and source, with optional context filters.
|
||||
- `getContext` returns graph orientation: stats, hubs, and skills.
|
||||
- `createEdge` is a post-confirmation execution tool. Agents should propose likely edges first and only write them after the user explicitly confirms.
|
||||
- `queryNodes` searches title, description, and source.
|
||||
- `dimensions` are removed from the MCP contract.
|
||||
|
||||
## Behavior Split
|
||||
|
||||
Internal app MCP surfaces:
|
||||
- talk to the running app/API
|
||||
- can participate in the live app runtime and UI refresh model
|
||||
|
||||
Standalone MCP:
|
||||
- talks directly to an existing SQLite DB
|
||||
- can read and write nodes, edges, and skills without the app running
|
||||
- does not own chunking, vector generation, or schema migration on a live existing DB
|
||||
- relies on the app to process pending `nodes.source` work later
|
||||
|
||||
## Main Tools
|
||||
|
||||
Read:
|
||||
- `retrieveQueryContext`
|
||||
- `getContext`
|
||||
- `queryNodes`
|
||||
- `queryContexts`
|
||||
- `getNodesById`
|
||||
- `queryEdge`
|
||||
- `listSkills`
|
||||
@@ -119,7 +44,6 @@ Read:
|
||||
- `sqliteQuery`
|
||||
|
||||
Write:
|
||||
- `writeContext`
|
||||
- `createNode`
|
||||
- `updateNode`
|
||||
- `createEdge`
|
||||
@@ -127,61 +51,26 @@ Write:
|
||||
- `writeSkill`
|
||||
- `deleteSkill`
|
||||
|
||||
## 6. How The Agent Should Behave With RA-H
|
||||
## Tool Behavior
|
||||
|
||||
- always search before creating
|
||||
- use `queryNodes` first for specific-node intent
|
||||
- use `retrieveQueryContext` when broader graph grounding would help
|
||||
- keep context optional by default
|
||||
- use `context_name` only when context is intentionally provided
|
||||
- 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
|
||||
- keep writeback prompts terse and selective
|
||||
- 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`.
|
||||
- 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.
|
||||
- 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.
|
||||
- Do not assume MCP node creation immediately produces chunks or embeddings. The canonical contract is:
|
||||
- write node data first
|
||||
- app-owned pipeline later creates chunks, FTS rows, and vectors
|
||||
|
||||
Do not assume MCP node creation immediately produces chunks or embeddings. The canonical contract is:
|
||||
- write node data first
|
||||
- app-owned pipeline later creates chunks, FTS rows, and vectors
|
||||
## Memory-File Rule
|
||||
|
||||
## 7. Optional Memory-File Reinforcement
|
||||
Optional assistant memory files can reinforce good behavior, but they are not supposed to be the hidden dependency that makes RA-H work.
|
||||
|
||||
Important distinction:
|
||||
- `CLAUDE.md` is an assistant-native memory/instruction file for Claude Code
|
||||
- `AGENTS.md` is a repo-local instruction file many teams already use
|
||||
- other clients may have their own memory or instruction surfaces
|
||||
|
||||
Rules:
|
||||
- the MCP/tool/docs contract should work without user prompt surgery
|
||||
Current rule:
|
||||
- MCP tools, server instructions, skills, and docs should be enough for the base contract
|
||||
- optional reinforcement can still improve consistency
|
||||
- do not create contradictory instruction files
|
||||
|
||||
Short recommended reinforcement pattern:
|
||||
|
||||
```md
|
||||
Retrieve relevant RA-H context before substantive work, search before creating, and keep durable writeback prompts brief and confirmation-gated.
|
||||
```
|
||||
|
||||
## 8. Troubleshooting And Common Failure Cases
|
||||
|
||||
`Tools not found`
|
||||
- fully restart the client
|
||||
- verify the config path is the one your client actually uses
|
||||
- run the pinned package manually once
|
||||
|
||||
`Database not found`
|
||||
- run the RA-H app once first so the DB exists
|
||||
- confirm `RAH_DB_PATH` if using a custom path
|
||||
|
||||
`Node writes land but embeddings/chunks are missing`
|
||||
- this is usually expected when the app is closed
|
||||
- standalone MCP writes node data first
|
||||
- the app later processes pending `nodes.source` work
|
||||
|
||||
`Native module load failure`
|
||||
- use Node 18-22 LTS
|
||||
- rebuild `better-sqlite3` if needed for local development
|
||||
|
||||
`Version drift`
|
||||
- pin the package version in client config
|
||||
- bump the pinned version intentionally when testing a new release
|
||||
- avoid contradictory instruction files across `CLAUDE.md`, `AGENTS.md`, and other client-specific memory surfaces
|
||||
|
||||
Reference in New Issue
Block a user