AgentGuard

AgentGuard is a policy-driven runtime authorization and security evaluation platform for MCP-based agents.

The repository has been scaffolded from AgentGuard_迭代开发计划书.md. Implementation begins with iteration 0: architecture, threat modeling, security boundaries, and the engineering baseline.

The executable iteration plan is documented in docs/week-0-development-plan.md.

Iteration 0 is complete; verification evidence is recorded in docs/week-0-completion-report.md.

The executable iteration-1 plan is documented in docs/week-1-development-plan.md.

Iteration 1 day-1 compatibility and contract evidence is recorded in docs/week-1-day-1-report.md.

Iteration 1 day-2 Mock MCP Server evidence is recorded in docs/week-1-day-2-report.md.

Iteration 1 day-3 Gateway lifecycle and proxy evidence is recorded in docs/week-1-day-3-report.md.

Iteration 1 day-4 audit persistence and deterministic Agent evidence is recorded in docs/week-1-day-4-report.md.

Iteration 1 is complete; final acceptance evidence is recorded in docs/week-1-completion-report.md.

Local development

Requirements: Python 3.12 and Docker Desktop with Docker Compose.

Copy-Item .env.example .env
python -m pip install -e ".[dev]"
docker compose up -d
python -m alembic upgrade head
python scripts/seed_dev_data.py
python scripts/check_infrastructure.py
python -m uvicorn main:app --reload

The Agent-facing MCP Streamable HTTP endpoint is http://127.0.0.1:8000/mcp/. The trailing slash is required by the mounted ASGI route. In baseline mode it exposes only the seven namespaced tools configured in config/mock-servers.yaml.

Run either deterministic LangGraph demo without an LLM key:

python -m agent_demo.cli get_order --order-id ORD-N-1001
python -m agent_demo.cli read_faq

Each successful call returns a trace_id. Inspect its redacted PostgreSQL audit chain with:

python scripts/show_trace.py <trace-id>

Run the complete non-interactive Week 1 acceptance chain with one command:

python -m scripts.week1_smoke

The smoke applies migrations, seeds fixed development references, checks PostgreSQL, Redis and MCP readiness, discovers all seven tools, runs both Agent tasks, and verifies their audit chains.

Week 1 tool catalog

file.delete_file
file.list_directory
file.read_file
notify.draft_message
notify.send_message
order.get_order
order.refund_order

A rejected MCP call returns only a stable public error and trace reference, for example:

{
  "error_code": "INVALID_TOOL_ARGUMENTS",
  "message": "Tool arguments are invalid.",
  "retryable": false,
  "trace_id": "<gateway-generated-uuid>"
}

Baseline authorization boundary

baseline_allowlist is a temporary development/test control, not a production authorization system. It has no JWT authentication, identity-aware discovery, RBAC, ABAC, policy evaluation, risk engine, or approval workflow. Production mode rejects baseline startup; audit records explicitly label it, and the baseline execution path must be removed after formal authorization is implemented in Weeks 2–5.

Quality checks:

python -m ruff check .
python -m ruff format --check .
python -m mypy gateway mcp_servers agent_demo main.py scripts
python -m pytest

Stop local services without deleting their data:

docker compose down

.env.example contains development-only placeholders. Production mode rejects the known demo secrets. PostgreSQL and Redis are bound to loopback for host-based development; Mock MCP Servers added in later iterations must remain on an internal Docker network and expose no host ports.

The development ports are 127.0.0.1:55432 for PostgreSQL and 127.0.0.1:56379 for Redis to avoid collisions with common local defaults. They use a dedicated development bridge while container-to-container data traffic stays on data_internal; remove host publishing when the Gateway itself is containerized.

Repository layout

• gateway/: MCP proxy, identity, policy, risk, approval, audit, registry, and scanner components.
• mcp_servers/: mock order, file, notification, and web-content MCP servers.
• agent_demo/: example agent integration.
• policies/: policy-as-code definitions.
• frontend/: approval, audit, and server-admission interfaces.
• tests/: unit, integration, and security evaluation cases.
• scripts/: evaluation and operational scripts.
• docs/: architecture, threat model, security boundaries, onboarding, and reports.