136 lines
3.0 KiB
Markdown
136 lines
3.0 KiB
Markdown
# MCP Server
|
|
|
|
> How to 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.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
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"
|
|
|
|
---
|
|
|
|
## Available Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `rah_add_node` | Create a new node (title/content/dimensions) |
|
|
| `rah_search_nodes` | Search existing nodes |
|
|
| `rah_update_node` | Update an existing node |
|
|
| `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_create_dimension` | Create a new dimension |
|
|
| `rah_update_dimension` | Update dimension description |
|
|
| `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
|
|
```
|
|
|
|
---
|
|
|
|
## Example Usage
|
|
|
|
Once connected, you can ask your AI assistant:
|
|
|
|
```
|
|
"Search RA-H for what I wrote about product strategy"
|
|
"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?"
|
|
```
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
- The MCP server only binds to `127.0.0.1` — localhost only
|
|
- No authentication required (local access only)
|
|
- All data persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`
|
|
|
|
---
|
|
|
|
## 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"
|
|
|
|
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
|