feat(antigravity): support mcp_config.json generation under .agents/

[okamiconcept]

feat(antigravity): support mcp_config.json generation under .agents/

TL;DR

apm install now correctly supports generating and updating workspace-local .agents/mcp_config.json (project scope) and ~/.gemini/config/mcp_config.json (user scope) configurations for the antigravity target. Remote connections are automatically formatted using the serverUrl field as required by the Google Antigravity connection schema.

Note

This completes the integration of the Antigravity target's configuration surface, complementing the rule and skill features added in PR #1984.

Problem (WHY)

• When installing MCP dependencies, the gating logic in mcp_integrator_install.py did not recognize antigravity in the installed runtimes lookup list, silently skipping MCP configuration even when antigravity was explicitly whitelisted in apm.yml or via the --target CLI flag.
• The default Gemini adapter formatting returned keys like url or httpUrl for remote servers, which Google Antigravity rejects in favor of serverUrl per the official Antigravity MCP Connection Schema.

Why these matter:
Grounding configurations in target-native schemas is essential for compatibility. As defined in target-detection guidelines:

"Each target is identified by a slug used in apm.yml's targets: field... Antigravity is registered as an explicit-only target."

Without proper gating and formatting support, the MCP servers are completely dropped for this target, violating the multi-harness portability contract.

Approach (WHAT)

Additive changes to the integration and client adapter layers to support runtime detection and correct formatting for the Antigravity target.

#	Fix (and why, if non-obvious)
1	Enable antigravity runtime discovery at both project scope (folder check) and user scope (binary check).
2	Explicitly map antigravity to itself in RUNTIME_TO_CANONICAL_TARGET mapping.
3	Override remote config formatting in AntigravityClientAdapter to output serverUrl instead of url/httpUrl.

Implementation (HOW)

• src/apm_cli/adapters/client/antigravity.py -- Overrode _format_server_config to convert remote server URL configuration keys (url or httpUrl) to "serverUrl".
• src/apm_cli/integration/mcp_integrator_install.py -- Added "antigravity" to the runtime discovery check. Updated _runtime_is_present and fallback logic to check for the .agents/ project folder (project scope) or the agy binary on PATH (user scope).
• src/apm_cli/integration/targets.py -- Mapped "antigravity": "antigravity" in RUNTIME_TO_CANONICAL_TARGET.
• CHANGELOG.md -- Documented the new feature under the Unreleased section.
• tests/integration/test_mcp_targets_gating_e2e.py -- Added E2E/integration tests verifying that targeting antigravity compiles a valid mcp_config.json containing stdio and remote configs.
• tests/unit/integration/test_antigravity_target.py -- Added unit tests covering the scope-aware presence checks and correct conversion of remote connection schemas.

Diagrams

Legend: This diagram shows the pipeline of target detection and gating mapping to formatting and final output writing.

flowchart LR
    subgraph Detect["Target Detection & Gating"]
        T1["--target antigravity"] --> V1["resolve_targets()"]
        V1 --> V2["Gate runtimes in _discover_installed_runtimes()"]
    end
    subgraph Formatting["Config Formatting"]
        V2 --> F1["AntigravityClientAdapter"]
        F1 --> F2["_format_server_config()"]:::new
        F2 -->|"serverUrl"| F3["update_config()"]
    end
    subgraph Output["Output config"]
        F3 --> O1[".agents/mcp_config.json"]
    end
    classDef new stroke-dasharray: 5 5;
    class F2 new;

Loading

Trade-offs

• Project-scope directory constraint. We chose to enforce the opt-in .agents/ directory presence check at project scope, meaning APM won't generate mcp_config.json in a project that has not initialized .agents/ yet. This aligns with existing target signals conventions.
• Inheritance reuse. Inheriting from GeminiClientAdapter allows reusing command/args formatting logic while surgically mapping remote endpoints keys.

Benefits

