Onboarding

What is AMTP? #

AMTP = Automated Multi-Agent Testing Pipeline. It is a ZagTrader internal system whose one-line description is:

Connect a private GitHub repository → three isolated LLM agents take turns analysing it → a pull request containing ready-to-run Playwright or Maestro test code appears on GitHub. AMTP never executes the tests.

Two things follow from that one sentence:

1. AMTP is a code-generation service, not a test runner. It produces .spec.ts (Playwright, web) and .yaml (Maestro, mobile) files and opens a PR. Reviewing, merging, and running those tests is left to humans and the target repo’s own CI. AMTP therefore needs no staging environment, no browser install, no device farm.
2. AMTP is built around a three-agent pipeline. Each agent is stateless and consumes/produces structured JSON. A deterministic orchestrator (Temporal, planned) sequences them and provides retries + durable state.

The three agents are:

What is and isn’t built yet #

This is the most important thing to internalise before reading the code, because the documentation site describes the intended architecture, not the current one.

Implemented and running today #

• GitHub MCP server (apps/github-mcp/) — TypeScript MCP server exposing seven tools over Streamable HTTP on port 8090. Three read tools (repo.tree, repo.read_file, repo.search_code) and four write tools (repo.branch_create, git.blob.create, git.tree.create, git.commit.create) implement the complete Git write path for the Test Engineer agent.
• Code Intelligence MCP server scaffold (apps/code-intel-mcp/) — sibling MCP server on port 8091. Currently returns an empty tools/list — tool implementation is in-progress under AUT-3. See apps/code-intel-mcp/PLAN.md for the full roadmap.
• Shared workspace package (packages/mcp-lib/) — @amtp/mcp-lib npm workspace package exposing logger, health, and otel shared across both MCP apps. Repo is now an npm workspace; single root package-lock.json.
• Healthcheck service (apps/healthcheck/) — Node service that pings Valkey and exposes /health on port 8083.
• OTel verifier (apps/otel-verify/) — small Python script (verify_trace.py) for confirming the observability stack accepts and stores traces.
• Database — Postgres 15 + PgBouncer (port 6432), schema applied via Flyway migrations (migrations/sql/V1..V6).
• Cache / queue — Valkey 8.0 (Redis-compatible).
• Documentation site (docs/AMTP_Docs_Website/) — static HTML site, built with node build.js and indexed with Pagefind, served by the docs nginx container.
• Observability stack — OTel collector, Tempo, Loki, Prometheus, Grafana (see docker-compose.observability.yml and infra/observability/).
• Secrets management — SOPS + age encrypted secrets committed as secrets/dev.sops.env; CI/CD materialises them via .github/actions/materialize-env/action.yml. See infra/sops/README.md.
• CI/CD — seven self-hosted GitHub Actions workflows under .github/workflows/, one per service (including code-intel-mcp-ci-cd.yml).

Planned, not yet in the repo #

• The three LLM agents (Repo Crawler, Test Case Generator, Test Engineer).
• Temporal orchestrator.
• Web frontend / API gateway for users to connect repos and trigger runs.
• AUT-3 tool implementations — ast.summarize_file, ast.extract_routes, ast.extract_components, ast.extract_selectors, ast.find_symbol in apps/code-intel-mcp/. Scaffold is shipped and healthy; tools are what remain.

Repository Layout #

Data Model #

Five tables, all in migrations/sql/, all UUID-keyed, all with ON DELETE CASCADE from parent → child. See Data Model for the full schema reference.

projects                  one row per connected GitHub repo
   │
   └── runs               one row per pipeline invocation
          │                 (depth_level: smoke|core|standard|deep)
          ├── stages      one row per agent step within a run
          │      │          (sequence + attempt for retries)
          │      └── artifacts   JSONB outputs produced by a stage
          │      │
          │      └── approvals   human-in-the-loop sign-offs on a stage
          │
          └── artifacts   run-level artifacts (not tied to a specific stage)

• stages.UNIQUE(run_id, sequence, attempt) lets a failed stage be retried without losing prior attempt history.
• artifacts.content is JSONB with a jsonb_typeof = 'object' check — every artifact is a structured agent output, never a free-form blob.
• runs.status is the orchestrator’s source of truth: pending → running → passed | failed | cancelled.

