# 1. Clone and enter
git clone https://github.com/YOUR-ORG/gps.git && cd gps

# 2. Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Copy env and customize org mapping
cp .env.example .env

# 4. Place your data files in data/
#    - An XLSX org spreadsheet (any .xlsx file)
#    - CSV exports: issues, features, releases, etc.
#    (Example data ships in data/acme-* for testing)

# 5. Build the database
uv run scripts/build_db.py --force

# 6. Run tests
scripts/test.sh

# 7. Start the MCP server
uv run mcp_server.py              # stdio (for Claude Code / ACP)
uv run mcp_server.py --http       # HTTP on :8000 (for shared deployments)

graph TD
    subgraph Sources["Data Sources (refreshed periodically)"]
        XLSX["XLSX\nOrg Spreadsheet"]
        CSV["CSV\nIssues, Features,\nReleases"]
        GOV["Markdown / PDF\nGovernance Docs"]
    end

    ETL["build_db.py\n(ETL Pipeline)"]
    DB[("gps.db\nSQLite — read-only cache\nsub-ms queries")]

    subgraph Server["MCP Server (no auth required)"]
        MCP["mcp_server.py"]
        TOOLS["9 Tools\nlookup_person, search_issues,\nrelease_risk_summary, ..."]
        RES["2 Resources\ngps://schema\ngps://catalog"]
    end

    subgraph Clients["Clients"]
        ACP["ACP Sessions\n(stdio, every pod)"]
        CC["Claude Code\n(stdio, local)"]
        HTTP["Shared Deployment\n(HTTP :8000)"]
    end

    XLSX --> ETL
    CSV --> ETL
    GOV --> ETL
    ETL --> DB
    DB --> MCP
    MCP --- TOOLS
    MCP --- RES
    MCP -->|stdio| ACP
    MCP -->|stdio| CC
    MCP -->|streamable-http| HTTP

    style DB fill:#e8f4f8,stroke:#2196F3,stroke-width:2px
    style MCP fill:#fff3e0,stroke:#FF9800,stroke-width:2px
    style ETL fill:#f3e5f5,stroke:#9C27B0,stroke-width:2px

sequenceDiagram
    participant Agent as Agent / Human
    participant MCP as GPS MCP Server
    participant DB as gps.db (SQLite)

    Note over DB: Pre-built by ETL pipeline<br/>Opened read-only at startup

    Agent->>MCP: tool call: lookup_person(name="Dana")
    MCP->>DB: SELECT ... FROM person WHERE name LIKE '%Dana%'
    DB-->>MCP: rows (sub-ms)
    MCP-->>Agent: JSON {results: [...], count: 1}

    Agent->>MCP: tool call: search_issues(status="In Progress", component="api")
    MCP->>DB: SELECT ... FROM jira_issue WHERE status LIKE ... AND EXISTS(...)
    DB-->>MCP: rows (sub-ms)
    MCP-->>Agent: JSON {issues: [...], count: 12}

    Agent->>MCP: tool call: release_risk_summary()
    MCP->>DB: SELECT ... FROM release_milestone
    MCP->>DB: SELECT ... FROM feature_release
    MCP->>DB: SELECT ... FROM feature WHERE feature_id IN (...)
    DB-->>MCP: rows
    MCP-->>Agent: JSON {releases: [...], assessed_on: "2026-03-20"}

    Agent->>MCP: resource: gps://schema
    MCP->>DB: SELECT sql FROM sqlite_master
    DB-->>MCP: DDL statements
    MCP-->>Agent: Full schema with row counts

    Note over Agent,DB: All queries are read-only<br/>No writes, no auth, no rate limits

{
  "mcpServers": {
    "gps": {
      "command": "uv",
      "args": ["run", "--script", "/app/gps/mcp_server.py"]
    }
  }
}

mcp_server.py          MCP server (stdio default, --http for HTTP)
scripts/
  build_db.py          ETL pipeline — materializes gps.db from source files
  test.sh              Test suite (lint, build, integrity, schema diff)
data/
  acme-*               Example data files (tracked)
  *.csv, *.xlsx, *.db  User data files (gitignored)
deploy/
  deploy.sh            Build, apply, status, logs automation
  k8s/                 Kubernetes/OpenShift manifests (kustomize)
docs/
  adr/                 Architecture Decision Records
  DEPLOYMENT.md        Deployment guide (local, container, k8s, ACP)
  CUSTOMIZATION.md     Customization guide (env vars, adding sources)
  SCHEMA.md            Database schema reference (ER diagram, tables, views)
governance/            Policy documents (auto-loaded into DB)
Containerfile          Container image build
.env.example           Configuration template
.mcp.json              Claude Code MCP server config