fix: OS release prep - bootstrap script, deps, docs
- Fix bootstrap script (.env.example.local → .env.example) - Fix @langchain/core version conflict (^1.0.1 → ^0.3.0) - Add settings:open event listener for LocalKeyGate button - Pin Next.js to 15.1.3 (was "latest") - Default runtime to 'local' mode - Remove desktop app references from UI text - Rewrite MCP docs for web-only context - Add SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md - Add docs/README.md, docs/TROUBLESHOOTING.md - Update README with platform support table 🤖 Generated with [Claude Code](https://claude.com/claude-code) 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
ffbd47563e
commit
0e6bf12ad3
+76
-29
@@ -1,45 +1,92 @@
|
||||
# RA-H MCP Connector Setup
|
||||
# RA-H MCP Server 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.
|
||||
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.
|
||||
|
||||
## Overview
|
||||
|
||||
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. 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.”
|
||||
### 1. Start the Next.js Server
|
||||
|
||||
The assistant calls two tools behind the scenes:
|
||||
```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."
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
| --- | --- |
|
||||
| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers the auto-embed queue. |
|
||||
|------|-------------|
|
||||
| `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. |
|
||||
|
||||
## Guardrails
|
||||
## Claude Desktop (STDIO Connector)
|
||||
|
||||
- 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:
|
||||
Claude Desktop expects STDIO-based servers. Point it at:
|
||||
|
||||
```
|
||||
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js
|
||||
node /path/to/ra-h_os/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`.
|
||||
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`.
|
||||
|
||||
## Development Notes
|
||||
## Configuration
|
||||
|
||||
- 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).
|
||||
| Environment Variable | Default | Description |
|
||||
|---------------------|---------|-------------|
|
||||
| `MCP_PORT` | `44145` | Port for the HTTP MCP server |
|
||||
| `RAH_ENABLE_MCP` | `true` | Set to `false` to disable MCP |
|
||||
|
||||
## Security Notes
|
||||
|
||||
- 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
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server won't start
|
||||
- Ensure the Next.js dev server is running first
|
||||
- Check if port 44145 is already in use: `lsof -i :44145`
|
||||
|
||||
### 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`
|
||||
|
||||
### 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
|
||||
|
||||
## 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
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# Documentation
|
||||
|
||||
## Quick Start
|
||||
See the main [README.md](../README.md) for setup instructions.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [0_overview.md](0_overview.md) | System overview and philosophy |
|
||||
| [1_architecture.md](1_architecture.md) | Technical architecture |
|
||||
| [2_schema.md](2_schema.md) | Database schema and sqlite-vec setup |
|
||||
| [3_context-and-memory.md](3_context-and-memory.md) | Context system |
|
||||
| [4_tools-and-workflows.md](4_tools-and-workflows.md) | Agent tools and workflows |
|
||||
| [5_logging-and-evals.md](5_logging-and-evals.md) | Logging infrastructure |
|
||||
| [6_ui.md](6_ui.md) | UI components and patterns |
|
||||
| [8_mcp.md](8_mcp.md) | MCP server setup |
|
||||
| [9_open-source.md](9_open-source.md) | Open source specific notes |
|
||||
|
||||
## Troubleshooting
|
||||
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues.
|
||||
@@ -0,0 +1,100 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### `npm install` fails
|
||||
|
||||
**Symptom:** Error during native module compilation
|
||||
|
||||
**Fix:** Install build tools:
|
||||
```bash
|
||||
# macOS
|
||||
xcode-select --install
|
||||
|
||||
# Linux
|
||||
sudo apt install build-essential python3
|
||||
|
||||
# Windows
|
||||
npm install -g windows-build-tools
|
||||
```
|
||||
|
||||
### `npm rebuild better-sqlite3` fails
|
||||
|
||||
**Symptom:** Native module rebuild errors
|
||||
|
||||
**Fix:**
|
||||
1. Ensure Node.js 18+ is installed
|
||||
2. Delete `node_modules` and reinstall:
|
||||
```bash
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
npm rebuild better-sqlite3
|
||||
```
|
||||
|
||||
## Runtime Issues
|
||||
|
||||
### App won't start
|
||||
|
||||
**Symptom:** Error on `npm run dev`
|
||||
|
||||
**Fixes:**
|
||||
1. Run the bootstrap script first: `scripts/dev/bootstrap-local.sh`
|
||||
2. Check `.env.local` exists (copy from `.env.example` if missing)
|
||||
3. Ensure database directory exists: `~/Library/Application Support/RA-H/db/`
|
||||
|
||||
### Vector search returns no results
|
||||
|
||||
**Symptom:** Semantic search doesn't find matches
|
||||
|
||||
**Fixes:**
|
||||
1. Ensure `sqlite-vec` extension is loading (check console for errors)
|
||||
2. Verify `SQLITE_VEC_EXTENSION_PATH` in `.env.local` points to `vendor/sqlite-extensions/vec0.dylib`
|
||||
3. Note: sqlite-vec only works on macOS currently. Linux/Windows users need to compile it manually.
|
||||
|
||||
### API key validation fails
|
||||
|
||||
**Symptom:** "Invalid key" error in Settings
|
||||
|
||||
**Fixes:**
|
||||
1. Verify key format:
|
||||
- OpenAI: starts with `sk-`
|
||||
- Anthropic: starts with `sk-ant-`
|
||||
2. Check key has correct permissions/credits
|
||||
3. Try regenerating the key in provider dashboard
|
||||
|
||||
### Chat returns errors
|
||||
|
||||
**Symptom:** Error messages when chatting
|
||||
|
||||
**Fixes:**
|
||||
1. Check API keys are valid (Settings → API Keys)
|
||||
2. Verify internet connection
|
||||
3. Check browser console for specific error messages
|
||||
|
||||
## Database Issues
|
||||
|
||||
### Database locked
|
||||
|
||||
**Symptom:** "SQLITE_BUSY" errors
|
||||
|
||||
**Fix:** Only run one instance of RA-H at a time. Close any other terminals running the app.
|
||||
|
||||
### Missing tables
|
||||
|
||||
**Symptom:** "no such table" errors
|
||||
|
||||
**Fix:** Re-run the schema script:
|
||||
```bash
|
||||
scripts/database/sqlite-ensure-app-schema.sh ~/Library/Application\ Support/RA-H/db/rah.sqlite
|
||||
```
|
||||
|
||||
## Platform-Specific
|
||||
|
||||
### Linux/Windows
|
||||
|
||||
The bundled `vec0.dylib` and `yt-dlp` binaries are macOS-only. For other platforms:
|
||||
|
||||
1. **sqlite-vec**: Build from source at https://github.com/asg017/sqlite-vec
|
||||
2. **yt-dlp**: Download from https://github.com/yt-dlp/yt-dlp/releases
|
||||
|
||||
See the main README for detailed instructions.
|
||||
Reference in New Issue
Block a user