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

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

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

3. Start the server

docker compose up -d --build

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

4. Verify health

curl http://localhost:3031/health

---

Client Integration

OpenCode

Add to ~/.config/opencode/opencode.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:

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

Antigravity AGY

Add to ~/.gemini/antigravity/mcp_config.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

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