# Personal MCP Context Registry

> A Model Context Protocol (MCP) Server to store and serve your personal context — identity, devices, servers, and projects — as structured Markdown files with a knowledge graph, accessible on-demand by AI Agents (Claude Desktop, Cursor, OpenCode, Antigravity AGY).

---

## Why?

Instead of pasting all your personal info into every AI chat session (wasting tokens and context window), this server lets any MCP-compatible AI agent query only what it needs, when it needs it. Think of it as a personal knowledge base with graph traversal, fuzzy search, and an audit log.

---

## Features

- 🗂 **Graph-backed Storage** — Markdown files (`personal.md`, `devices.md`, `servers.md`, etc.) linked via semantic relations in `index.json`
- 🔍 **Fuzzy Search** — Fast in-memory search across all context files via `Fuse.js`
- 🔗 **Graph Traversal** — Query related nodes at configurable depth
- 🛡 **Safe Writes** — Every write auto-backs up the existing file before overwriting; rollback on validation failure
- 📋 **Audit Log** — JSON-lines access log with auto-purge of entries older than 30 days
- ✅ **Integrity Validator** — Detects broken links, orphan nodes, and missing files
- 🐳 **Docker-ready** — Bind-mount your data from `~/context-data` on host, bound exclusively to `127.0.0.1:3031`
- 🗂 **Multi-namespace** — Separate namespaces for `personal`, `work`, `project-x` contexts

---

## Available MCP Tools

| Tool | Description |
|---|---|
| `get_context_nodes` | List all nodes and links in the graph |
| `read_context_file` | Read full markdown content of a node |
| `search_context` | Fuzzy search across all context files |
| `get_related_nodes` | Traverse graph relations from a node |
| `create_context_node` | Create a new node with markdown content |
| `update_context_file` | Update existing node content (overwrite / append) |
| `delete_context_node` | Soft-delete node (moves file to `.backup/`) |
| `add_context_relation` | Link two nodes with a named relation |
| `remove_context_relation` | Remove a link between two nodes |
| `validate_context` | Run integrity check on graph & files |
| `backup_context` | Full backup of namespace to `.backup/` |
| `get_access_log` | Read the audit access log |

---

## Tech Stack

| Layer | Technology |
|---|---|
| Runtime | Node.js 20 + TypeScript |
| Transport | Streamable HTTP (`/mcp` endpoint) |
| Storage | Markdown files + JSON graph |
| Search | `Fuse.js` (in-memory fuzzy) |
| Auth | None (localhost only for MVP) |
| Deployment | Docker Compose |

---

## Quick Start

### Prerequisites
- Docker & Docker Compose installed

### 1. Clone & Create context data directory

```bash
git clone https://github.com/your-username/personal-mcp-context.git
cd personal-mcp-context
mkdir -p ~/context-data/personal
```

### 2. Create initial `index.json`

```bash
cat > ~/context-data/personal/index.json << 'EOF'
{
  "version": "2.0",
  "nodes": [],
  "links": [],
  "metadata": {}
}
EOF
```

### 3. Start the server

```bash
docker compose up -d --build
```

The server will be available at `http://127.0.0.1:3031` (localhost only).

### 4. Verify health

```bash
curl http://localhost:3031/health
```

---

## Client Integration

### OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
"mcp": {
  "personal-context": {
    "type": "remote",
    "url": "http://localhost:3031/mcp",
    "enabled": true
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "personal-context": {
      "command": "curl",
      "args": ["-s", "http://localhost:3031/mcp"]
    }
  }
}
```

### Antigravity AGY

Add to `~/.gemini/antigravity/mcp_config.json`:

```json
{
  "mcpServers": {
    "personal-context": {
      "serverUrl": "http://localhost:3031/mcp"
    }
  }
}
```

---

## Data Structure

Your context data lives in `~/context-data/` on your host machine (bind-mounted into the container). Files in this directory are **not included in this repo** and should **never be committed** (already in `.gitignore`).

```
~/context-data/
└── personal/
    ├── index.json       # Knowledge graph (nodes + links)
    ├── personal.md      # Your identity/profile
    ├── devices.md       # Hardware info
    ├── servers.md       # Server/infrastructure info
    └── .backup/         # Auto-generated backups
```

---

## Local Development

```bash
npm install
npm run dev       # Hot-reload via tsx
npm run build     # Compile TypeScript
npm run test      # Run Vitest tests
```

---

## Security Notes

> ⚠️ **This server has NO authentication** in its current MVP state. It is designed to run **locally only** (`127.0.0.1:3031`). Do NOT expose this port to a public network without adding Bearer token auth first.

- `~/context-data` is in `.gitignore` — never commit it
- Port is bound to `127.0.0.1` only in `docker-compose.yml`
- Before deploying publicly (e.g., CapRover): add Bearer token auth + HTTPS

---

## License

MIT