1. Seamlessly configure MCP servers from apm.yml for Google Antigravity CLI and IDE.
2. Ensure remote connection schemas align with official specifications.
3. Proper scope-aware gating prevents writing config files on hosts that lack the runtime.

Validation

All tests were successfully run and verified locally.

Full pytest output (25 tests)

============================= test session starts ==============================
platform linux -- Python 3.13.5, pytest-9.0.3, pluggy-1.6.0
rootdir: /home/mgravouil/Documents/datanumia/apm
configfile: pyproject.toml
plugins: split-0.11.0, cov-7.0.0, anyio-4.10.0, xdist-3.8.0
collecting ...
collected 25 items
tests/unit/integration/test_antigravity_target.py .....................  [ 84%]
tests/integration/test_mcp_targets_gating_e2e.py ....                    [100%]
============================== 25 passed in 1.25s ==============================

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	apm install writes the dedicated MCP configuration file to .agents/mcp_config.json inside project root when antigravity is active.	Portability by manifest, Multi-harness support	tests/integration/test_mcp_targets_gating_e2e.py::TestMCPTargetsGatingE2E::test_targets_whitelist_antigravity_allows_listed_runtimes	integration
2	apm install --global (user scope) writes MCP config to ~/.gemini/config/mcp_config.json when antigravity is active.	Portability by manifest, Multi-harness support	tests/unit/integration/test_antigravity_target.py::test_antigravity_mcp_user_path_is_gemini_config_mcp_config	unit
3	Remote SSE and HTTP servers are correctly formatted to use the serverUrl field instead of url or httpUrl in .agents/mcp_config.json.	Portability by manifest, DevX (pragmatic as npm)	tests/unit/integration/test_antigravity_target.py::test_antigravity_mcp_remote_server_uses_server_url	unit
4	Antigravity MCP runtime is detected at project scope when .agents/ exists, and at user scope when the agy binary is on PATH.	Multi-harness support, DevX (pragmatic as npm)	tests/unit/integration/test_antigravity_target.py::test_antigravity_mcp_runtime_is_detected_when_agents_dir_exists tests/unit/integration/test_antigravity_target.py::test_antigravity_mcp_runtime_is_detected_at_user_scope_when_agy_binary_exists	unit

How to test

• Initialize a project with .agents/ folder and dependencies declaration:

  targets:
    - antigravity
  dependencies:
    mcp:
      - name: test-remote
        registry: false
        transport: http
        url: https://api.example.com/mcp/

• Run apm install and verify .agents/mcp_config.json is generated correctly.
• Verify that serverUrl is used under test-remote configurations in the generated file.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

This PR completes MCP configuration support for the antigravity target by (1) ensuring the runtime is properly discovered/gated at install time and (2) emitting Antigravity-compatible remote server configuration using serverUrl, with tests covering both behaviors.

Changes:

• Add antigravity runtime discovery signals (project scope via .agents/, user scope via agy on PATH) to MCP install gating.
• Override Antigravity MCP remote formatting to emit serverUrl (instead of url/httpUrl).
• Add unit + integration coverage for Antigravity MCP config writing and gating, and record the feature in the changelog.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/apm_cli/integration/mcp_integrator_install.py	Adds antigravity to runtime discovery and implements scope-aware presence detection (.agents/ vs agy).
src/apm_cli/integration/targets.py	Maps antigravity runtime name to canonical target name.
src/apm_cli/adapters/client/antigravity.py	Overrides server config formatting to rename remote URL keys to serverUrl per Antigravity schema.
tests/unit/integration/test_antigravity_target.py	Adds unit tests for serverUrl formatting and Antigravity runtime presence detection.
tests/integration/test_mcp_targets_gating_e2e.py	Adds E2E test asserting .agents/mcp_config.json is written for targets: [antigravity] and remote formatting uses serverUrl.
CHANGELOG.md	Adds an Unreleased entry for the new Antigravity MCP config generation feature.