feat: standalone MCP server (ra-h-mcp-server)
- Added apps/mcp-server-standalone/ with direct SQLite access - Works without RA-OS app running - Install via: npx ra-h-mcp-server - Updated docs/8_mcp.md with setup instructions 🤖 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
5c480b01d6
commit
bcea76800b
+91
-84
@@ -1,16 +1,75 @@
|
||||
# MCP Server
|
||||
|
||||
> How to connect Claude Code and other AI assistants to your knowledge base.
|
||||
> Connect Claude Code and other AI assistants to your knowledge base.
|
||||
|
||||
**How it works:** RA-OS 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.
|
||||
**How it works:** RA-OS includes an 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.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
## Quick Start (Recommended)
|
||||
|
||||
The easiest way is using the npm package:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "npx",
|
||||
"args": ["ra-h-mcp-server"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Add this to your `~/.claude.json` (Claude Code) or Claude Desktop settings.
|
||||
|
||||
**Requirements:**
|
||||
- Node.js 18+ installed
|
||||
- RA-OS run at least once (to create the database)
|
||||
|
||||
**That's it.** No need to keep RA-OS running.
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Local Development
|
||||
|
||||
If you're developing RA-OS and want to use the local server:
|
||||
|
||||
### Standalone (No Web App Required)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/ra-h_os/apps/mcp-server-standalone/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
First install dependencies:
|
||||
```bash
|
||||
cd apps/mcp-server-standalone
|
||||
npm install
|
||||
```
|
||||
|
||||
### HTTP Transport (Web App Required)
|
||||
|
||||
If you want real-time UI updates when nodes are created:
|
||||
|
||||
1. Start RA-OS: `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"
|
||||
2. Configure:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"url": "http://127.0.0.1:44145/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -24,55 +83,10 @@
|
||||
| `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_list_dimensions` | List all dimensions |
|
||||
| `rah_create_dimension` | Create a new dimension |
|
||||
| `rah_update_dimension` | Update dimension description |
|
||||
| `rah_update_dimension` | Update/rename dimension |
|
||||
| `rah_delete_dimension` | Delete a dimension |
|
||||
| `rah_search_embeddings` | Semantic search across embeddings |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Configuration
|
||||
|
||||
Add to your `~/.claude.json` or Claude Code settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `/path/to/ra-h_os` with the actual path to your RA-OS installation.
|
||||
|
||||
**Note:** RA-OS 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
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"url": "http://127.0.0.1:44145/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To start the HTTP server standalone:
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -85,11 +99,20 @@ Once connected, you can ask your AI assistant:
|
||||
"Add this conversation summary to RA-H as a new node"
|
||||
"Find all nodes with the 'research' dimension"
|
||||
"Create an edge between node 123 and node 456"
|
||||
"What are my most connected nodes?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `apps/mcp-server-standalone/` | **Standalone server (direct SQLite, recommended)** |
|
||||
| `apps/mcp-server/server.js` | HTTP MCP server |
|
||||
| `apps/mcp-server/stdio-server.js` | STDIO bridge to HTTP server |
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- The MCP server only binds to `127.0.0.1` — localhost only
|
||||
@@ -98,38 +121,22 @@ Once connected, you can ask your AI assistant:
|
||||
|
||||
---
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:44145/status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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"
|
||||
### "Database not found"
|
||||
|
||||
Run RA-OS at least once to create the database:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### "Tools not showing" (npm package)
|
||||
|
||||
1. Make sure Node.js 18+ is installed: `node --version`
|
||||
2. Try running manually: `npx ra-h-mcp-server`
|
||||
3. Restart Claude Code
|
||||
|
||||
### "Connection refused" (HTTP method)
|
||||
|
||||
1. Make sure RA-OS 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
|
||||
2. Check the port: `lsof -i :44145`
|
||||
|
||||
Reference in New Issue
Block a user