diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 62c0b57..2d2c852 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,13 +1,12 @@ # GPS - Global Positioning System MCP Server -Read-only caching tier for org and engineering data. Materializes people, teams, issues, features, releases, and governance into a SQLite database. Optimized for sub-millisecond agent queries over MCP — no auth, no rate limits. +Read-only caching tier for org and engineering data. Materializes people, teams, issues, features, releases, and governance into a SQLite database and serves them over MCP. ## Structure - `mcp_server.py` — MCP server (stdio default, `--http` for HTTP) - `scripts/` — ETL pipeline (build_db.py, test.sh) - `data/` — source files + gps.db (user data gitignored, acme-* examples tracked) - `deploy/` — Kubernetes manifests + deploy.sh automation -- `docs/` — ADRs, deployment, customization, schema reference - `governance/` — org policies (auto-loaded into DB) ## Commands @@ -18,26 +17,11 @@ uv run mcp_server.py # start MCP server (stdio) uv run mcp_server.py --http # start MCP server (HTTP :8000) ``` -## MCP Tools (read-only, no auth) -- `lookup_person` — find people by name, email, or user ID -- `list_team_members` — list team roster with roles and components -- `search_issues` — filter issues by status, priority, assignee, component, label, keyword -- `get_feature_status` — feature details: progress, RICE score, releases, teams -- `release_risk_summary` — flags features under 80% complete near milestones -- `list_documents` — governance documents with table of contents -- `get_document` — full governance document by ID -- `get_document_section` — single section by fuzzy heading match -- `get_gps_version` — version and build metadata - -## MCP Resources -- `gps://schema` — full DDL with row counts (read this first) -- `gps://catalog` — data source inventory - -## ACP Integration -GPS runs as a sidecar MCP in every ACP pod. No auth needed — read-only org data. Wire via managed settings, init container, or HTTP sidecar. See docs/DEPLOYMENT.md. - ## Rules - Never commit: csv, xlsx, pdf, db, .env, tokens, secrets (except data/acme-* examples) - Database (data/gps.db) is always opened read-only - Use uv (not pip). Use ruff (enforced by pre-commit). - `scripts/test.sh` is bash — run directly, not via `uv run` + +## More Info +See [BOOKMARKS.md](BOOKMARKS.md) for deployment docs, schema reference, and ADRs. diff --git a/BOOKMARKS.md b/BOOKMARKS.md new file mode 100644 index 0000000..05592aa --- /dev/null +++ b/BOOKMARKS.md @@ -0,0 +1,29 @@ +# Bookmarks + +## Table of Contents +- [Deployment](#deployment) +- [Schema & Data](#schema--data) +- [Architecture Decisions](#architecture-decisions) + +--- + +## Deployment + +### [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) +Deployment guide covering local dev, ACP integration, container builds, OpenShift/Kubernetes manifests, and CI/CD workflow. + +### [deploy/deploy.sh](deploy/deploy.sh) +CLI for building images, pushing to registries, and applying kustomize manifests. Run `deploy/deploy.sh` with no args for usage. + +## Schema & Data + +### [docs/SCHEMA.md](docs/SCHEMA.md) +Full database schema reference with table descriptions and column details. + +### [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md) +How to add custom data sources, configure ETL, and extend the database. + +## Architecture Decisions + +### [docs/adr/](docs/adr/) +Architecture Decision Records for GPS design choices.