feat(examples): ship echo-mcp, an MCP server bundle that runs through the gateway

[earakely-scale]

Summary

A second example bundle, echo-mcp, ships in the wheel beside hello. Where hello needs nothing, echo-mcp needs Docker. It builds an MCP server from a Dockerfile, deploys it through the gateway, and checks it by calling its tool:

$ agent-env run echo-mcp
envs/echo (Dockerfile image): building with docker, which can take minutes
envs/echo (Dockerfile image): v1 (new)
envs/echo: v1 (new)
artifacts/check_echo: v1 (new)
tasks/smoke.json: v1 (new)
service-db env 'default-db' (missing): building, which can take minutes
gateway env 'default' (missing): building, which can take minutes
[tasks/smoke.json] step 1/2 env (deploy_env)
…
Tasks:
  tasks/smoke.json v1: passed (echoes: 1), 24.5s, instance @local/agentenv-framework/echo-mcp/smoke-…

Tore down 1 sandbox.

agent-env run lists it beside hello. A rerun writes nothing.

The bundle

src/agent_env/examples/echo-mcp/, registered as echo-mcp = "agent_env.examples":

• envs/echo/, the server:
  • server.py is an AgentEnvEnvironment with one tool, echo, which returns the text it's sent. @environment_card(name="echo") names the env, so it needs no env.toml.
  • The Dockerfile uses the gateway's own pinned python:3.11-slim, so a first run pulls that base once.
  • requirements.txt names agentenv-framework-protocol and mcp>=1.25,<2. The protocol doesn't install mcp, and without it the container exits at startup.
• artifacts/check_echo/verify.py, one file, so a file artifact: it calls echo through the env's MCP endpoint and checks the text comes back.
• tasks/smoke.json: deploy_env → env_outcome_verifier. Deploying through the gateway, the default, builds the gateway and service-database infra on the first run.

Release pin

publish-pypi.yml pins the protocol line in requirements.txt to the release's exact version, as it already pins pyproject.toml. In the repo the line is unpinned, so a run from a clone installs the newest published protocol. tst/unit/test_release_protocol_pins.py checks, on every PR, that each file the release rewrites (pyproject.toml and the requirements path the workflow names) holds exactly one line its sed matches. A moved folder or a rewritten line then fails the PR, instead of a release after the protocol is already on PyPI.

Tests

• Slow tier (run_bundle_built_envs_test.py): runs agent-env run echo-mcp by name, then reruns it. The rerun must leave the image, env, artifact and task at "v1, unchanged". Passed locally in 65 s.
• Unit: the plugin-report test now counts both bundles the core ships. The unit tier: 8,075 passed. One gateway time-trigger test (process_scope_socket_test) failed under parallel load, and passes alone three times out of three; it fails the same way on other branches.
• Installer tier: the container journey's agent-env plugin list row now reads bundle echo-mcp, bundle hello. test_container_journey.py passed locally (2 passed).
• Clean install, run locally: passed. Its check that every tracked example file ships in the wheel now covers echo-mcp's six files.
• The installed wheel, by hand: installed with --compile-bytecode, which leaves __pycache__ in both envs/echo/ and artifacts/check_echo/. Two runs of echo-mcp both pass, and the second leaves every entry unchanged. So the compiled files change neither a hash nor check_echo's type as a single-file artifact.

Not hot path (an example, docs and the publish step), so no release of its own. The example reaches users with the next release.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, with no blocking issues found.

Summary

Adds echo-mcp, a bundled example that builds a Docker image, deploys an MCP server through the gateway, and checks its echo tool.

• You can run a Docker-built echo MCP example by name.
• Release builds pin the example server to their protocol version.

No actionable new issues were found. No previous review threads were supplied.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["agent-env run echo-mcp"] --> B["Build echo image"]
  B --> C["Deploy through gateway"]
  C --> D["Call echo tool"]
  D --> E["Check returned text"]
  E --> F["Tear down sandbox"]

Loading

_{Reviews (4) · Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." · Reviewed by Greptile}