Skip to content

perf(mcp-gateway): drop agent_sdk from the Python stub's import path - #20670

Closed
chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:perf/stub-trim-imports
Closed

chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:perf/stub-trim-imports

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: make each MCP stub process start lighter by not loading a 14-module
subtree it never uses.

The Python MCP stub (kiro_crew.mcp_gateway.stub) runs once per session per MCP
server, so whatever it imports is multiplied by every stub on a host (on one
measured host, 965 stubs). A fresh stub import on current main loads 228
modules, including kiro_crew.agent_sdk and its 14 submodules — which the stub
never uses. It pulls them only because it imports the 10 managed server names
from mcp_cleanup, and mcp_cleanup eagerly imports agent_sdk.mcp_refs for an
unrelated constant. The stub needs only the names.

Why it matters

Every byte and module the stub imports is paid again by each of the many stub
processes a host runs. Dropping the agent_sdk subtree from the stub's import
path cuts per-stub resident memory and start cost at the only point the stub
actually touches those names, with no behaviour change.

Not a goal

  • Fewer stubs, or the stub's lifecycle/count — not touched.
  • The Rust stub (perf(mcp-gateway): Rust MCP stub, used by default when built #19627) — someone else's open work, not touched.
  • PoolKey, hashing, or any security code — not touched.
  • Lazy-loading concurrent.futures, urllib, ctypes, or
    executors/subprocess_pool: these are not stub-local (stdlib/shared-leaf,
    pulled on paths used across the codebase), so they are deliberately left alone.

What changed (motivation → approach → change)

  • Symptom: a fresh stub import loads 228 modules, with agent_sdk (14 submodules)
    resident though unused.
  • Root cause: the stub's top-level from kiro_crew.mcp_cleanup import KIROCREW_BIN_MCP_SERVERS drags in mcp_cleanup, whose line-24 import of
    agent_sdk.mcp_refs pulls the whole agent_sdk package.
  • Change: spell the 10 server names out as a module-local frozenset in
    stub.py, so a running stub never imports mcp_cleanup (or agent_sdk). This
    matches the file's own established pattern — _KIROCREW_MCP_SUBCOMMANDS is
    already spelled out in stub.py for exactly this reason, kept honest by a
    ratchet test. The two consumers (build_register_payload,
    _fallback_target_is_own_control_plane) read the same 10 names, now from the
    module-local set.

Before / after a fresh stub import, measured on current main:

modules kiro_crew.agent_sdk
before 228 loaded (14 submodules)
after 212 not loaded

16 fewer modules per stub; mcp_cleanup is also no longer imported by a running
stub.

Backwards compatibility

Removes nothing: the stub no longer re-exports mcp_cleanup's
KIROCREW_BIN_MCP_SERVERS as the identical object, but no code reads
KIROCREW_BIN_MCP_SERVERS from the stub module — a grep of src/ and test/
finds the only readers of stub.KIROCREW_BIN_MCP_SERVERS are the stub itself and
this PR's own tests. Every other src/ consumer imports the constant from
mcp_cleanup directly and is untouched. No default, UI, or user-facing output
changes.

Tests

  • test_mcp_gateway_stub_import_budget.py gains kiro_crew.agent_sdk to its
    forbidden-when-bridging set, so the footprint cannot silently return. It fails
    on main and passes here (red-first).
  • test_the_fallback_precheck_covers_every_control_plane
    (test_mcp_gateway_stub_session_token.py) now pins the stub's spelled-out set
    to mcp_cleanup's by value (and keeps the superset-of-CONTROL_PLANE_BACKENDS
    invariant), replacing the object-identity assertion the old re-export relied
    on.

Manual verification

N/A — unit coverage is sufficient; the change is import-path only and the
module-set bound plus the value-ratchet lock the behaviour in.

Related Issues

Closes #20642
Part of #20640

