# Zap Projects -- Agent Guide

This guide is for AI coding agents (Cursor, Copilot, or any other tool) that want to access the Zap Projects system -- a centralised hub of all Cursor chat history, plans, and project data.

## What data is available?

| Entity | Description | Count |
|--------|-------------|-------|
| **Projects** | Auto-discovered from chat data (e.g. philoenic, zap-mail, energystats) | 9+ |
| **Chats** | Full Cursor AI chat transcripts with metadata, LLM summaries, and deep analysis | 23+ |
| **Plans** | Cursor `.plan.md` files cross-referenced to chats and projects | 415+ |
| **Deep analysis** | Structured JSON: artifacts, decisions, unfinished work, chart work, questions raised | Per chat |

## Access methods

### 1. MCP Server (for Cursor agents)

The `zap-projects` MCP server is registered globally in `~/.cursor/mcp.json` on orcus.

**Tools:**

- `list_projects()` -- all projects with chat/plan counts
- `get_project(slug)` -- project detail with recent chats/plans
- `search_chats(query, project?, limit?)` -- full-text search across chats
- `get_chat(id, include_transcript?)` -- chat detail with summary, deep analysis, plans
- `list_plans(project?, query?)` -- list/search plan files
- `get_plan(path)` -- read a plan file's content
- `search_all(query)` -- unified search across everything

**For external agents (remote mode):**

Set environment variables in your MCP config:

```json
{
  "mcpServers": {
    "zap-projects": {
      "command": "python3",
      "args": ["/path/to/mcp/server.py"],
      "env": {
        "ZAP_PROJECTS_MODE": "remote",
        "ZAP_PROJECTS_API_URL": "https://orcus.getzap.co/projects/api",
        "ZAP_PROJECTS_API_KEY": "<your-key>"
      }
    }
  }
}
```

### 2. REST JSON API

Base URL: `https://zap.orcus.lan/projects/api/` (LAN) or `https://orcus.getzap.co/projects/api/` (external, when configured).

**Authentication:**
- LAN requests (192.168.x.x, 10.x.x, 127.0.0.1): no auth needed
- External requests: include `X-Api-Key: <key>` header
- Create keys: `php /var/www/zap/apps/zap-projects/scripts/manage-api-keys.php --create "agent-name"`

**Endpoints:**

#### GET /projects/api/projects.php
List all projects with chat/plan counts.

```bash
curl -s 'https://zap.orcus.lan/projects/api/projects.php' | jq '.projects[] | {slug, name, chat_count, plan_count}'
```

#### GET /projects/api/projects.php?slug=philoenic
Single project detail with recent chats and plans.

#### GET /projects/api/chats.php
List chats. Params: `?project=`, `?q=`, `?limit=`, `?offset=`.

```bash
curl -s 'https://zap.orcus.lan/projects/api/chats.php?q=postgres&limit=5' | jq '.chats[] | {id, first_query_short}'
```

#### GET /projects/api/chats.php?id=UUID
Single chat with metadata, summary, plans, deep analysis.

Add `&include=transcript` for full transcript text.

#### GET /projects/api/plans.php
List plans. Params: `?project=`, `?q=`, `?limit=`, `?offset=`.

#### GET /projects/api/plans.php?path=/home/jd/.cursor/plans/example.plan.md
Single plan with content and linked projects/chats.

#### GET /projects/api/search.php?q=migration
Unified search across chats, plans, and projects.

### 3. Direct database access (advanced)

PostgreSQL on localhost, database `zap`, tables prefixed with `cursor_`:

- `cursor_chats` -- main chat table with tsvector FTS
- `cursor_chat_plans` -- chat-to-plan links
- `cursor_chat_deep_analysis` -- structured LLM analysis (JSONB)
- `cursor_projects` -- project registry
- `cursor_chat_projects` -- chat-to-project many-to-many
- `cursor_plans` -- plan file index
- `cursor_plan_projects` -- plan-to-project many-to-many
- `cursor_api_keys` -- API key management

Credentials come from `ZAP_PROJECTS_ENV_FILE` or `apps/zap-projects/env/.env`.

## Example workflows

**Find what was done in previous sessions:**
```
search_chats("postgres migration") -> get_chat("<id>")
```

**Understand a project's history:**
```
get_project("philoenic") -> lists recent chats and plans
```

**Find related plans:**
```
list_plans(project="philoenic", query="deploy")
```

**Get deep analysis of a session:**
```
get_chat("<id>") -> includes deep_analysis with artifacts, decisions, unfinished work
```

## Registering as an external agent

1. Ask the user to create an API key:
   ```bash
   php /var/www/zap/apps/zap-projects/scripts/manage-api-keys.php --create "my-agent"
   ```
2. Use the key in your REST API calls (`X-Api-Key` header)
3. Or configure the MCP server in remote mode (see above)

## Web UI

- Project Hub: `https://zap.orcus.lan/projects/`
- Cursor Hub: `https://zap.orcus.lan/projects/cursor`
- Project Detail: `https://zap.orcus.lan/projects/<slug>`
- This guide: `https://zap.orcus.lan/projects/docs/agent-guide`