{"id":49360403,"url":"https://github.com/ambient-code/gps","last_synced_at":"2026-04-27T16:02:15.487Z","repository":{"id":346480805,"uuid":"1187437311","full_name":"ambient-code/gps","owner":"ambient-code","description":"GPS — read-only MCP caching tier for org and engineering data","archived":false,"fork":false,"pushed_at":"2026-03-24T03:19:44.000Z","size":231,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T03:41:25.179Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ambient-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"governance/example-policy.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T18:14:07.000Z","updated_at":"2026-03-24T03:19:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ambient-code/gps","commit_stats":null,"previous_names":["ambient-code/gps"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ambient-code/gps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fgps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fgps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fgps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fgps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ambient-code","download_url":"https://codeload.github.com/ambient-code/gps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fgps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32343571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-27T16:02:10.357Z","updated_at":"2026-04-27T16:02:15.480Z","avatar_url":"https://github.com/ambient-code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GPS - Global Positioning System MCP Server\n\nA read-only caching tier that gives agents and humans sub-millisecond access to org and engineering data. GPS materializes people, teams, issues, features, release schedules, component mappings, and governance documents into a SQLite database and serves them over [MCP](https://modelcontextprotocol.io) — optimized for high-frequency agent queries with zero upstream latency.\n\n**Why GPS exists:** Agents need fast, reliable access to org and engineering data. Querying live APIs (Jira, Confluence, HR systems) on every turn is slow, rate-limited, and fragile. GPS pre-materializes everything into a single SQLite file, opens it read-only, and serves structured results in microseconds. No auth, no rate limits, no network dependencies at query time.\n\n## 5-Minute Quickstart\n\n```bash\n# 1. Clone and enter\ngit clone https://github.com/YOUR-ORG/gps.git \u0026\u0026 cd gps\n\n# 2. Install uv (if needed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 3. Copy env and customize org mapping\ncp .env.example .env\n\n# 4. Place your data files in data/\n#    - An XLSX org spreadsheet (any .xlsx file)\n#    - CSV exports: issues, features, releases, etc.\n#    (Example data ships in data/acme-* for testing)\n\n# 5. Build the database\nuv run scripts/build_db.py --force\n\n# 6. Run tests\nscripts/test.sh\n\n# 7. Start the MCP server\nuv run mcp_server.py              # stdio (for Claude Code / ACP)\nuv run mcp_server.py --http       # HTTP on :8000 (for shared deployments)\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph Sources[\"Data Sources (refreshed periodically)\"]\n        XLSX[\"XLSX\\nOrg Spreadsheet\"]\n        CSV[\"CSV\\nIssues, Features,\\nReleases\"]\n        GOV[\"Markdown / PDF\\nGovernance Docs\"]\n    end\n\n    ETL[\"build_db.py\\n(ETL Pipeline)\"]\n    DB[(\"gps.db\\nSQLite — read-only cache\\nsub-ms queries\")]\n\n    subgraph Server[\"MCP Server (no auth required)\"]\n        MCP[\"mcp_server.py\"]\n        TOOLS[\"9 Tools\\nlookup_person, search_issues,\\nrelease_risk_summary, ...\"]\n        RES[\"2 Resources\\ngps://schema\\ngps://catalog\"]\n    end\n\n    subgraph Clients[\"Clients\"]\n        ACP[\"ACP Sessions\\n(stdio, every pod)\"]\n        CC[\"Claude Code\\n(stdio, local)\"]\n        HTTP[\"Shared Deployment\\n(HTTP :8000)\"]\n    end\n\n    XLSX --\u003e ETL\n    CSV --\u003e ETL\n    GOV --\u003e ETL\n    ETL --\u003e DB\n    DB --\u003e MCP\n    MCP --- TOOLS\n    MCP --- RES\n    MCP --\u003e|stdio| ACP\n    MCP --\u003e|stdio| CC\n    MCP --\u003e|streamable-http| HTTP\n\n    style DB fill:#e8f4f8,stroke:#2196F3,stroke-width:2px\n    style MCP fill:#fff3e0,stroke:#FF9800,stroke-width:2px\n    style ETL fill:#f3e5f5,stroke:#9C27B0,stroke-width:2px\n```\n\n### How it works\n\n1. **ETL pipeline** (`scripts/build_db.py`) loads all sources into a single SQLite database — runs periodically, not per-query\n2. **MCP server** (`mcp_server.py`) opens the database read-only with mmap, 64MB cache, and memory-backed temp store — tuned for agent query patterns\n3. **No auth required** — the database contains read-only organizational data; agents connect directly via stdio or HTTP\n4. The LLM never touches upstream data sources directly — clean security boundary\n\n### Client-Server Interaction\n\n```mermaid\nsequenceDiagram\n    participant Agent as Agent / Human\n    participant MCP as GPS MCP Server\n    participant DB as gps.db (SQLite)\n\n    Note over DB: Pre-built by ETL pipeline\u003cbr/\u003eOpened read-only at startup\n\n    Agent-\u003e\u003eMCP: tool call: lookup_person(name=\"Dana\")\n    MCP-\u003e\u003eDB: SELECT ... FROM person WHERE name LIKE '%Dana%'\n    DB--\u003e\u003eMCP: rows (sub-ms)\n    MCP--\u003e\u003eAgent: JSON {results: [...], count: 1}\n\n    Agent-\u003e\u003eMCP: tool call: search_issues(status=\"In Progress\", component=\"api\")\n    MCP-\u003e\u003eDB: SELECT ... FROM jira_issue WHERE status LIKE ... AND EXISTS(...)\n    DB--\u003e\u003eMCP: rows (sub-ms)\n    MCP--\u003e\u003eAgent: JSON {issues: [...], count: 12}\n\n    Agent-\u003e\u003eMCP: tool call: release_risk_summary()\n    MCP-\u003e\u003eDB: SELECT ... FROM release_milestone\n    MCP-\u003e\u003eDB: SELECT ... FROM feature_release\n    MCP-\u003e\u003eDB: SELECT ... FROM feature WHERE feature_id IN (...)\n    DB--\u003e\u003eMCP: rows\n    MCP--\u003e\u003eAgent: JSON {releases: [...], assessed_on: \"2026-03-20\"}\n\n    Agent-\u003e\u003eMCP: resource: gps://schema\n    MCP-\u003e\u003eDB: SELECT sql FROM sqlite_master\n    DB--\u003e\u003eMCP: DDL statements\n    MCP--\u003e\u003eAgent: Full schema with row counts\n\n    Note over Agent,DB: All queries are read-only\u003cbr/\u003eNo writes, no auth, no rate limits\n```\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `lookup_person` | Find people by name, email, or user ID (partial match) |\n| `list_team_members` | List all members of a scrum team with roles and components |\n| `search_issues` | Search issues by status, priority, assignee, component, label, or keyword |\n| `get_feature_status` | Get feature details: progress, RICE score, releases, components, teams |\n| `release_risk_summary` | Assess release risk — flags features under 80% complete near milestones |\n| `list_documents` | List governance documents with table of contents |\n| `get_document` | Retrieve full governance document content by ID |\n| `get_document_section` | Retrieve a specific section by fuzzy heading match |\n| `get_gps_version` | Return GPS version and build metadata |\n\n## MCP Resources\n\n| URI | Description |\n|-----|-------------|\n| `gps://schema` | Full database DDL with row counts — agents should read this first |\n| `gps://catalog` | Data source inventory (DATA_CATALOG.yaml) |\n\n## Wiring GPS into ACP Sessions\n\nGPS runs as a sidecar MCP in every ACP pod — no auth needed. The recommended approach is adding it to the runner's managed settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"gps\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--script\", \"/app/gps/mcp_server.py\"]\n    }\n  }\n}\n```\n\nBake `mcp_server.py` + `data/gps.db` + `VERSION` into the runner image or mount via shared volume. For init container and HTTP sidecar patterns, see [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).\n\n## Project Structure\n\n```\nmcp_server.py          MCP server (stdio default, --http for HTTP)\nscripts/\n  build_db.py          ETL pipeline — materializes gps.db from source files\n  test.sh              Test suite (lint, build, integrity, schema diff)\ndata/\n  acme-*               Example data files (tracked)\n  *.csv, *.xlsx, *.db  User data files (gitignored)\ndeploy/\n  deploy.sh            Build, apply, status, logs automation\n  k8s/                 Kubernetes/OpenShift manifests (kustomize)\ndocs/\n  adr/                 Architecture Decision Records\n  DEPLOYMENT.md        Deployment guide (local, container, k8s, ACP)\n  CUSTOMIZATION.md     Customization guide (env vars, adding sources)\n  SCHEMA.md            Database schema reference (ER diagram, tables, views)\ngovernance/            Policy documents (auto-loaded into DB)\nContainerfile          Container image build\n.env.example           Configuration template\n.mcp.json              Claude Code MCP server config\n```\n\n## Configuration\n\nGPS is configured via environment variables (see `.env.example`):\n\n- `GPS_TAB_ORG_MAP` — JSON mapping of XLSX tab names to `[org_key, org_name]` pairs\n- `GPS_JIRA_SCRUM_REF_TAB` — XLSX tab name for Jira-to-Scrum-team mappings\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambient-code%2Fgps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fambient-code%2Fgps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambient-code%2Fgps/lists"}