Checklist

  • At most two commits (one here), Conventional Commits title (perf: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A
  • No secrets, credentials, or internal references in the diff

CI note

Backend Tests (Windows) (7) fails on two cases in
test/test_app_mcp_tool_policy_scope.py (serves_managed_tools) that are
outside this diff — this PR touches only stub.py and two stub test files, not
mcp_shared.py. The cases pass locally in isolation; the shard failure is a
known Windows code-location fragility that #20711 fixes on main. Not retried
here.

… agent_sdk

The Python MCP stub runs once per session per MCP server, so what it imports
is multiplied by every session on the host. It imported the 10 managed server
NAMES from mcp_cleanup, which eagerly imports agent_sdk.mcp_refs for an
unrelated constant and so pulled kiro_crew.agent_sdk and its 14 submodules
into every stub.

Spell the names out as a frozenset in stub.py, the file's own established
pattern for exactly this (see _KIROCREW_MCP_SUBCOMMANDS). A fresh stub import
drops from 228 to 212 modules and no longer loads agent_sdk. The module-set
regression test gains kiro_crew.agent_sdk so the footprint cannot silently
return, and the fallback-precheck test now pins value equality against
mcp_cleanup's set instead of object identity.
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 15, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision c7684d73362e3ef184fc0f2e55d0f9b3ec24b7ce touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of c7684d73362e3ef184fc0f2e55d0f9b3ec24b7ce via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check the comment in stub.py: it names test_mcp_gateway_stub_import_budget as the test that keeps the copied set equal to mcp_cleanup, but test_mcp_gateway_stub_session_token does that.

Suggestions

  • Moving the 10 names into a small module that imports nothing, read by both mcp_cleanup and stub.py, would leave one source of truth and no copy to keep in sync.

[DESIGN-REVIEWED] c7684d7

Description read

[DESCRIPTION-READ] 601708b44a1b3e964b8149751953a6c255ed7b72679bf3dbddd6595e0f0ed61f

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed c7684d73362e3ef184fc0f2e55d0f9b3ec24b7ce via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c7684d7

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of c7684d73362e3ef184fc0f2e55d0f9b3ec24b7ce via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The stub gets a second hand-kept copy of the 10 server names, but the actual cause is one module-level import in mcp_cleanup used by one function.

Not justified as shipped

  • Item 2 — symptom-level: the description says "mcp_cleanup eagerly imports agent_sdk.mcp_refs for an unrelated constant". That constant is RESERVED_TOOL_NAMESPACES = frozenset({"builtin"}), and its only use in mcp_cleanup.py is line 572. The base calls mcp_cleanup "the leaf" set (stub.py:2816 and the rewritten test docstring), so the line-24 import is what broke that promise. The PR works around it with a copy plus a drift test. I grepped KIROCREW_BIN_MCP_SERVERS and counted 8 other src/ files that import it from mcp_cleanup and still load agent_sdk that way. Pointing to the _KIROCREW_MCP_SUBCOMMANDS precedent is an argument from analogy.
    Subtraction: delete the new stub.KIROCREW_BIN_MCP_SERVERS frozenset and its comment block. Move from kiro_crew.agent_sdk.mcp_refs import RESERVED_TOOL_NAMESPACES (mcp_cleanup.py:24) inside the function at line 572. Keep the stub's original mcp_cleanup import and the is pin.
    Clears when: the import is deferred and the copy is removed, or the import-budget test shows mcp_cleanup's remaining imports (atomic_write, config.paths, user_json) break the stub's budget even after the move.

What this change ships

Inventory (4 items) — 3 justified

Intent: make each MCP stub process start lighter by not loading the agent_sdk package it never uses. This is a FIX (perf, #20642).

  1. A fresh stub loads 16 fewer modules; agent_sdk is no longer loaded — justified
  2. A second spelled-out copy of the 10 managed server names, in stub.py — symptom-level; duplicates mcp_cleanup.KIROCREW_BIN_MCP_SERVERS
  3. Import-budget test now forbids kiro_crew.agent_sdk — justified
  4. Fallback-precheck test changes from an identity check to a value check — justified

[FIRST-PRINCIPLES-REVIEWED] c7684d7

Description read

[DESCRIPTION-READ] b0664a0fc98d0c11131dd9fa5e559fcb9261966fb619576f3d8f36cee4ee0a42

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Superseded by #20753, re-opened from the main repository so every review lane can publish.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

perf(mcp-gateway): trim the Python stub's remaining imports toward the 18.4 MB floor

1 participant