MTR MCP服务器-完整文档

生产服务器: https://project-1-04.eduhk.hk/mcp/\ 最后更新：2025年10月24日\ 版本：3.0（带内存的完整MCP功能集）

______________________________________________________________________

📑 目录

概述
生产部署
快速开始
MCP检验员测试
LangGraph集成
地方发展
文档
建筑
主要特点
故障排除

______________________________________________________________________

🎯 概述

该项目实现了 生产就绪模型上下文协议（MCP）服务器 香港地铁系统，与 LangGraph代理 和 AWS基岩Nova Lite 用于自然语言交互。

包含内容

✅ 完整MCP服务器 使用工具、资源和提示
✅ LangGraph代理 有对话记忆
✅ 自然语言处理 93个地铁站
✅ 双工具界面 （人性化+机器可读）
✅ 实时MTR数据 香港政府API
✅ 生产部署 在NGINX上使用SSL/TLS
✅ LangSmith集成 可观察性
✅ 完整的测试套件 包含6个测试文件

技术

MCP服务器：FastMCP（Python）+FastAPI
LLM框架：LangGraph+LangChain
AI模型：AWS基岩Nova Lite
运输：服务器发送事件（SSE）
记忆：内存保护程序（持久对话）
部署：Docker+NGINX反向代理

______________________________________________________________________

🌐 生产部署

🚀 Live服务器：MCP服务器已部署并准备就绪！

端点

端点	URL	目的
SSE（主要）	`https://project-1-04.eduhk.hk/mcp/sse`	MCP客户端的流式HTTP
健康	`https://project-1-04.eduhk.hk/mcp/health`	服务器运行状况
信息	`https://project-1-04.eduhk.hk/mcp/info`	服务器功能
文档	`https://project-1-04.eduhk.hk/mcp/docs`	API文件

建筑

Internet (HTTPS:443)
    ↓
NGINX Reverse Proxy
    ├─ SSL/TLS termination
    ├─ SSE-optimized (no buffering)
    └─ Location: /mcp/ → http://127.0.0.1:8080/mcp/
    ↓
Docker Container (:8080)
    ├─ Python 3.11 slim
    ├─ Health checks
    └─ Auto-restart
    ↓
FastAPI Application (fastapi_mcp_integration.py)
    ├─ MCP Protocol: 2025-06-18 (Streamable HTTP)
    ├─ SSE connection handling
    └─ JSON-RPC message routing
    ↓
MCP Server (mcp_server.py)
    ├─ 2 Tools (train schedules)
    ├─ 2 Resources (stations, network)
    └─ 3 Prompts (journey planning)
    ↓
MTR API (data.gov.hk)

部署功能

✅ MCP协议：2025-06-18（流式HTTP）
✅ SSL/TLS：加密的HTTPS连接
✅ Nginx：SSE优化的反向代理配置
✅ 码头工人：带有健康检查的容器化部署
✅ 24/7正常运行时间：生产准备就绪，可进行监控
✅ 自动重启：容器在故障时重新启动

快速测试

# Health check
curl https://project-1-04.eduhk.hk/mcp/health

# Expected: {"status":"healthy","service":"mtr-mcp-server",...}

# SSE endpoint (streaming)
curl -N -H "Accept: text/event-stream" https://project-1-04.eduhk.hk/mcp/sse

# Expected: event: message
#           data: {"jsonrpc":"2.0",...}

______________________________________________________________________

🚀 快速开始

1.安装

# Clone or navigate to project directory
cd C:\Users\user\Documents\mtr-mcp-fastapi-example

# Activate virtual environment
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

2.环境设置

创建 .env 文件：

# AWS Bedrock Credentials (required for LangGraph demo)
AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
AWS_REGION=us-east-1
BEDROCK_MODEL=amazon.nova-lite-v1:0

# MCP Server - Use production server (no local setup needed!)
MCP_SERVER_URL=https://project-1-04.eduhk.hk/mcp/sse

# Alternative: Use local development server
# MCP_SERVER_URL=http://localhost:8080/mcp/sse

# LangSmith (Optional - for observability)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langsmith-api-key
LANGCHAIN_PROJECT=mtr-demo

