# ContextVault

Shared context storage for AI agents. Any MCP-compatible model (Claude, ChatGPT, Gemini) can store, read, and search context entries through the MCP server. A web UI lets you browse and manage everything.

## Architecture

```
  Claude / ChatGPT / Gemini
        │ (MCP stdio)
        ▼
  ┌──────────────┐
  │  MCP Server   │──────┐
  └──────────────┘      │
                         ▼
  ┌──────────────┐   ┌──────────┐
  │   Web UI      │──▶│ Express  │──▶ PostgreSQL
  └──────────────┘   └──────────┘
```

- **Express API** (`src/index.ts`) — REST API + serves the React UI
- **MCP Server** (`src/mcp.ts`) — stdio MCP server for AI agents
- **PostgreSQL** — persistent storage with JSONB tags and GIN index

## Quick Start (Docker)

```bash
docker compose up
```

Open http://localhost:3000 for the UI. Postgres runs on port 5432.

## Local Development

Prerequisites: Node.js 20+, PostgreSQL running locally.

```bash
# Create the database
createdb context_vault

# Install and build
npm install
cd client && npm install && npm run build && cd ..
npm run build:server

# Start the web server
npm start

# Or run the MCP server for AI agents
npm run mcp
```

Set `DATABASE_URL` env var if your Postgres isn't at the default `postgresql://postgres:postgres@localhost:5432/context_vault`.

## MCP Configuration

### Claude Code / Claude Desktop

```json
{
  "mcpServers": {
    "context-vault": {
      "command": "node",
      "args": ["/absolute/path/to/context-vault/dist/mcp.js"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/context_vault"
      }
    }
  }
}
```

## Deploy to GCP (Cloud Run)

```bash
# Build and push
gcloud builds submit --tag gcr.io/PROJECT_ID/context-vault

# Deploy
gcloud run deploy context-vault \
  --image gcr.io/PROJECT_ID/context-vault \
  --set-env-vars DATABASE_URL=postgresql://... \
  --port 8080 \
  --allow-unauthenticated
```

## API

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/stats` | Dashboard stats |
| GET | `/api/namespaces` | List namespaces |
| GET | `/api/entries` | List entries (query: `namespace`, `source`, `tag`) |
| GET | `/api/entries/search?q=` | Search entries |
| GET | `/api/entries/:ns/:key` | Get one entry |
| POST | `/api/entries` | Create/upsert entry |
| PUT | `/api/entries/:ns/:key` | Update entry |
| DELETE | `/api/entries/:ns/:key` | Delete entry |

## MCP Tools

| Tool | Description |
|------|-------------|
| `store` | Store or upsert a context entry |
| `get` | Retrieve a specific entry |
| `update` | Partially update an entry |
| `delete` | Delete an entry |
| `list` | List entries with filters |
| `search` | Search by keyword |
| `namespaces` | List all namespaces |