“BeeRad”
733d1c3407
Local-first knowledge management system with BYO API keys. Features: - 3-panel UI (Nodes | Focus | Helpers) - SQLite + sqlite-vec for vector search - Agent system (Easy/Hard mode orchestrators) - Content extraction (YouTube, PDF, web) - Integrate workflow for connection discovery - Dimension system with auto-assignment Tech stack: - Next.js 15 + TypeScript + Tailwind CSS - Anthropic (Claude) + OpenAI (GPT) via Vercel AI SDK Setup: npm install && npm rebuild better-sqlite3 scripts/dev/bootstrap-local.sh npm run dev MIT License
46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
# RA-H MCP Connector Setup
|
||
|
||
The desktop app now ships with a local Model Context Protocol (MCP) server so any MCP‑compatible assistant (Claude, ChatGPT, Gemini, Codex, etc.) can read/write your RA-H graph. Everything runs on `127.0.0.1` and never leaves your Mac.
|
||
|
||
## Quick Start
|
||
|
||
1. Launch the RA-H desktop app (it boots the Next.js sidecar + MCP bridge automatically).
|
||
2. Open **Settings → External Agents** inside RA-H and copy the connector URL (example: `http://127.0.0.1:44145/mcp`).
|
||
3. In Claude, ChatGPT, or any other assistant:
|
||
- open the MCP/connectors panel,
|
||
- choose **Add connector → HTTP**,
|
||
- paste the copied URL and name it “RA-H”.
|
||
4. Talk naturally. Examples:
|
||
- “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.”
|
||
|
||
The assistant calls two tools behind the scenes:
|
||
|
||
| Tool | Description |
|
||
| --- | --- |
|
||
| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers the auto-embed queue. |
|
||
| `rah_search_nodes` | Searches existing nodes (title/content/dimensions) before deciding whether to create something new. |
|
||
|
||
## Guardrails
|
||
|
||
- The MCP server only binds to `127.0.0.1` and is meant for **your** agents. Do not expose it beyond your machine.
|
||
- Anything the assistant writes is immediately persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`. Review the RA-H activity panel if something looks off.
|
||
- Disable the connector by setting `RAH_ENABLE_MCP=false` before launching the app (UI toggle coming soon).
|
||
- The `/status` endpoint returns health info if you need diagnostics: `curl http://127.0.0.1:44145/status`.
|
||
|
||
### Claude Desktop (STDIO Connector)
|
||
|
||
Claude’s configuration window expects STDIO-based servers. To let Claude start a connector directly, point it at:
|
||
|
||
```
|
||
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js
|
||
```
|
||
|
||
This script speaks MCP over stdin/stdout (no HTTP listener), so Claude can manage it through `claude_desktop_config.json` or the “Add MCP Server” CLI flow. Keep the main RA-H app running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`.
|
||
|
||
## Development Notes
|
||
|
||
- Implementation lives in `apps/mcp-server/server.js` (HTTP transport + tool definitions). It proxies through the existing `/api/nodes/*` routes, so validation + auto-embed behavior stays consistent.
|
||
- The Mac sidecar (`apps/mac/scripts/sidecar-launcher.js`) bootstraps the MCP server and keeps `~/Library/Application Support/RA-H/config/mcp-status.json` updated for the Settings panel/API.
|
||
- To run the server standalone (for MCP Inspector, etc.): `node apps/mcp-server/server.js` (requires the Next.js sidecar to be running so the API endpoints respond).
|