Aero Ref

Local agent + MCP demo: FlightAware AeroAPI (live airport boards) and Google BigQuery (demo airports catalog), orchestrated by mcp-use, LangGraph, and Ollama (langchain-ollama).

The Python package name is aero-ref (distribution); import path is aero_ref.

---

Long-form visual reference

Rendered HTML (diagrams, styling): the long-form doc is published at https://georgejinu-labs.github.io/aero-ref/ — built from docs/index.html. On GitHub’s file browser, docs/index.html opens as raw source; use the Pages URL above for a normal web page.

That page walks through a real aero-ref run: two MCP servers, LangGraph phases, token growth, max_steps, and the second-turn catalog edge case—aligned in spirit with execution.log (tool counts may differ as the demo evolves).

• Offline: open docs/index.html from a local clone in your browser (file path or drag into a window).

---

What a run looks like (execution.log)

execution.log is a captured trace from:

uv run .\main.py

with trace logging enabled (see Run). It shows the same pipeline you would see on the console:

1. Two stdio MCP sessions — mcp_use spawns uv run --directory <repo> src/aero_ref/flight_server.py and .../bigquery_server.py.

2. Cold initialize latency — in this log, flight ~17s and BigQuery ~21s (first import + deps + optional BigQuery warmup; your machine will differ).

3. Tool discovery — flight MCP exposes four tools; BigQuery MCP exposes two catalog tools, a tiny no-arg hint tool (get_demo_airport_hints), an MCP resource (reference://demo-airport-hints, same text), and MCP prompts (airport-summary, compare-airports) used by main.py when AGENT_USE_MCP_PROMPTS=1 (default).

   Server	Tools
   flight	get_airport_flights, get_airport_arrivals, get_airport_departures, get_airport_flight_counts
   bigquery	list_demo_airports, get_demo_airport, get_demo_airport_hints

4. LangGraph — ModelCallLimitMiddleware then model (ChatOllama → Ollama, e.g. qwen2.5:3b), then tools node issuing MCP tools/call JSON-RPC over stdin/stdout.

5. Example dialogue — first turn: catalog lookup for KIAH plus get_airport_flight_counts; second turn: compare airports (limited by which ICAO codes exist in your BigQuery airports table—the log illustrates a missing catalog row and model recovery).

6. Shutdown — sessions closed cleanly after agent.run completes.

Use that file when you want line-level correlation with LangChain [chain/*], [llm/*], and mcp-use DEBUG lines.

---

MCP prompts (workflow templates on the server)

An MCP prompt is a pre-built workflow template registered on the MCP server (here: src/aero_ref/bigquery_server.py), not a long instruction string baked into main.py. The client calls prompts/get with a name and arguments; the returned text becomes the user message passed to agent.run(...).

Why that matters: edge-case rules (for example, “if the catalog has no row for KHOU, say so and do not substitute DFW or another hub”) live with the server, so every run gets the same guardrails without duplicating paragraphs in the driver. The same hint text is available as MCP reference://demo-airport-hints and as get_demo_airport_hints() (no arguments). Prefer the tool in LangGraph runs: mcp-use maps resource reads to LangChain tools that require a valid uri, and small models often pass invalid placeholders. Authoritative rows still come from get_demo_airport.

Defaults in main.py: with AGENT_USE_MCP_PROMPTS=1 (default), turn 1 uses prompt airport-summary (AGENT_PROMPT_ICAO, default KIAH); turn 2 uses compare-airports (SECOND_PROMPT_ICAO_A / SECOND_PROMPT_ICAO_B, default KHOU / KIAH). Set AGENT_USE_MCP_PROMPTS=0 to use plain AGENT_QUERY and SECOND_AGENT_QUERY strings instead.

---

Architecture (short)

Piece	Role
main.py	Loads mcp_config.json, builds MCPClient + ChatOllama + MCPAgent, runs scripted queries (env-configurable).
src/aero_ref/flight_server.py	FastMCP server: AeroAPI HTTP tools (API key from env).
src/aero_ref/bigquery_server.py	FastMCP server: read-only BigQuery queries for the demo airports table.
mcp-use	Spawns servers, MCP protocol over stdio, adapts tools for LangChain.
LangGraph	Agent loop inside MCPAgent with step limits (AGENT_MAX_STEPS, middleware).

---

Prerequisites

• uv
• Ollama running with your model pulled (default: qwen2.5:3b)
• FlightAware AeroAPI key — FLIGHTAWARE_API_KEY or AEROAPI_KEY in .env
• Google BigQuery — BIGQUERY_PROJECT or GOOGLE_CLOUD_PROJECT, dataset/table env vars, and Application Default Credentials (e.g. gcloud auth application-default login or GOOGLE_APPLICATION_CREDENTIALS)

---

Setup

cd C:\path\to\aero-ref
uv sync

Copy and edit .env at the repo root (see comments in your template). Load demo airport data when needed: scripts/load_bq_demo_tables.py and related SQL under scripts/.

BigQuery smoke test (no MCP):

uv run python scripts/test_bigquery_connection.py

---

Run

uv run python main.py

Optional queries (defaults are in main.py):

• AGENT_USE_MCP_PROMPTS=1 (default) — first/second messages from BigQuery MCP prompts; tune with AGENT_PROMPT_FIRST, AGENT_PROMPT_ICAO, SECOND_AGENT_PROMPT, SECOND_PROMPT_ICAO_A, SECOND_PROMPT_ICAO_B.
• AGENT_USE_MCP_PROMPTS=0 — use string queries instead: AGENT_QUERY, SECOND_AGENT_QUERY

Verbose trace (similar style to execution.log):

$env:FLIGHT_BOOKING_AGENT_TRACE = "1"
uv run python main.py

(WEATHER_AGENT_TRACE=1 is also accepted for the same behavior.)

For mcp-use INFO-style logs without full LangChain verbosity: MCP_USE_DEBUG=2.

Telemetry: mcp-use may log anonymized telemetry; set MCP_USE_ANONYMIZED_TELEMETRY=false to disable.

Python 3.14: you may see a LangChain / Pydantic v1 compatibility warning; it does not stop the demo from running in typical setups.

---

Tests

uv run pytest

---

MCP config for other hosts

mcp_config.json is the source of truth for Cursor or other MCP clients. main.py rewrites --directory to the repo root at runtime so paths stay correct when you move the project.