GitHub MCP Server #

apps/github-mcp/ is the part of the codebase you will spend the most time near, because (a) it is the working reference for “how an MCP server is built in this org” and (b) the AUT-3 Code Intelligence server you are about to build will sit alongside it. See GitHub MCP for the full reference.

Read tools (Stage 1 — Repo Crawler) #

• repo.tree — filtered, sorted, deterministic file tree for a repo subtree at a given ref. Honours gitignore-style patterns.
• repo.read_file — UTF-8 contents of a single file, truncated at max_bytes (default 64 KiB, cap 1 MiB), with binary-detection guard.
• repo.search_code — wraps GitHub’s Code Search API with auto-detected extension: / path: qualifiers, jittered retry on rate-limit, and ranked { path, snippet }[] output.

Write tools (Stage 3 — Test Engineer) #

• repo.branch_create — creates a new Git branch from an existing committish; idempotent if the ref already exists at the same SHA.
• git.blob.create — creates a Git blob from UTF-8 text or base64 content; returns the blob SHA.
• git.tree.create — creates a Git tree from a base tree SHA + an array of blob items; passing sha: null for a path deletes it.
• git.commit.create — creates a Git commit pointing at a tree SHA; appends a Run-Id: {run_id} Git trailer to the message for pipeline traceability.

Auth #

A GitHub App (not a PAT). Three pieces of config:

Internal structure (read in this order) #

1. src/index.ts, src/server.ts — entry point and MCP server wiring.
2. src/tools/ — seven tool files; each is a Zod input schema + validated handler. The write tools (repo-branch-create.ts, git-blob-create.ts, git-tree-create.ts, git-commit-create.ts) are the newer additions and show the idiomatic pattern most clearly.
3. src/lib/schema.ts — all Zod schemas and TypeScript output types.
4. src/lib/github.ts — Octokit client factory (App auth, throttling, resolveRef).
5. src/lib/otel.ts, telemetry.ts, logger.ts — observability wiring (template for any new service).

Infrastructure Stack #

Base file (docker-compose.yml) stands up these services. See Infrastructure for full configuration details.

The shared Docker network is explicitly named amtp_net (not the default <project>_amtp_net) so the observability compose file can reference it as external: true. Don’t change that name without also fixing the observability compose file.

CI/CD #

Seven self-hosted GitHub Actions workflows, one per deployable surface. See CI/CD for job-level detail.

Where AUT-3 (Code Intelligence) Fits #

AUT-3 is the Code Intelligence (AST) MCP Server — a sibling MCP server to the GitHub MCP one. Same transport, same observability conventions, different tools. See Code Intelligence MCP for the full reference page.

Purpose: wrap tree-sitter parsers for TypeScript, JavaScript, TSX, JSX, Python, Kotlin, Swift, and Dart, and expose tools that return AST-derived JSON summaries of source files instead of raw text.

Why it matters: token cost of feeding raw source files to LLM agents is the dominant bottleneck in this pipeline. AST-summarized output preserves the structural information agents actually use (function signatures, exports, class shapes) while dropping bodies they don’t need. Spec target: a 300-line TS file (~8,000 chars) → a 60-line JSON summary (~1,200 chars), ~85% reduction with no semantic loss.

Where to start #

1. The scaffold is already shipped at apps/code-intel-mcp/. Server starts, /healthz returns healthy, tools/list returns []. Read Phase 1 + 1.5 of apps/code-intel-mcp/PLAN.md to understand what was scaffolded.
2. Read Phase 2 of the plan for the three open design questions (WASM vs native, output JSON shape, cache key strategy) — these must be answered before writing tool code.
3. The 85% reduction target is the design constraint for every schema choice.

Quick Orientation #

Open Questions #

Things not derivable from the repo that you should clarify with the team before assuming:

1. AUT-3 design questions (Phase 2 of PLAN.md). Output JSON shape for ast.summarize_file, cache key strategy, and WASM-vs-native binding decision must be answered and written down before AUT-35 code lands.
2. Self-hosted runner build tools. CI uses WASM (web-tree-sitter) so no C compiler is needed today, but verify before switching to native bindings.
3. Secrets rotation process. infra/sops/README.md documents the age key setup and rotation procedures. Make sure your local key is registered in .sops.yaml before editing secrets.