MCP Agent Execution Runtime

A Python runtime for inspectable agent workflows and AI-augmented software delivery. It combines MCP tools, bounded code execution, session-scoped context, change-risk analysis, intelligent test selection, optional evidence-cited LLM review, policy decisions, traces, and regression evaluation.

What it implements

• Official stdio Model Context Protocol server built with the MCP Python SDK.

• Five tools: run_agent_workflow, run_bounded_python, get_session_context, list_runtime_skills, and review_sdlc_change.

• An AI-augmented SDLC review tool that parses unified diffs, ranks repository context within a character budget, maps changed paths to tests, detects rule-based risk signals, and drafts review documentation.

• An opt-in OpenAI-compatible review adapter with an untrusted-context prompt boundary, strict JSON validation, evidence-ID enforcement, graceful fallback, and mandatory human review.

• Declarative skill registry mapping named skills to capabilities and risk levels without duplicating execution logic.

• Role-separated planner, execution, and reviewer subagents coordinated by a workflow orchestrator.

• Expression-only Python execution in an isolated child interpreter with AST allowlists, an empty working directory, a cleared environment, timeouts, output limits, and best-effort POSIX CPU, memory, file, and descriptor limits.

• SQLite session memory with namespace validation, entry and context-window limits, secret redaction, and explicit deletion.

• JSONL observability traces containing hashes, timings, policy results, and status without raw prompts or secrets.

• Deterministic evaluation cases with a quality gate and JSON/Markdown reports.

• Unit, integration, MCP client/server, and policy-denial tests in GitHub Actions.

Related MCP server: RoadBoard

Architecture

flowchart LR
  A["MCP client"] --> B["Official stdio MCP server"]
  B --> C["Runtime tool service"]
  C --> D["Workflow orchestrator"]
  C --> M["SDLC change-review service"]
  D --> E["Planner subagent"]
  D --> F["Execution subagent"]
  D --> G["Reviewer subagent"]
  D --> L["Declarative skill registry"]
  F --> H["Bounded Python child process"]
  D --> I["SQLite session memory"]
  C --> J["JSONL trace recorder"]
  M --> J
  M --> N["Optional OpenAI-compatible LLM"]
  K["Evaluation cases"] --> C

See docs/architecture.md for module responsibilities and docs/security.md for the execution threat model.

Run locally

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests -v
mcp-agent-runtime eval --cases evals/runtime_cases.json --report-dir reports
mcp-agent-runtime sdlc-eval --cases evals/sdlc_review_cases.json --report-dir reports
mcp-agent-runtime run "calculate: sum([4, 8, 15, 16, 23, 42])" --session example

Run the MCP server

mcp-agent-runtime mcp

Configure a compatible MCP client to start the installed mcp-agent-runtime executable with the mcp argument. The integration test launches the server over stdio, completes initialization, lists all five tools, and calls both the workflow and SDLC review tools.

AI-augmented SDLC review

review_sdlc_change always runs deterministic context selection, change-risk analysis, test mapping, and documentation drafting. Set use_llm=true to add a review from an OpenAI-compatible endpoint:

export SDLC_LLM_BASE_URL="https://provider.example/v1"
export SDLC_LLM_MODEL="review-model"
export SDLC_LLM_API_KEY="replace-at-runtime"
mcp-agent-runtime mcp

The API key is read only from the environment. Repository snippets are marked untrusted, context and output are bounded, cited evidence IDs must be present in the packet, invalid provider output fails closed to an empty model finding set, and every response requires human review. See docs/sdlc-review.md.

Evaluation gate

mcp-agent-runtime eval --cases evals/runtime_cases.json --report-dir reports
mcp-agent-runtime sdlc-eval --cases evals/sdlc_review_cases.json --report-dir reports

The runtime cases cover allowed operations and policy denial. The SDLC cases cover security, delivery, data-contract, test-selection, human-review, and context-budget behavior. A release passes only when every case in both suites meets its expected outcome.

Container execution

Build the image:

docker build -t mcp-agent-execution-runtime .

Run the MCP server with additional container restrictions:

docker run --rm -i \
  --network none \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --pids-limit 64 \
  --memory 256m \
  --cpus 0.5 \
  mcp-agent-execution-runtime mcp

Security boundaries

The expression runner is layered and deliberately narrow. It is useful for demonstrating policy enforcement and resource controls, but it is not described as a complete hostile-code security boundary. Production execution should add an independently hardened container or microVM boundary, syscall filtering, per-tenant credentials, network policy, image provenance, and centralized audit storage. See docs/security.md.

Evidence boundaries

This is a portfolio runtime using deterministic subagents, local storage, and an optional provider adapter. CI does not send code to an LLM, and the project does not operate against customer repositories, measure organization-level developer productivity, automate merge decisions, prove production scale, or claim production-grade isolation. Those limits are intentional and documented so the implemented controls remain interview-defensible.