Skip to content

perf(mcp-gateway): spell out managed server names in the stub to drop agent_sdk - #20753

Merged
iamwhatever merged 1 commit into
mainfrom
perf/stub-trim-imports
Oct 23, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
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: mcp_cleanup imported agent_sdk.mcp_refs at module scope
    (mcp_cleanup.py:24) for a single constant, RESERVED_TOOL_NAMESPACES. The
    stub's from kiro_crew.mcp_cleanup import KIROCREW_BIN_MCP_SERVERS therefore
    dragged the whole agent_sdk package into every stub.
  • Change: move that import into its one reader, prune_dangling_tool_refs, so it
    is paid only when that function runs. A lazy import is behaviour-preserving.
    An earlier revision of this PR copied the names into stub.py instead; the
    First Principles review asked for the cause to be fixed rather than the symptom
    worked around, and this revision adopts that — fixing the eager import removes
    agent_sdk from the stub and from mcp_cleanup's other importers, with no
    duplicated list and no drift test to maintain. (See the First Principles
    thread on this PR.)

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

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

14 fewer modules per stub (the whole agent_sdk subtree); the stub still imports
mcp_cleanup, which no longer pulls agent_sdk.

Backwards compatibility

Removes nothing: the only change is when agent_sdk.mcp_refs is imported
inside mcp_cleanup — moved from module scope into the one function
(prune_dangling_tool_refs) that reads RESERVED_TOOL_NAMESPACES. Every public
name mcp_cleanup exports is unchanged, KIROCREW_BIN_MCP_SERVERS is still the
same object every importer reads, and the function's behaviour is identical (the
import resolves on first call instead of at module load). 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 a fresh/bridging stub import may never load
    agent_sdk again. It fails on main (where mcp_cleanup's eager import pulls
    agent_sdk into the stub) and passes here (red-first).
  • The existing prune_dangling_tool_refs / RESERVED_TOOL_NAMESPACES coverage
    (test_mcp_dangling_tool_refs.py, test_agent.py) continues to pass with the
    import deferred into the function, confirming the lazy import is
    behaviour-preserving.

Manual verification

N/A — unit coverage is sufficient; the change moves one import inside a function
and the module-set bound locks the stub footprint 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

Dependency License Gate fails on every PR in this repository (a repository
setting, not something this diff affects) and is left as-is.

Note on test/test_app_mcp_tool_policy_scope.py (serves_managed_tools): a
Windows shard flagged two of its cases once on an earlier run, but they are
outside this diff — this PR touches only mcp_cleanup.py and one stub import
test, not mcp_shared.py where serves_managed_tools lives — and they pass
here. The behaviour is a known Windows code-location fragility that #20711
addresses on main.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e 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

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

The PR title still describes the abandoned approach ("spell out managed server names in the stub"); retitle it to match the lazy import before merge.

[DESIGN-REVIEWED] 4ec3b7e

Description read

[DESCRIPTION-READ] b419d55605d641a37899de57bd2a711ce31d26118d51eb5da971ac46b6d5fbd8

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

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e — 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: PASS

The PR title still says "spell out managed server names in the stub". The diff instead defers mcp_cleanup's agent_sdk import, so retitle before squash-merge.

What this change ships

Inventory (2 items) — 2 justified

Intent: make each per-session MCP stub process start lighter by not loading the unused agent_sdk subtree. This is a FIX: perf, at cause level.

  1. Importing mcp_cleanup (stub, rewriter, session_servers, control_plane, gatewayd) no longer loads kiro_crew.agent_sdk; the import moves into prune_dangling_tool_refs, the only function that reads RESERVED_TOOL_NAMESPACES (mcp_cleanup.py:577) — justified
  2. The stub import-budget test now forbids kiro_crew.agent_sdk in a bridging stub, which pins the saving — justified

[FIRST-PRINCIPLES-REVIEWED] 4ec3b7e

Description read

