# Frank — the course MCP server

The teaching build for **Claude for Engineering Teams — From Chat to Agent
Pipelines**, Sections 5–7. An MCP server that runs on AWS EC2 and gives
every agent your team already uses — Claude Desktop, Claude Code, VS Code,
GitHub Copilot — typed, audited, least-privilege tools over your
infrastructure and GitHub pipeline.

> One server. Every agent your team already uses.

This is a clean-room teaching build: small on purpose, every tool under
~40 lines, built live on camera in two passes.

## The toolbox

| Pass | Lecture | Tool | What it answers |
|---|---|---|---|
| 1 — infra | 5.3 | `instance_health()` | "How's the box?" |
| 1 — infra | 5.3 | `service_status(name)` | "Is shipit up?" |
| 1 — infra | 5.3 | `tail_log(service, lines)` | "What's it logging?" |
| 1 — infra | 5.3 | `deploy_status()` | "What's deployed?" |
| 2 — pipeline | 5.4 | `list_workflow_runs(limit)` | "Is CI green?" |
| 2 — pipeline | 5.4 | `get_failed_jobs(run_id)` | "What failed?" |
| 2 — pipeline | 5.4 | `get_job_log(job_id)` | "Why did it fail?" |
| 2 — pipeline | 5.4 | `pr_checks(pr_number)` | "Can this PR merge?" |

Design rule (Lecture 5.3): each tool does one job with typed inputs and a
small, capped output. Agents compose tools; we don't build "do everything"
tools.

## Security posture (Lecture 5.5)

- **Credential boundary:** Frank holds the IAM role and the GitHub PAT.
  Laptops and prompts never see a secret.
- **Fine-grained PAT:** one repo, Actions: read. Frank observes; the repair
  agent writes with its own credential.
- **IAM:** read-mostly, region-pinned, no wildcards (`deploy/iam-policy.json`).
- **Transport:** bearer-token auth, private bind, tunnel/VPN access only.
- **Allowlists everywhere:** services Frank may inspect are enumerated in
  config, not discovered.
- **Audit:** every tool call is a loggable event; systemd hardening in
  `deploy/frank.service`.

## Quick start (local, no AWS needed)

```bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
export FRANK_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
.venv/bin/python -m frank.server
# then: claude mcp add --transport http frank http://127.0.0.1:8720/mcp \
#         --header "Authorization: Bearer $FRANK_AUTH_TOKEN"
```

`instance_health`, `service_status`, and `tail_log` read /proc and systemd,
so they return real data on any Linux box. GitHub tools need
`FRANK_GITHUB_TOKEN` + `FRANK_GITHUB_REPO` (see `.env.example`).

EC2 deployment, IAM, and client wiring: `deploy/ec2-setup.md`.

## Repo layout

```
frank/
  config.py        # all configuration, all from env
  tools_infra.py   # pass 1 — Lecture 5.3
  tools_github.py  # pass 2 — Lecture 5.4
  server.py        # FastMCP wiring + auth — Lectures 5.5–5.6
deploy/
  frank.service    # systemd unit, hardened
  iam-policy.json  # read-mostly instance role
  ec2-setup.md     # the on-camera deployment walkthrough
```

## Recording checkpoints

Tag the repo as you record so students can check out each lecture's state:
`git tag lecture-5.3` after pass 1, `lecture-5.4` after pass 2,
`lecture-5.5` after auth + hardening.