Skip to content

Add project-scoped CodeGraph freshness proxy - #4

Merged
FaithZL merged 15 commits into
devfrom
codex/codegraph-mcp-proxy
Aug 19, 2026
Merged

FaithZL merged 15 commits into
devfrom
codex/codegraph-mcp-proxy

Conversation

@FaithZL

@FaithZL FaithZL commented Aug 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • add a project-scoped, standard-library stdio MCP server exposing only polaris_codegraph_explore
  • bind pre-status, optional one-shot sync, explore, and post-status into one fail-safe freshness envelope
  • project ignored runtime bundles into immutable v3 Code Intelligence records with source/Git fallback evidence
  • register the proxy non-destructively for Codex and Claude Code projects, while preserving user-owned CodeGraph installation, initialization, raw MCP, watcher, and daemon configuration
  • migrate Polaris to protocol 0.1.21 / Host Adapter v3 while preserving immutable v1/v2 historical evidence
  • update English/Chinese documentation and every CodeGraph-capable stage skill; mark the old direct status/sync plan as historical

Why

The previous stage flow could inspect CodeGraph freshness separately from the graph query. That allowed project identity, pending changes, response banners, and post-query drift to lose their mechanical connection. The project proxy makes freshness adjacent to graph content and forces stale or unknown results into navigation-only mode with auditable source/Git fallback.

User impact

Repositories that already contain .codegraph/ can use one Polaris tool for bounded relationship queries. CodeGraph remains optional and non-gating. Polaris does not install or initialize CodeGraph and does not manage its raw MCP registration, watcher, or daemon. Validation remains graph-free.

Validation

  • python3 tests/run_tests.py — 201/201 passed
  • python3 -m unittest tests.test_codegraph -v — 92 passed
  • python3 -m unittest tests.test_core -v — 106 passed
  • python3 -m compileall -q polaris_cli.py scripts tests
  • python3 scripts/materialize_task_layout.py && git diff --exit-code
  • git diff --check dev...HEAD

The end-to-end test vendors Polaris into a disposable Git repository, launches the registered MCP command against an executable fake CodeGraph CLI, verifies the exact status/sync/explore/status call sequence and working directory, records the bundle as v3, confirms runtime ignore/hash binding, and proves project validation makes no CodeGraph call.

@FaithZL
FaithZL marked this pull request as ready for review August 19, 2026 02:19
@FaithZL
FaithZL merged commit f58d159 into dev Aug 19, 2026
3 checks passed
@FaithZL
FaithZL deleted the codex/codegraph-mcp-proxy branch August 21, 2026 03:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants