# Context Engineering with MCP: Build AI Systems That Actually Remember

<img src="images/cover.png" alt="Context Engineering with MCP Course Cover" width="700"/>

Welcome to the training hub for mastering **Context Engineering with Model Context Protocol (MCP)**. This course teaches you to implement production-ready semantic memory systems for AI assistants using Python, FastAPI, FastMCP, and LangGraph.

---

## Quick Start

### Prerequisites

- **Python 3.13** (pinned in `.python-version`) — `onnxruntime` (a chromadb dependency) does not yet ship 3.14 wheels
- Node.js 20+ (for Lab 01 and MCP Inspector)
- [uv](https://docs.astral.sh/uv/) package manager (recommended for Python)
- Claude Desktop or Claude Code

### Option 1: Hello MCP Lab (Beginner Entry Point)

```bash
git clone https://github.com/timothywarner-org/context-engineering.git
cd context-engineering/labs/lab-01-hello-mcp/starter
npm install && npm start

# Test with MCP Inspector (in another terminal)
npx @modelcontextprotocol/inspector node src/index.js
```

### Option 1.5: MCP Chat CLI Lab (Python Bridge)

```powershell
cd labs/lab-02-mcp-chat
.\run.ps1
```

`run.ps1` is the **on-rails launcher**: it bootstraps `.env`, lifts `ANTHROPIC_API_KEY` from the repo-root `.env`, and launches the chat REPL. **Lab 02** is the smallest complete Python **MCP client + stdio server + REPL** in the repo - the conceptual bridge between Lab 01 (JS hello-world) and WARNERCO (production-shaped).

### Option 1.7: MCP Apps Lab (Interactive UI Surfaces)

```bash
cd labs/lab-03-mcp-apps
```

**Lab 03** ships three npm MCP servers (budget-allocator, map, system-monitor) that render interactive `ui://` surfaces in Claude Desktop via SEP-1865 (MCP Apps extension, spec 2026-01-26). See [`labs/lab-03-mcp-apps/README.md`](labs/lab-03-mcp-apps/README.md).

### Option 1.9: Remote MCP + OAuth on Azure

**Lab 04** is a remote MCP server secured by Entra ID OAuth, fronted by Azure API Management as the authorization-server facade, with an Azure Functions Python backend. Deploy with `azd up`, connect per [`remote-mcp-apim-functions-python/QUICKSTART.md`](remote-mcp-apim-functions-python/QUICKSTART.md), then tear down the same day with `azd down --purge --force`.

### Option 2: WARNERCO Schematica (Flagship Teaching App)

```bash
cd src/warnerco/backend
uv sync
uv run uvicorn app.main:app --reload    # HTTP server at http://localhost:8000
uv run warnerco-mcp                      # MCP stdio server for Claude Desktop
uv run warnerco-restart                  # Force-kill port 8000 and restart uvicorn
```

The `warnerco-restart` command (from `scripts/restart_server.py`) terminates anything bound to port 8000 (Windows: `netstat` + `taskkill /F /T`; POSIX: `lsof` + `SIGKILL`) before restarting. Flags: `--kill-only`, `--port N`.

---

## Course Structure (4 x 50 Minutes)

| Segment | Topic                          | Focus                                                                       |
| ------- | ------------------------------ | --------------------------------------------------------------------------- |
| **1**   | Context, Made Visible          | Consumer LLMs hide context; dev tools (Claude Code, Copilot) expose it       |
| **2**   | MCP: Standard for Context      | The protocol + a server on the official `mcp` SDK; current best practices    |
| **3**   | Memory Tiers in a Real App     | WARNERCO's four CoALA tiers live; orchestration kept under the hood          |
| **4**   | MCP in the Tools You Use       | Claude Code + GitHub Copilot in VS Code as context-engineering surfaces      |

Full plan: `instructor/course-plan-june-2026.md` (context-first, official-SDK-first; delivered 2026-06-30). The earlier orchestration-forward plan is archived under `instructor/archive/`.

### Segment Notebooks

`notebooks/segment-1.ipynb` through `segment-4.ipynb` are four **prepopulated, verified teaching notebooks**, one per 50-minute segment. Each opens with a **repo-root anchor cell** that walks up to `.git`, so it runs from any working directory. They print **live counts** (never hardcoded), and Segment 3 runs the full pipeline with live Anthropic prose. Open them in **VS Code with the Jupyter extension** and **Run All**. Verified to run error-free from both the repo root and `notebooks/`.

---

## WARNERCO Schematica Architecture

The flagship teaching application exercises **all four CoALA memory tiers** (Sumers et al. 2024) in a 9-node LangGraph pipeline:

```
+--------------------------------------------------------------------------+
|                          FastAPI + FastMCP                               |
+--------------------------------------------------------------------------+
|  LangGraph Flow (9-node CoALA-tiered RAG)                                |
|  parse_intent -> query_graph -> inject_scratchpad -> recall_episodes ->  |
|  retrieve -> compress_context -> reason -> respond -> log_episode        |
+--------------------------------------------------------------------------+
|  Four CoALA Memory Tiers                                                 |
|  +------------+  +-----------+  +----------+  +------------------------+ |
|  | Working    |  | Episodic  |  | Semantic |  | Procedural             | |
|  | Scratchpad |  | events.db |  | Vector   |  | MCP Prompts (versioned)| |
|  | (SQLite)   |  | (SQLite)  |  | store    |  | catalog://procedural   | |
|  +------------+  +-----------+  +----------+  +------------------------+ |
+--------------------------------------------------------------------------+
|  Consolidation ("sleep cycle"): scratchpad+episodic --(ctx.sample)--> semantic |
+--------------------------------------------------------------------------+
```

### CoALA Tier Reference

| Tier        | What it stores                                | Backed by                            | LangGraph node                          |
| ----------- | --------------------------------------------- | ------------------------------------ | --------------------------------------- |
| Working     | Session observations & inferences             | `data/scratchpad/notes.db` (SQLite)  | `inject_scratchpad`                     |
| Episodic    | Timestamped events with importance            | `data/episodic/events.db` (SQLite)   | `recall_episodes` + `log_episode`       |
| Semantic    | Durable facts (incl. consolidated `FACT-*`)   | Vector store (Chroma / Azure / JSON) | `retrieve`                              |
| Procedural  | Versioned skills/workflows                    | MCP `@mcp.prompt()` registrations    | (user-invoked, not in pipeline)         |

The **`reason` node** (LangGraph node 6) synthesizes prose via the official **`anthropic` Python SDK** (`AsyncAnthropic`); if the backend `.env` lacks the key it degrades gracefully - retrieval still works and the prose shows a fallback message.

Episodic recall uses **Park et al.'s scoring formula** — `α_recency · 0.5^(hours/half_life) + α_importance · stored + α_relevance · cosine(query, summary)` — and `warn_episodic_recall` returns the per-event score breakdown so students can see why each memory surfaced.

The knowledge graph is indexed at `src/warnerco/backend/data/graph/knowledge.db` with **117 entities** and **221 relationships** across 6 predicates (`has_tag`, `compatible_with`, `belongs_to_model`, `has_status`, `has_category`, `contains`).

### Progressive Tool Loading

The server registers **28 MCP tools**, **12 resources**, and **5 prompts**. Two meta-discovery tools implement progressive tool loading per Anthropic's "code execution with MCP" guidance:

- `warn_search_tools(query, detail, limit)` — keyword discovery with detail levels `name`, `summary`, `full`
- `warn_describe_tool(name)` — full schema for a single tool by name

Both meta-tools self-exclude from `warn_search_tools` results, so `count` is up to 26 even when `total` is 28. Clients can list tools cheaply, then pull full schemas only for what they actually plan to call.

---

## Repository Structure

```
context-engineering/
├── src/warnerco/backend/      # WARNERCO Schematica (FastAPI + FastMCP + LangGraph)
├── labs/lab-01-hello-mcp/     # Lab 01: Hello MCP, single add tool (JS)
├── labs/lab-02-mcp-chat/      # Lab 02: MCP client + server + chat REPL (Python, vendored)
├── labs/lab-03-mcp-apps/      # Lab 03: MCP Apps, interactive ui:// surfaces (JS/TS, SEP-1865)
├── remote-mcp-apim-functions-python/  # Lab 04: remote MCP + Entra ID OAuth via APIM (Python + bicep)
├── notebooks/                 # Four verified segment teaching notebooks (segment-1..4)
├── docs/                      # Student materials, tutorials, diagrams
├── instructor/                # Instructor-only materials
├── config/                    # Sample MCP client configurations
├── .vscode/                   # VS Code workspace configuration
├── .claude/                   # Claude Code agents and skills
└── CLAUDE.md                  # Development instructions (SOURCE OF TRUTH)
```

**For development details, see [CLAUDE.md](CLAUDE.md)** - the source of truth for:
- Complete MCP tool reference (28 tools)
- API endpoint documentation
- Environment variable configuration (incl. `EPISODIC_*`)
- 9-node LangGraph pipeline details
- All four CoALA memory tiers (Working / Episodic / Semantic / Procedural)

**For the framework explainer (read this first):** see [docs/tutorials/coala-explainer.md](docs/tutorials/coala-explainer.md) — what CoALA is and where each tier lives in the WARNERCO codebase.

**For the classroom demo:** see [docs/tutorials/coala-memory-walkthrough.md](docs/tutorials/coala-memory-walkthrough.md) — the ~4-minute four-tier classroom path.

---

## MCP Client Configuration

### Claude Desktop

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "warnerco": {
      "command": "uv",
      "args": ["run", "warnerco-mcp"],
      "cwd": "C:/github/context-engineering/src/warnerco/backend"
    }
  }
}
```

### Claude Code (project scope)

`.claude/mcp.json` is checked in with two entries pointing at the same server: `claude-warnerco-schematica` and `claude-warnerco-coala-memory` (the second pre-pins the episodic-memory env vars for class demos).

### VS Code Copilot

`.vscode/mcp.json` is checked in with a single `vscode-warnerco-schematica` entry (`MEMORY_BACKEND=chroma`) plus the GitHub Copilot remote MCP server `ghcopilot-warner`. To list servers in VS Code: `Cmd/Ctrl+Shift+P → MCP: List Servers`.

---

## Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector uv run warnerco-mcp
# Opens http://localhost:6274
```

---

## Resources

- **[MCP Specification](https://spec.modelcontextprotocol.io/)** - Official protocol documentation
- **[FastMCP Documentation](https://github.com/jlowin/fastmcp)** - Python MCP framework
- **[CLAUDE.md](CLAUDE.md)** - Development instructions for this repository

---

## Your Instructor

### Tim Warner

**Microsoft MVP** - Azure AI and Cloud/Datacenter Management
**Microsoft Certified Trainer** (25+ years)

- Website: [techtrainertim.com](https://techtrainertim.com)
- GitHub: [@timothywarner](https://github.com/timothywarner)
- LinkedIn: [linkedin.com/in/timothywarner](https://www.linkedin.com/in/timothywarner/)

---

## License

MIT License - 2026 Timothy Warner

---

**Now go build AI systems that actually remember!**