“BeeRad”andClaude Opus 4.5
0e6bf12ad3
- 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>
93 lines
3.1 KiB
Markdown
93 lines
3.1 KiB
Markdown
# RA-H MCP Server Setup
|
|
|
|
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. 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."
|
|
|
|
## 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. |
|
|
|
|
## Claude Desktop (STDIO Connector)
|
|
|
|
Claude Desktop expects STDIO-based servers. Point it at:
|
|
|
|
```
|
|
node /path/to/ra-h_os/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`.
|
|
|
|
## Configuration
|
|
|
|
| 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
|