3.运行LangGraph演示

无需本地MCP服务器！ 只需运行：

# Run the full MCP demo with production server
python langgraph_demo_full_mcp.py

发生了什么：

✅ 连接到生产MCP服务器 https://project-1-04.eduhk.hk/mcp/sse
✅ 加载MCP资源（93个港铁车站，网络图）
✅ 使用MCP工具创建LangGraph代理
✅ 演示有记忆的5轮对话
✅ 显示上下文感知的多回合交互

样本输出：

✓ MCP Server URL: https://project-1-04.eduhk.hk/mcp/sse
  (Using deployed production server)
✓ Environment variables loaded
✓ Using model: amazon.nova-lite-v1:0

🚀 Connecting to MCP server...
   ✓ Attempting to connect to https://project-1-04.eduhk.hk/mcp/sse

📚 Loading MCP Resources...
   Found 2 resources:
   - mtr://stations/list: MTR Stations List
   - mtr://lines/map: MTR Lines Map
   ✓ Loaded station reference

🔧 Loading MCP Tools...
   Found 2 tools:
   - get_next_train_schedule: Get MTR train schedule
   - get_next_train_structured: Get structured JSON data

🤖 Building LangGraph Agent...
   ✓ Agent ready with Tools, Resources, and Prompts

💬 Starting Multi-turn Conversation with Memory
...

______________________________________________________________________

🧪 MCP检验员测试

GUI模式

# Start MCP Inspector
npx @modelcontextprotocol/inspector

配置：

连接类型：直接
服务器URL: https://project-1-04.eduhk.hk/mcp/sse

您可以测试的内容：

工具选项卡

- get_next_train_schedule -人性化格式 - get_next_train_structured -JSON格式 - 参数测试： line=TKL, sta=TKO

资源选项卡

- mtr://stations/list -查看所有93个带有代码的车站 - mtr://lines/map -查看网络拓扑

提示选项卡

- check_next_train -快速时间表检查 - plan_mtr_journey -多步行程规划 - compare_stations -车站比较

实时测试

- 执行工具并查看实时MTR数据 - 查看SSE消息流 - 调试协议消息

命令行接口命令模式

# List available tools
npx @modelcontextprotocol/inspector --cli \
  https://project-1-04.eduhk.hk/mcp/sse \
  --method tools/list

# Call a tool
npx @modelcontextprotocol/inspector --cli \
  https://project-1-04.eduhk.hk/mcp/sse \
  --method tools/call \
  --tool-name get_next_train_schedule \
  --tool-arg line=TKL \
  --tool-arg sta=TKO

# Read a resource
npx @modelcontextprotocol/inspector --cli \
  https://project-1-04.eduhk.hk/mcp/sse \
  --method resources/read \
  --uri mtr://stations/list

______________________________________________________________________

🤖 LangGraph集成

建筑

LangGraph代理使用MCP服务器提供对MTR数据的自然语言访问：

User Query
    ↓
LangGraph Agent (AWS Bedrock Nova Lite)
    ↓
Decision: Need MTR data?
    ├─ YES → Call MCP Tool
    │         ↓
    │      MCP Server (production)
    │         ↓
    │      MTR API
    │         ↓
    │      Return data to agent
    │         ↓
    │      Format response
    └─ NO → Use memory/knowledge
    ↓
Natural language response
    ↓
Save to memory (for next turn)

记忆和多回合上下文

代理维护对话历史记录：

# Turn 1
User: "When is the next train at Tseung Kwan O?"
Agent: [Calls MCP tool] "Next train in 3 minutes to LOHAS Park"
Memory: Saves "Tseung Kwan O" context

# Turn 2 (references previous)
User: "What about the other direction?"
Agent: [Uses memory] "Next train in 5 minutes to North Point"

# Turn 3
User: "Compare it with Hong Kong station"
Agent: [Remembers TKO] [Calls tool for HOK] [Compares both]

主要特点

✅ 工具：2个MCP工具（人机格式）
✅ 资源：2个MCP资源（站+网络）
✅ 鼓励：3个MCP提示（模板）
✅ 记忆：对话历史记录的内存保存程序
✅ 上下文：多回合上下文感知

______________________________________________________________________

💻 地方发展（可选）

如果您想在本地运行自己的MCP服务器进行开发：

启动本地服务器

# Option A: FastAPI integration (recommended)
python fastapi_mcp_integration.py

# Option B: Original MCP server
python mcp_server.py

预期产量：

============================================================
🚀 Starting MTR MCP Server under /mcp
============================================================
🌐 Server: http://0.0.0.0:8080
📡 SSE Endpoint: http://0.0.0.0:8080/mcp/sse
📖 API Docs: http://0.0.0.0:8080/mcp/docs
🔍 Health Check: http://0.0.0.0:8080/mcp/health
============================================================

本地端点

上海证券交易所: http://localhost:8080/mcp/sse
健康: http://localhost:8080/mcp/health
信息: http://localhost:8080/mcp/info
文档: http://localhost:8080/mcp/docs

Docker部署

# Build and run locally
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop
docker-compose down

何时使用本地vs生产

使用生产(https://project-1-04.eduhk.hk/mcp/sse)何时：

✅ 向他人展示
✅ 在没有Docker的机器上运行
✅ 与远程协作者共享
✅ 变更前的最终验证

使用本地(http://localhost:8080/mcp/sse)何时：

🔧 开发新的MCP功能
🐛 测试协议变更
🔍 使用断点进行调试
📝 迭代提示/工具

______________________________________________________________________

📚 文档

此存储库包含 全面的文件:

核心文件

README.md （此文件）

- 项目概述 - 生产部署信息 - 快速入门指南 - 测试说明

MCP_GUIDE.md

- 完整的MCP协议参考 - 协议规范（2025-06-18） - FastAPI实施指南 - MCP检查器使用 - 调试和故障排除 - LangGraph集成模式

MTR_API.md

- MTR API文件 - 全部10条线路和93个车站 - API端点和参数 - 响应格式 - 代码示例（Python、JavaScript、React）

部署\_ INFO.md

- 详细的部署架构 - 安全最佳实践 - 故障排除指南 - 协议版本比较 - NGINX配置

关键主题

MCP协议：什么是MCP，为什么它很重要，三个原语（工具、资源、提示）
流式HTTP：采用SSE传输的最新协议版本（2025-06-18）
FastAPI集成：如何 fastapi_mcp_integration.py 实施MCP
生产部署：NGINX配置、Docker设置、SSL/TLS
LangGraph代理：使用MCP工具和内存构建AI代理
系统提示：用MTR领域知识指导人工智能行为
朗史密斯：LLM应用程序的可观察性和跟踪性

______________________________________________________________________

🏗️ 建筑

系统组件

┌─────────────────────────────────────────────────────────┐
│                   CLIENT LAYER                          │
│  • MCP Inspector (debugging)                            │
│  • LangGraph Agent (AI application)                     │
│  • Custom clients (your applications)                   │
└──────────────────┬──────────────────────────────────────┘
                   │ HTTPS/SSE
┌──────────────────▼──────────────────────────────────────┐
│               TRANSPORT LAYER                           │
│  • NGINX Reverse Proxy                                  │
│  • SSL/TLS Termination                                  │
│  • SSE Optimization (no buffering)                      │
└──────────────────┬──────────────────────────────────────┘
                   │ HTTP
┌──────────────────▼──────────────────────────────────────┐
│              APPLICATION LAYER                          │
│  • FastAPI (fastapi_mcp_integration.py)                 │
│  • MCP Protocol Handler (2025-06-18)                    │
│  • JSON-RPC Message Router                              │
└──────────────────┬──────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────┐
│                MCP SERVER LAYER                         │
│  • MCP Business Logic (mcp_server.py)                   │
│  • Tools: get_next_train_schedule,                      │
│           get_next_train_structured                     │
│  • Resources: mtr://stations/list,                      │
│               mtr://lines/map                           │
│  • Prompts: check_next_train,                           │
│             plan_mtr_journey,                           │
│             compare_stations                            │
└──────────────────┬──────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────┐
│                 DATA LAYER                              │
│  • MTR Next Train API (data.gov.hk)                     │
│  • Real-time train schedules                            │
│  • 10 lines, 93 stations                                │
└─────────────────────────────────────────────────────────┘

文件结构

mtr-mcp-fastapi-example/
├── README.md                          # This file (complete guide)
├── MCP_GUIDE.md                       # MCP protocol reference
├── MTR_API.md                         # MTR API documentation
├── DEPLOYMENT_INFO.md                 # Deployment details
│
├── fastapi_mcp_integration.py         # FastAPI + MCP (deployed)
├── mcp_server.py                      # MCP business logic
├── langgraph_demo_full_mcp.py         # LangGraph demo
│
├── requirements.txt                   # Python dependencies
├── docker-compose.yml                 # Docker configuration
├── Dockerfile                         # Container definition
├── .env                               # Environment variables
│
└── test_*.py                          # Test suite (6 files)

______________________________________________________________________

✨ 主要特点

MCP功能（完整实施）

特征类型	计数	示例
工具	2	`get_next_train_schedule`, `get_next_train_structured`
资源	2	`mtr://stations/list`, `mtr://lines/map`
鼓励	3	`check_next_train`, `plan_mtr_journey`, `compare_stations`

工具1： `get_next_train_schedule` （人性化）

目的：以可读格式显示列车时刻表

输入: line="TKL", sta="TKO", lang="EN"

输出示例:

🚇 MTR Train Schedule for TKL-TKO
🕐 Current Time: 2025-10-24 14:30:00

🔼 UPBOUND Trains:
  1. 🚆 Platform 1 → LHP - 2 minutes
  2. 🚆 Platform 1 → LHP - 8 minutes

🔽 DOWNBOUND Trains:
  1. 🚆 Platform 2 → NOP - 3 minutes

✅ Status: Normal operation

工具2： `get_next_train_structured` （机器可读）

目的：为程序化访问提供结构化JSON

输入: line="TKL", sta="TKO", lang="EN"

输出示例:

{
  "resolved_line": "TKL",
  "resolved_station": "TKO",
  "timestamp": "2025-10-24 14:30:00",
  "up": [
    {"dest": "LHP", "ttnt": "2", "plat": "1", "time": "14:32:00"}
  ],
  "down": [
    {"dest": "NOP", "ttnt": "3", "plat": "2", "time": "14:33:00"}
  ],
  "error": null
}

自然语言支持

✅ 93个地铁站 模糊匹配
✅ 全名: "Tseung Kwan O" → "TKO"
✅ 线路名称: "Airport Express" → "AEL"
✅ 不区分大小写: "hong kong" 作品
✅ 伤寒耐受性: "Tseng Kwan O" → "TKO"

支持的地铁线路

线路代码	名称	车站	示例车站
将军澳线	将军澳	8	将军澳、LHP、POA、NOP
曝光锁定	机场快线	5	HOK、KOW、AIR、AWE
ISL	港岛线	17	KET、ADM、CEN、CHW
TCL	东涌线	8	HOK、OLY、TSY、TUC
TML	屯马线	27	WKS、DIH、HOM、TUM
密封的	东铁线	16	ADM、UNI、SHS、LMC
硅	南岛线	5	ADM、OCP、SOH
潜伏期	荃湾线	16	尖沙咀、莫、腊、天水围
KTL	观塘线	17	WHA、YMT、DIH、TIK
深度强化学习	迪士尼乐园	2	孙，迪士尼

______________________________________________________________________

🐛 故障排除

连接错误

症状：“无法连接到MCP服务器”

解决方案:

# 1. Verify server is reachable
curl https://project-1-04.eduhk.hk/mcp/health

# Expected: {"status":"healthy",...}

# 2. Test SSE endpoint
curl -N -H "Accept: text/event-stream" https://project-1-04.eduhk.hk/mcp/sse

# Expected: event: message
#           data: {"jsonrpc":"2.0",...}

# 3. Check your MCP_SERVER_URL in .env
echo $env:MCP_SERVER_URL  # PowerShell

协议错误

症状：“协议版本无效”或“找不到方法”

解决方案:

✅ 确保您使用的是协议版本 2025-06-18
✅ 更新MCP SDK： pip install --upgrade mcp
✅ 检查服务器发送 "protocolVersion": "2025-06-18" 在初始化响应中

AWS基岩错误

症状：“未配置AWS凭据”

解决方案:

# Option 1: Set in .env file
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1

# Option 2: AWS CLI
aws configure

MCP检查器连接问题

症状：检查器显示“连接错误”

解决方案:

检查服务器URL: https://project-1-04.eduhk.hk/mcp/sse
连接类型：使用“直接”（非代理）
手动测试: curl -N -H "Accept: text/event-stream" https://project-1-04.eduhk.hk/mcp/sse
浏览器控制台：检查CORS或SSL错误

LangGraph演示错误

症状：演示无法启动

常见修复:

# 1. Check environment variables
cat .env

# 2. Test MCP connection independently
curl https://project-1-04.eduhk.hk/mcp/health

# 3. Verify AWS credentials
python test_01_aws_bedrock.py

# 4. Check Python dependencies
pip install -r requirements.txt --upgrade

______________________________________________________________________

📖 了解更多

官方资源

MCP规范: https://spec.modelcontextprotocol.io/
MCP GitHub: https://github.com/modelcontextprotocol
LangGraph文档: https://langchain-ai.github.io/langgraph/
朗史密斯: https://docs.smith.langchain.com/
MTR开放数据: https://data.gov.hk/en-data/dataset/mtr-data2-nexttrain-data

项目资源

GitHub存储库: https://github.com/enoch-sit/mtrmcp
MCP检查员: https://github.com/modelcontextprotocol/inspector
FastMCP: https://github.com/jlowin/fastmcp

______________________________________________________________________

🤝 贡献

这是一个学习MCP、FastAPI和LangGraph的教育项目。

贡献：

复刻仓库
创建要素分支
进行更改
使用MCP检查员进行测试
提交拉取请求

______________________________________________________________________

📝 许可证

MIT许可证（如适用）

______________________________________________________________________

🎉 总结

这个项目展示了什么

✅ 完整的MCP协议 -所有三个图元（工具、资源、提示）\ ✅ 生产部署 -NGINX+Docker+SSL/TLS\ ✅ 流式HTTP -最新MCP协议（2025-06-18）\ ✅ LangGraph集成 -具有记忆的AI代理\ ✅ 现实世界API -香港港铁实况数据\ ✅ 自然语言 -93个站点的模糊匹配\ ✅ 双接口 -人性化+机器可读\ ✅ 测试工具 -MCP检查员+完整的测试套件\ ✅ 可观测性 -LangSmith追踪\ ✅ 文档 -综合指南

快速命令

# Test production server
curl https://project-1-04.eduhk.hk/mcp/health

# Use MCP Inspector
npx @modelcontextprotocol/inspector

# Run LangGraph demo
python langgraph_demo_full_mcp.py

______________________________________________________________________

部署状态: ✅ 生产就绪\ 服务器URL: https://project-1-04.eduhk.hk/mcp/sse\ 最后更新：2025年10月24日\ 维护者：项目团队

Mtr MCP Example Fastapi

快速接入

详细介绍

MTR MCP服务器-完整文档

📑 目录

🎯 概述

包含内容

技术

🌐 生产部署

端点

建筑

部署功能

快速测试

🚀 快速开始

1.安装

2.环境设置

3.运行LangGraph演示

🧪 MCP检验员测试

GUI模式

命令行接口命令模式

🤖 LangGraph集成

建筑

记忆和多回合上下文

主要特点

💻 地方发展（可选）

启动本地服务器

本地端点

Docker部署

何时使用本地vs生产

📚 文档

核心文件

关键主题

🏗️ 建筑

系统组件

文件结构

✨ 主要特点

MCP功能（完整实施）

工具1： get_next_train_schedule （人性化）

工具2： get_next_train_structured （机器可读）

自然语言支持

支持的地铁线路

🐛 故障排除

连接错误

协议错误

AWS基岩错误

MCP检查器连接问题

LangGraph演示错误

📖 了解更多

官方资源

项目资源

🤝 贡献

📝 许可证

🎉 总结

这个项目展示了什么

快速命令

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

工具1： `get_next_train_schedule` （人性化）

工具2： `get_next_train_structured` （机器可读）