docs: sync documentation from private repo
- Rewrite 3_context-and-memory.md (auto-context system, remove legacy memory) - Create 7_voice.md (voice interface documentation) - Update 0_overview.md, 1_architecture.md, 4_tools-and-workflows.md, 6_ui.md, 8_mcp.md - Add simple human-readable intros to all docs - Update README.md with voice doc reference Synced from ra-h commit 4a3d7e0
This commit is contained in:
“BeeRad”
+72
-63
@@ -1,92 +1,101 @@
|
||||
# RA-H MCP Server Setup
|
||||
# RA-H MCP Server
|
||||
|
||||
RA-H includes a local Model Context Protocol (MCP) server that lets any MCP-compatible assistant (Claude, ChatGPT, Gemini, etc.) read/write your knowledge graph. Everything runs on `127.0.0.1` and never leaves your machine.
|
||||
> How to connect Claude Code and other AI assistants to your knowledge base.
|
||||
|
||||
## Overview
|
||||
**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.
|
||||
|
||||
The MCP server is a standalone Node.js process that bridges external AI assistants to your local RA-H database. In the open source version, you run this server manually alongside the Next.js dev server.
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Start the Next.js Server
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
This starts the web app at `http://localhost:3000`.
|
||||
|
||||
### 2. Start the MCP Server
|
||||
|
||||
In a separate terminal:
|
||||
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
```
|
||||
|
||||
The MCP server will start on port `44145` by default.
|
||||
|
||||
### 3. Connect Your Assistant
|
||||
|
||||
1. Open **Settings → External Agents** in RA-H and copy the connector URL: `http://127.0.0.1:44145/mcp`
|
||||
2. In Claude, ChatGPT, or your assistant:
|
||||
- Open the MCP/connectors panel
|
||||
- Choose **Add connector → HTTP**
|
||||
- Paste the URL and name it "RA-H"
|
||||
|
||||
### 4. Use It
|
||||
|
||||
Talk naturally:
|
||||
- "Summarize this chat and add it to RA-H under Strategy + Q1 Execution."
|
||||
- "Search RA-H for what I already wrote about Apollo launch delays."
|
||||
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"
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers auto-embedding. |
|
||||
| `rah_search_nodes` | Searches existing nodes (title/content/dimensions) before deciding whether to create something new. |
|
||||
| `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 |
|
||||
|
||||
## Claude Desktop (STDIO Connector)
|
||||
## Claude Code Configuration
|
||||
|
||||
Add to your `~/.claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or use the HTTP transport if you prefer:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"url": "http://127.0.0.1:44145/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**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 /path/to/ra-h_os/apps/mcp-server/stdio-server.js
|
||||
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js
|
||||
```
|
||||
|
||||
This speaks MCP over stdin/stdout. Add it to `claude_desktop_config.json` or use the "Add MCP Server" CLI flow. Keep the Next.js server running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`.
|
||||
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`.
|
||||
|
||||
## Configuration
|
||||
## HTTP Transport
|
||||
|
||||
| Environment Variable | Default | Description |
|
||||
|---------------------|---------|-------------|
|
||||
| `MCP_PORT` | `44145` | Port for the HTTP MCP server |
|
||||
| `RAH_ENABLE_MCP` | `true` | Set to `false` to disable MCP |
|
||||
For assistants that support HTTP transport:
|
||||
|
||||
## Security Notes
|
||||
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
|
||||
|
||||
- The MCP server only binds to `127.0.0.1` — it's meant for **your** local agents only
|
||||
- Do not expose it beyond your machine
|
||||
- Anything the assistant writes is immediately persisted to your local SQLite database
|
||||
- Review the RA-H activity panel if something looks unexpected
|
||||
## Example Usage
|
||||
|
||||
## Troubleshooting
|
||||
Once connected, you can:
|
||||
|
||||
### Server won't start
|
||||
- Ensure the Next.js dev server is running first
|
||||
- Check if port 44145 is already in use: `lsof -i :44145`
|
||||
```
|
||||
"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"
|
||||
```
|
||||
|
||||
### Connection fails in assistant
|
||||
- Verify both servers are running (Next.js on 3000, MCP on 44145)
|
||||
- Try the health endpoint: `curl http://127.0.0.1:44145/status`
|
||||
## Guardrails
|
||||
|
||||
### Tools not working
|
||||
- The MCP server proxies through `/api/nodes/*` routes — ensure the Next.js server responds
|
||||
- Check the terminal running the MCP server for error logs
|
||||
- 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`
|
||||
|
||||
## Development
|
||||
|
||||
- Implementation: `apps/mcp-server/server.js` (HTTP transport + tool definitions)
|
||||
- STDIO variant: `apps/mcp-server/stdio-server.js`
|
||||
- The server proxies through existing `/api/nodes/*` routes, so validation and auto-embed behavior stays consistent
|
||||
- **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`
|
||||
|
||||
To run standalone (for MCP Inspector):
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
```
|
||||
Requires the Next.js sidecar to be running.
|
||||
|
||||
Reference in New Issue
Block a user