# 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.

## Architecture

```mermaid
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](docs/architecture.md) for module responsibilities
and [docs/security.md](docs/security.md) for the execution threat model.

## Run locally

```bash
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

```bash
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:

```bash
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](docs/sdlc-review.md).

## Evaluation gate

```bash
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:

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

Run the MCP server with additional container restrictions:

```bash
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](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.