[DESCRIPTION-READ] 5d97d1b5637cdac17497b377cc98709671cb34e76533bd013a0139fd4bb3e26a

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 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4ec3b7e

Verdict parsed from the review's SHA-scoped output markers for commit 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4ec3b7e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 4ec3b7e84ee3819ea82e0191a1bb1d0e8133cb2e: <one-sentence reason>

@chenmingwei23
chenmingwei23 force-pushed the perf/stub-trim-imports branch from c7684d7 to 18c0430 Compare October 15, 2026 09:26
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Thanks — fixed in 18c0430. The comment at stub.py:616 now names test_mcp_gateway_stub_session_token, which is where the equality pin (stub.KIROCREW_BIN_MCP_SERVERS == frozenset(mcp_cleanup.KIROCREW_BIN_MCP_SERVERS)) actually lives; test_mcp_gateway_stub_import_budget pins the forbidden-module set, not the name-set equality.

On the leaf-module suggestion: a shared names-only module would remove the hand-kept copy, but it also edits mcp_cleanup and adds a new module imported across the codebase — wider than this perf change needs. The spelled-out set here follows the file's own existing _KIROCREW_MCP_SUBCOMMANDS pattern and the drift test keeps it honest, so I've kept the change stub-local. The single-source-of-truth refactor would be a good standalone follow-up.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

On the First Principles CONCERNS (advisory) at head 18c0430 — answering the subtraction point by point:

1. "Make the mcp_cleanup.py:24 import of agent_sdk.mcp_refs call-time instead of copying the names."
That is a real alternative and it would remove agent_sdk from the stub and from the other mcp_cleanup importers. But it changes mcp_cleanup, a module ~24 src/ files import, and it defers an import that is currently module-level — shifting when agent_sdk first loads (and any import-time error it would raise) into mcp_cleanup's hot path. That is a wider, behaviour-shifting edit than this perf change needs, and it touches code outside the stub. The issue (#20642) is specifically about the Python stub's import path; keeping the change stub-local is the smallest honest version of that goal. The deferred-import refactor is a legitimate separate change against mcp_cleanup with its own blast-radius review.

2. "A third hand-typed copy of the 10 names."
Agreed this is a copy, and the drift test exists precisely because of it. It is the same trade the file already made for _KIROCREW_MCP_SUBCOMMANDS (spelled out, pinned by a ratchet test) rather than a new pattern. The equality pin in test_mcp_gateway_stub_session_token fails if the copy ever diverges from mcp_cleanup, so the duplication cannot silently rot.

3. "This is an addition / perf change, no defect fixed."
Correct — it is a perf change, labelled as such; no behaviour changes.

Net: the subtraction is viable but out of this PR's goal and footprint. I've left the stub-local copy + drift test as the minimal change for #20642 and noted the deferred-import refactor as a reasonable follow-up. CONCERNS is advisory and does not block readiness; holding this as the shipped shape unless a maintainer directs the mcp_cleanup refactor instead.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the perf/stub-trim-imports branch from 18c0430 to 7725619 Compare October 15, 2026 09:56
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Adopted the subtraction in 7725619. The eager import at mcp_cleanup.py:24 is gone — from kiro_crew.agent_sdk.mcp_refs import RESERVED_TOOL_NAMESPACES now lives inside its one reader, prune_dangling_tool_refs. The stub's KIROCREW_BIN_MCP_SERVERS copy and the drift-test rewrite are deleted; the stub imports the name from mcp_cleanup again, and mcp_cleanup no longer pulls agent_sdk.

A fresh stub import now loads 214 modules (down from 228) with no agent_sdk, and the saving reaches mcp_cleanup's other importers too. The module-budget regression test keeps kiro_crew.agent_sdk forbidden in a bridging stub (red on main, green here). The lazy import is behaviour-preserving — the prune_dangling_tool_refs / RESERVED_TOOL_NAMESPACES coverage (test_mcp_dangling_tool_refs.py, test_agent.py) passes unchanged.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Update for 7725619: the hand-kept copy you flagged (and its drift test) is gone. The root cause is now fixed instead — mcp_cleanup's agent_sdk.mcp_refs import is deferred into its one reader — so the stub imports KIROCREW_BIN_MCP_SERVERS from mcp_cleanup as before, with no second copy to keep in sync. That also removes the stub comment that named the wrong drift test.

@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
…rops it

The per-session MCP stub imports the 10 managed server NAMES from
mcp_cleanup. mcp_cleanup imported agent_sdk.mcp_refs at module scope for a
single constant (RESERVED_TOOL_NAMESPACES), so that NAME import pulled
kiro_crew.agent_sdk and its 14 submodules into every stub.

Move the agent_sdk.mcp_refs import into its one reader
(prune_dangling_tool_refs). A lazy import is behaviour-preserving. A fresh
stub import drops from 228 to 214 modules and no longer loads agent_sdk,
and the saving also reaches mcp_cleanup's other importers. The module-set
regression test forbids kiro_crew.agent_sdk in a bridging stub so the
footprint cannot silently return.
@chenmingwei23
chenmingwei23 force-pushed the perf/stub-trim-imports branch from 7725619 to 4ec3b7e Compare October 15, 2026 10:23
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Follow-up for 4ec3b7e: the description now matches the diff. It describes the lazy-import approach in mcp_cleanup (deferring agent_sdk.mcp_refs into prune_dangling_tool_refs), gives the module count measured on this HEAD (228 → 214, agent_sdk not loaded), and no longer claims a stub.py spelled-out set or a session-token test change — the earlier revision's wording. The earlier CONCERNS was formed against that superseded description.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@chenmingwei23
chenmingwei23 marked this pull request as ready for review October 22, 2026 01:55
@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 22, 2026 01:55
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 22, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head 4ec3b7e. The change itself looks good to ship.

What I checked:

  • Moving the agent_sdk.mcp_refs import into prune_dangling_tool_refs is behaviour preserving. RESERVED_TOOL_NAMESPACES has no other reader in mcp_cleanup, nothing re-imports it from mcp_cleanup, and no test patches it there.
  • Red first holds: with main's mcp_cleanup.py the updated import budget test fails 3 cases; at this head it and test_mcp_dangling_tool_refs.py pass (36 passed). A fresh stub import at this head does not load kiro_crew.agent_sdk.
  • All five AI lanes name this head with no blocking findings, and readiness is passed.

One should fix, non blocking:

🟡 The PR title still describes the earlier revision. It says "spell out managed server names in the stub", but this head no longer touches stub.py; it defers an import in mcp_cleanup. The squash commit takes the PR title, so the history on main would describe a change that did not land. Suggested title: perf(mcp-gateway): defer mcp_cleanup's agent_sdk import so the stub drops it, which matches the commit headline.

Not approving yet: the CodeQL Analyze (python) run on this head is still in progress. Once the title matches the diff and that check is green, this is ready.

@iamwhatever

Copy link
Copy Markdown
Contributor

Hold at 4ec3b7e. The code is ready. One requested change is still open.

The Design and First Principles lanes, and bolichen97's review, all ask for a new title before merge, and there has been no reply. The title still says "spell out managed server names in the stub", but this head no longer touches stub.py. The squash commit takes the title, so main's history would describe a change that did not land. Retitling to something like perf(mcp-gateway): defer mcp_cleanup's agent_sdk import so the stub drops it clears it. Retitling does not move the head.

The change itself is sound. The deferred import has no other reader in mcp_cleanup, the stub family on current main still imports from mcp_cleanup, the new budget pin locks in the saving, and every check including CodeQL is green. I read CI and source and ran nothing.

— crew-pr-reviewer (r119)

@iamwhatever
iamwhatever merged commit 3af6ae7 into main Oct 23, 2026
109 checks passed
@iamwhatever
iamwhatever deleted the perf/stub-trim-imports branch October 23, 2026 07:23
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 2026
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.

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

3 participants