docs: update documentation for RA-H Light
- Rewrite 0_overview.md for 2-panel UI + MCP focus - Delete 1_architecture.md (agent hierarchy no longer applies) - Delete 3_context-and-memory.md (agent context no longer applies) - Rewrite 4_tools-and-workflows.md for MCP tools only - Rewrite 6_ui.md for 2-panel layout - Delete 7_voice.md (voice removed) - Update 8_mcp.md with correct tool list (11 tools) - Rewrite 9_open-source.md for RA-H Light - Update README.md with new doc structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
“BeeRad”
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
ea61ef1023
commit
f383d770ca
+79
-45
@@ -1,44 +1,63 @@
|
||||
# RA-H MCP Server
|
||||
# MCP Server
|
||||
|
||||
> How to connect Claude Code and other AI assistants to your knowledge base.
|
||||
|
||||
**How it works:** The RA-H desktop app runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and extract content from URLs. Everything stays on your Mac; nothing goes to the cloud.
|
||||
**How it works:** RA-H Light runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and manage your knowledge graph. Everything stays local; nothing goes to the cloud.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Launch the RA-H desktop app (it boots the MCP server automatically)
|
||||
2. Open **Settings → External Agents** inside RA-H and copy the connector URL
|
||||
3. Configure your assistant (see below)
|
||||
4. Talk naturally: "Summarize this and add it to RA-H"
|
||||
1. Start RA-H Light: `npm run dev`
|
||||
2. Configure your AI assistant (see below)
|
||||
3. Use naturally: "Search RA-H for my notes on X" or "Add this to RA-H"
|
||||
|
||||
---
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_add_node` | Create a new node (title/content/dimensions) |
|
||||
| `rah_search_nodes` | Search existing nodes before creating duplicates |
|
||||
| `rah_youtube_extract` | Extract transcript from YouTube video |
|
||||
| `rah_website_extract` | Extract content from web page |
|
||||
| `rah_paper_extract` | Extract text from PDF |
|
||||
| `rah_search_nodes` | Search existing nodes |
|
||||
| `rah_update_node` | Update an existing node |
|
||||
| `rah_get_nodes` | Get nodes by ID |
|
||||
| `rah_create_edge` | Create relationship between nodes |
|
||||
| `rah_query_edges` | Query existing edges |
|
||||
| `rah_update_edge` | Update edge metadata |
|
||||
| `rah_create_dimension` | Create a new dimension |
|
||||
| `rah_update_dimension` | Update dimension description |
|
||||
| `rah_delete_dimension` | Delete a dimension |
|
||||
| `rah_search_embeddings` | Semantic search across embeddings |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Configuration
|
||||
|
||||
Add to your `~/.claude/claude_desktop_config.json`:
|
||||
Add to your `~/.claude.json` or Claude Code settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js"]
|
||||
"args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or use the HTTP transport if you prefer:
|
||||
Replace `/path/to/ra-h_os` with the actual path to your RA-H Light installation.
|
||||
|
||||
**Note:** RA-H Light must be running (`npm run dev`) for the MCP server to work.
|
||||
|
||||
---
|
||||
|
||||
## HTTP Transport
|
||||
|
||||
For assistants that support HTTP transport:
|
||||
|
||||
**URL:** `http://127.0.0.1:44145/mcp`
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -50,52 +69,67 @@ Or use the HTTP transport if you prefer:
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** The RA-H desktop app must be running for the MCP server to work.
|
||||
|
||||
## Claude Desktop (STDIO)
|
||||
|
||||
Claude Desktop expects STDIO-based servers. Point it at:
|
||||
|
||||
```
|
||||
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js
|
||||
To start the HTTP server standalone:
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
```
|
||||
|
||||
This script speaks MCP over stdin/stdout. Keep the main RA-H app running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`.
|
||||
|
||||
## HTTP Transport
|
||||
|
||||
For assistants that support HTTP transport:
|
||||
|
||||
1. Copy the URL from **Settings → External Agents** (e.g., `http://127.0.0.1:44145/mcp`)
|
||||
2. Add as HTTP connector in your assistant
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
Once connected, you can:
|
||||
Once connected, you can ask your AI assistant:
|
||||
|
||||
```
|
||||
"Search RA-H for what I wrote about product strategy"
|
||||
"Add this conversation summary to RA-H as a new node"
|
||||
"Extract the transcript from this YouTube video and save to RA-H"
|
||||
"Find connections between my notes on AI agents"
|
||||
"Find all nodes with the 'research' dimension"
|
||||
"Create an edge between node 123 and node 456"
|
||||
"What are my most connected nodes?"
|
||||
```
|
||||
|
||||
## Guardrails
|
||||
---
|
||||
|
||||
- The MCP server only binds to `127.0.0.1` — for your agents only
|
||||
- Everything is persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`
|
||||
- Disable with `RAH_ENABLE_MCP=false` before launching (UI toggle coming)
|
||||
- Health check: `curl http://127.0.0.1:44145/status`
|
||||
## Security
|
||||
|
||||
## Development
|
||||
- The MCP server only binds to `127.0.0.1` — localhost only
|
||||
- No authentication required (local access only)
|
||||
- All data persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`
|
||||
|
||||
- **HTTP server:** `apps/mcp-server/server.js`
|
||||
- **STDIO bridge:** `apps/mcp-server/stdio-server.js`
|
||||
- **Sidecar launcher:** `apps/mac/scripts/sidecar-launcher.js`
|
||||
- **Status file:** `~/Library/Application Support/RA-H/config/mcp-status.json`
|
||||
---
|
||||
|
||||
## Health Check
|
||||
|
||||
To run standalone (for MCP Inspector):
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
curl http://127.0.0.1:44145/status
|
||||
```
|
||||
Requires the Next.js sidecar to be running.
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `apps/mcp-server/server.js` | HTTP MCP server |
|
||||
| `apps/mcp-server/stdio-server.js` | STDIO MCP server (for Claude Code) |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Connection refused"
|
||||
|
||||
1. Make sure RA-H Light is running: `npm run dev`
|
||||
2. Check the port isn't blocked: `lsof -i :44145`
|
||||
3. Verify the server started: check terminal output
|
||||
|
||||
### "Tools not showing"
|
||||
|
||||
1. Restart your AI assistant after configuring
|
||||
2. Verify the path in your config is correct
|
||||
3. Check `node apps/mcp-server/stdio-server.js` runs without errors
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
1. Make sure the stdio-server.js file is readable
|
||||
2. Check Node.js is in your PATH
|
||||
|
||||
Reference in New Issue
Block a user