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:

{
  "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/scripts/manage-api-keys.php --create "agent-name"

Endpoints:

GET /projects/api/projects.php

List all projects with chat/plan counts.

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=.

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 in /var/www/zap/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:

   php /var/www/zap/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