Py Cs Aviation MCP Claude

航空MCP

跨语言架构演示：一个调用C#后端微服务的Python MCP服务器，带有用于测试和交互的LangChain CLI客户端。

建筑

Architecture Diagram

该系统有四个通过Docker Compose编排的服务：

CLI客户端在主机上运行，并通过SSE连接到MCP服务器。

数据流

Flow Diagram

1. 客户端 发送自然语言查询（交互式）或直接调用MCP工具（批处理）
2. MCP服务器 接收工具调用，将其转换为HTTP GET到相应的C#服务
3. C#服务 过滤参数化JSON存根数据并返回结果
4. MCP服务器 格式化响应并将其返回给客户端

请求序列

Sequence Diagram

MCP工具

Stub数据覆盖范围

五个机场： 电池数据连接, 约翰·F·肯尼迪, 洛杉矶国际机场, 奥黑尔国际机场（芝加哥国际机场）, ATL 每个机场每次服务有3-4条记录。

项目结构

py-cs-aviation-mcp-claude/
├── docker-compose.yml              # Orchestrates all 4 services
├── src/
│   ├── aviation-mcp/               # Python MCP server
│   │   ├── Dockerfile
│   │   ├── pyproject.toml
│   │   └── src/
│   │       ├── server.py           # Entry point, tool registration
│   │       ├── config.py           # Environment-based configuration
│   │       ├── tools/              # MCP tool handlers (OOP)
│   │       ├── clients/            # Async HTTP clients for C# services
│   │       ├── models/             # Pydantic data models
│   │       └── debug_logging/      # JSON-RPC protocol logger
│   ├── aviation-mcp-client/        # LangChain CLI test client
│   │   ├── pyproject.toml
│   │   ├── src/
│   │   │   ├── client.py           # Entry point (REPL + batch modes)
│   │   │   ├── agent.py            # LangChain agent setup
│   │   │   ├── test_runner.py      # Batch test scenarios
│   │   │   └── config.py           # Client configuration
│   │   └── tests/
│   │       └── test_client.py      # 18 pytest unit tests
│   ├── flight-status/              # C# microservice (Controller -> Service -> Core)
│   │   ├── Dockerfile
│   │   └── src/
│   ├── gate-info/                  # C# microservice (same layering)
│   │   ├── Dockerfile
│   │   └── src/
│   └── weather/                    # C# microservice (same layering)
│       ├── Dockerfile
│       └── src/

快速开始

先决条件

• 码头工人 和 Docker Compose
• 紫外线 （Python包管理器）——用于运行CLI客户端
• LLM API密钥 （可选，仅用于交互模式）

启动所有服务

####

    # 1. Start all services
    docker-compose up --build -d

    # 2. Wait ~60s for health checks, then verify
    docker-compose ps

    docker-compose logs -f

    # 3. Run batch tests (no LLM key neededm in another window)
    cd src/aviation-mcp-client
    uv run python -m src.client --test --mcp-url http://localhost:8000/sse

    # 4. (Optional) Interactive mode (needs ANTHROPIC_API_KEY or LLM_API_KEY)
    LLM_API_KEY=your-key uv run python -m src.client --mcp-url http://localhost:8000/sse

    # 5. Check debug logs
    docker-compose logs aviation-mcp

    # 6. Cleanup
    docker-compose down

####

docker-compose up --build -d

等待健康检查（约60秒）：

docker-compose ps

所有C#服务都应该显示 healthy 在MCP服务器启动之前。

运行批量测试（不需要LLM密钥）

cd src/aviation-mcp-client
uv sync
uv run python -m src.client --test --mcp-url http://localhost:8000/sse

对所有3个工具运行8个预定义的测试场景。退出代码0=全部通过。

Connecting to MCP server at http://localhost:8000/sse...

  [PASS] Flight lookup at BDL
  [PASS] Flight by number
  [PASS] Unknown airport returns empty
  [PASS] Gates at JFK
  [PASS] Specific gate
  [PASS] Unknown gate returns empty
  [PASS] Weather at LAX
  [PASS] Unknown airport weather

Results: 8/8 passed

交互模式（需要LLM）

交互式REPL需要一个语言模型。支持三个提供商：

人为（默认）

LLM_API_KEY=your-anthropic-key uv run python -m src.client --mcp-url http://localhost:8000/sse

开放人工智能

LLM_PROVIDER=openai LLM_MODEL=gpt-4o LLM_API_KEY=your-openai-key \
  uv run python -m src.client --mcp-url http://localhost:8000/sse

Ollama（本地，不需要API密钥）

奥拉玛 在本地运行模型并公开与OpenAI兼容的API。不需要API密钥或云帐户。

1. 安装Ollama -- https://ollama.com/download

1. 拉一个模型 支持工具调用：

ollama pull llama3.2

其他支持工具调用的模型： mistral, qwen2.5, command-r.检查 Ollama模型库 查看完整列表。

1. 启动服务 （如果尚未运行）：

docker-compose up --build -d

1. 运行交互式客户端:

LLM_PROVIDER=ollama LLM_MODEL=llama3.2 \
  uv run python -m src.client --mcp-url http://localhost:8000/sse

如果Ollama在其他主机或端口上运行：

LLM_PROVIDER=ollama LLM_MODEL=llama3.2 LLM_BASE_URL=http://myhost:11434/v1 \
  uv run python -m src.client --mcp-url http://localhost:8000/sse

Aviation MCP Client (type 'quit' to exit)
Connected to MCP server at http://localhost:8000/sse
Tools available: ['get_flight_status', 'get_gate_info', 'get_weather']

> What flights are at BDL?

检查调试日志

docker-compose logs aviation-mcp

显示JSON-RPC消息、工具注册和请求/响应跟踪。

停止服务

docker-compose down

运行测试

所有测试（共68项）

# C# microservice tests (30 xUnit tests)
cd src/flight-status/src && dotnet test
cd src/gate-info/src && dotnet test
cd src/weather/src && dotnet test

# Python MCP server tests (17 pytest tests)
cd src/aviation-mcp && uv run pytest

# Python CLI client tests (21 pytest tests)
cd src/aviation-mcp-client && uv run pytest

个人服务测试

# Flight Status (11 tests)
cd src/flight-status/src && dotnet test --verbosity normal

# Gate Info (10 tests)
cd src/gate-info/src && dotnet test --verbosity normal

# Weather (9 tests)
cd src/weather/src && dotnet test --verbosity normal

# MCP Server (17 tests)
cd src/aviation-mcp && uv run pytest tests/ -v

# CLI Client (21 tests)
cd src/aviation-mcp-client && uv run pytest tests/ -v

技术栈

配置

MCP服务器环境变量

CLI客户端环境变量

CLI参数

python -m src.client [--test] [--mcp-url URL]

  --test       Run batch tests instead of interactive REPL
  --mcp-url    Override MCP server SSE URL

Docker编写服务

flight-status:  5001  # Health check: GET /api/flights
gate-info:      5002  # Health check: GET /api/gates
weather:        5003  # Health check: GET /api/weather
aviation-mcp:   8000  # Depends on all 3 C# services being healthy

所有服务都通过 aviation-net 网桥网络。MCP服务器在启动之前等待所有C#服务健康检查通过。