# your-first-instrument — the CAM MCP starter

*A rig for your experiments, not a finished thing. Cloned in Session 3 of
Computationally Assisted Metacognition (CIS 7000, Penn, Fall 2026).*

The premise, in one breath: **an AI model only knows what is in its context
window — and an MCP server is how you hand it an instrument** so it can reach
what it lacks (a clock, a dataset, your notes, a museum's collection).
Building one is not hard. That is the whole lesson. By the end of the hour
yours will be running, connected to Claude, and answering questions the bare
model cannot.

## What's in the rig

- `server.py` — a small, working MCP server (a sense of time, ~40 lines).
  Two tools work; the third is a stub with your name on it.
- `docs/adr/` — **the choices live here, not in the code.** Every decision
  this repo made for you is written down with its reasons, so you inherit
  understanding, not just files. Disagree with one? Write the next ADR.
- `docs/TRACKS.md` — three feasible directions, sized for one session.
- `.vscode/` — the environment configures itself (extensions, project color).
- `render.yaml` — one-click deploy to Render's free tier, so your instrument
  gets a URL anyone's Claude can connect to.

## What you might need to install (once per machine)

macOS ships less than you'd think. In Terminal, in order (skip what you have):

```bash
# 1. Homebrew — the missing package manager for macOS (from brew.sh):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 2. uv — the Python project runner (installs Python itself if needed):
brew install uv
# 3. cloudflared — the tunnel that lets claude.ai reach your laptop:
brew install cloudflared
# 4. git — Apple installs it on first use; this just triggers that:
git --version
```

Windows: Do all of this inside WSL (see the course setup guide); the same
commands work there with `apt`-flavored Homebrew or the uv curl installer.

## Run it (2 minutes)

```bash
uv run server.py     # THAT'S IT — environment built, deps resolved, server up (port 8000)
```

Why not `pip install`? Your machine will refuse, and it's right to — see
`docs/adr/0004-virtual-environments-and-uv.md`: every project gets its own room.

Then hand it to your **local** collaborator (the claude CLI reaches localhost;
the browser claude.ai can't — it calls from the cloud, which is exactly why
deployment exists):

```bash
claude mcp add --transport http first-instrument http://localhost:8000/mcp
```

Ask it: *"What time is it? How long have we been talking?"* The model still
has no clock; it learned to consult one. Yours.

**To reach the browser claude.ai, a tunnel is REQUIRED** — claude.ai calls
from Anthropic's cloud and can never see your laptop directly:

```bash
brew install cloudflared          # once
cloudflared tunnel --url http://localhost:8000   # prints your public URL
```

Add that URL (`https://…trycloudflare.com/mcp`) in claude.ai → Settings →
Connectors — both surfaces now hold your instrument. The tunnel dies with
your terminal; when you want a PERMANENT home, deploy to Render (ADR-0003).

## Deploy it — a permanent home (Render, free)

The tunnel dies with your terminal. For an instrument that outlives your laptop:

1. **render.com** → Sign in **with GitHub** (the account holding your repo).
2. **New +** → **Blueprint** → select your repo → **Apply**. (`render.yaml` does the rest.)
3. ~2 minutes of build → copy your `https://….onrender.com` URL.
4. claude.ai → Settings → Connectors → edit `first-instrument` → swap URL to the Render one + `/mcp`.

Free-tier truth (ADR-0003): the instance naps when idle — first call after a nap
takes ~30s. Fine for an instrument; now you know why.

## License

MPL-2.0 with a Template Output Grant — the template stays open with attribution; what YOU build from it may be Apache-2.0 (open, attributed) or fully closed. See LICENSE + TEMPLATE-GRANT.md.