🛡️ Guardian MCP-情境感知安全护送

使用谷歌地图、OpenWeather、YOLOv8和Moondream2 Vision AI的实时数据进行行人安全评估的生产级MCP系统。

______________________________________________________________________

🎯 它的作用

Guardian MCP通过以下方式提供智能行人安全评估：

路径分析：通过安全功能检测获取步行路线（小巷、照明不良、楼梯）
天气监测：实时天气状况和能见度
危险检测：混合人工智能视觉-YOLOv8用于物体+Moondream2用于环境条件
安全评分：具有透明推理的算法0-100安全评分

示例互动

👤 User: I'm at 40.7128, -74.0060. Take me to 40.7580, -73.9855. It's 10 PM.

🤖 Guardian Agent:
→ Calls get_walking_route() via Maps MCP
→ Calls get_weather() via Weather MCP
→ Calls evaluate_safety() via Safety MCP

🛡️ Safety Assessment:
Route: 3.2 km, 41 minutes walking
Weather: Clear, 68°F, visibility 10km
Route Features: ⚠️ Includes poorly lit areas
Time: Night (high risk period)

Safety Score: 62/100 (MODERATE RISK)
Recommendation: Proceed with caution. Stay alert in poorly lit areas.

______________________________________________________________________

📦 建筑

四台独立的MCP服务器

guardian-mcp-v2/
├── maps-mcp/           Google Maps Directions API
│   ├── index.js        Route fetching + safety feature detection
│   ├── package.json
│   └── Dockerfile
│
├── weather-mcp/        OpenWeather API
│   ├── index.js        Real-time weather conditions
│   ├── package.json
│   └── Dockerfile
│
├── vision-mcp/         Google Cloud Vision MCP (primary)
│   ├── index.js        MCP server (Node.js, Cloud Vision API)
│   ├── package.json
│   └── Dockerfile
│
├── local-vision-mcp/   Local YOLOv8 + Moondream2 Vision (optional)
│   ├── index.py                MCP server (Python)
│   ├── yolo_detector.py        Object detection 
│   ├── condition_analyzer.py   Environmental analysis 
│   ├── requirements.txt        Python dependencies
│   └── Dockerfile            
│
└── safety-mcp/         Algorithmic Safety Scoring
    ├── index.js        
    ├── package.json
    └── Dockerfile

技术栈

语言：JavaScript（地图、天气、安全、云视觉）+Python（本地视觉）
运行时：Node.js 20+（js服务+谷歌云视觉MCP）+Python 3.11（本地YOLO+Moondream MCP）
视觉AI:

- 云视觉：Google Cloud Vision API（标签检测）通过 vision-mcp/ - 本地视野（可选）：YOLOv8 Nano（Ultralytics）+Moondream2（vikhyatk） local-vision-mcp/

框架：@modelcontextprotocol/sdk v1.0.4（JS）+mcp v1.1.2（Python）
运输：stdio（通过stdin/stdout的JSON-RPC）
部署：Kubernetes中的Docker容器

______________________________________________________________________

🔑 先决条件

1.API密钥设置

谷歌地图方向API

首选 Google 云控制台
创建项目或选择现有项目
启用 “API指南”
首选凭证 → 创建凭据 → API密钥
复制密钥（格式： AIzaSyC-xxxxxxxxxxxxxxxxxxxxx)

OpenWeather API

首选开放天气
注册免费帐户
从仪表板获取API密钥
免费套餐：每天1000次通话

视觉AI选项

您可以使用以下任一方式运行Guardian 谷歌云愿景 （快速，管理，需要API密钥）或可选 当地YOLOv8+月亮梦2 堆叠（100%局部，较重）。

A） Google Cloud Vision API（默认 `vision-mcp/`)

需要一个谷歌云项目+ 愿景API 启用
用途 GOOGLE_CLOUD_VISION_API_KEY
有一个慷慨的免费等级（见愿景定价)

B）本地视野（YOLOv8+Moondream2）-100%免费！

不需要外部API。 模型自动下载：

YOLOv8纳米 （~6MB）-在构建过程中预下载
月亮梦2 （~1.6GB）-第一个容器启动时下载

应用的优化：

仅使用CPU的PyTorch（与完整版相比节省约1.5GB）
在构建过程中积极清理缓存
延迟加载：Moondream2在运行时下载（不是构建时）
基础图像大小：1.65GB （最终运行时间：首次启动后约3.2GB）
构建时间：约5分钟（预下载时为20+分钟）

没有API密钥，没有外部服务，完全在容器中本地运行。

2.硬件要求（本地视觉MCP）

本地视觉MCP (local-vision-mcp/YOLOv8+Moondream2，针对CPU推理进行了优化）：

随机存取存储器：最低4GB，建议6GB（用于Moondream2推理）
存储：总共3.5GB（1.65GB图像+1.6GB模型下载+开销）
中央处理器：建议使用2个以上内核（每张图像的推断时间约为300-800ms）
备注：仅在CPU上运行，不需要GPU！
首次启动：Moondream2自动下载（约2分钟）

其他MCP是轻量级的（每个小于200MB RAM）。

3.Archestra平台

# Pull and run Archestra
docker pull archestra/platform:latest
docker run -d -p 3000:3000 --name archestra archestra/platform:latest

# Access UI
open http://localhost:3000

______________________________________________________________________

🚀 安装和部署

第一步：构建Docker镜像

cd /home/azad/Desktop/Hackathon/guardian-mcp-v2

# Build all 4 images
./build-images.sh

预期产量：

✅ Maps MCP built: guardian-maps-mcp:latest
✅ Weather MCP built: guardian-weather-mcp:latest
✅ Vision MCP built: guardian-vision-mcp:latest
✅ Safety MCP built: guardian-safety-mcp:latest

步骤2：将映像加载到Archestra的Kubernetes集群中

cd /home/azad/Desktop/Hackathon/guardian-mcp-v2

# load all 4 images to cluster
./build-images.sh

重要提示： Archestra在其Docker容器中运行一个嵌入式Kubernetes（KinD）集群。您需要将自定义图像加载到此集群中。

# Find Archestra container name
docker ps --filter "ancestor=archestra/platform" --format "{{.Names}}"
# Output: vigilant_payne (or similar)

# Load all 4 images (replace 'vigilant_payne' with your container name)
docker exec vigilant_payne kind load docker-image guardian-maps-mcp:latest --name archestra-mcp
docker exec vigilant_payne kind load docker-image guardian-weather-mcp:latest --name archestra-mcp
docker exec vigilant_payne kind load docker-image guardian-vision-mcp:latest --name archestra-mcp
docker exec vigilant_payne kind load docker-image guardian-safety-mcp:latest --name archestra-mcp

每个项目的预期产出：

Image: "guardian-maps-mcp:latest" with ID "sha256:..." not yet present on node "archestra-mcp-control-plane", loading...

步骤3：在Archestra UI中配置MCP服务器

开放Archestra http://localhost:3000
导航到 MCP注册表 或 私人MCP注册表
点击 “添加MCP服务器” （或类似按钮）
填写表格4次（每台服务器一次）：

______________________________________________________________________

服务器1:守护者地图MCP

Display Name: Guardian Maps MCP
Docker Image: guardian-maps-mcp:latest
Command: (leave empty - uses default CMD from Dockerfile)
Arguments: (leave empty)
Transport Type: stdio
Environment Variables:
  - Key: GOOGLE_MAPS_API_KEY
    Value: [Paste your Google Maps API key here]

______________________________________________________________________

服务器2:守护者气象MCP

Display Name: Guardian Weather MCP
Docker Image: guardian-weather-mcp:latest
Command: (leave empty)
Arguments: (leave empty)
Transport Type: stdio
Environment Variables:
  - Key: OPENWEATHER_API_KEY
    Value: [Paste your OpenWeather API key here]

______________________________________________________________________

服务器3:Guardian Vision MCP（谷歌云视觉）

Display Name: Guardian Vision MCP
Docker Image: guardian-vision-mcp:latest
Command: (leave empty)
Arguments: (leave empty)
Transport Type: stdio
Environment Variables:
  - Key: GOOGLE_CLOUD_VISION_API_KEY
    Value: [Paste your Google Cloud Vision API key here]

💡 Note: This MCP uses Google Cloud Vision's LABEL_DETECTION under the hood. Fast, managed, and benefits from Google's infra. Local YOLO+Moondream2 Vision is available separately via the `local-vision-mcp/` directory if you want a 100% offline option.

______________________________________________________________________

服务器4:守护者安全MCP

Display Name: Guardian Safety MCP
Docker Image: guardian-safety-mcp:latest
Command: (leave empty)
Arguments: (leave empty)
Transport Type: stdio
Environment Variables: (none - this server is purely algorithmic)

______________________________________________________________________

步骤4：创建网关和代理

创建网关 （将MCP工具组合在一起）：

- 首选网关部分 - 点击 “创建网关” - 姓名： Guardian Gateway - 将所有4台MCP服务器添加到此网关

创建代理 （使用工具的LLM）：

- 首选代理部分 - 点击 “创建代理” - 姓名： Guardian Escort Agent - 分配 Guardian Gateway 致该代理人 - 添加系统提示（见下文）

______________________________________________________________________

📝 监护人代理系统提示

将此复制到代理的系统提示符中：

You are Guardian, a safety escort intelligence system that helps pedestrians assess route safety.

# YOUR WORKFLOW
1. When user provides origin and destination coordinates, call get_walking_route
2. Call get_weather with the origin coordinates to get current conditions
3. If user provides a street photo (URL or base64):
   a. Call detect_objects to find physical hazards (vehicles, obstacles, construction)
   b. Call analyze_conditions to assess environmental factors (lighting, weather visibility)
4. ALWAYS call evaluate_safety with all collected data
5. Present a clear safety assessment to the user

# VISION TOOLS (Two-Part Analysis)
- **detect_objects**: Uses YOLOv8 to detect concrete objects (cars, people, barriers, obstacles)
- **analyze_conditions**: Uses Moondream2 to assess abstract conditions (lighting, wet surfaces, fog)
- Use BOTH tools when analyzing an image for complete hazard detection

# TIME OF DAY MAPPING
- 6am-11am: "morning"
- 12pm-5pm: "afternoon"
- 6pm-8pm: "evening"
- 9pm-5am: "night"

# SAFETY SCORING
The evaluate_safety tool returns a score from 0-100:
- 80-100: LOW RISK - Safe to proceed
- 60-79: MODERATE RISK - Proceed with caution
- 40-59: HIGH RISK - Consider alternative route
- 0-39: CRITICAL RISK - Strongly recommend reroute

# YOUR RULES
- Always trust the safety_score from the Safety MCP
- Explain the risk_breakdown clearly (hazards, weather, route, time penalties)
- Base your final recommendation on the Safety MCP output
- Be transparent about data sources (Maps, Weather, Vision APIs)
- Never make up safety information - only use tool results

______________________________________________________________________

🧪 测试

测试1：端到端路线评估

在Archestra聊天中，发送：

I'm at 40.7128, -74.0060
Take me to 40.7580, -73.9855
Current time: 3 PM

预期代理行为：

✅ 呼叫 get_walking_route(40.7128, -74.0060, 40.7580, -73.9855)
✅ 呼叫 get_weather(40.7128, -74.0060)
✅ 呼叫 evaluate_safety() 所有数据
✅ 提供带分数和建议的安全评估

测试2：带有危险图像（URL或Base64）

I'm walking to work. Here's what the street looks like:
https://example.com/street-photo.jpg

预期代理行为：

✅ 呼叫 detect_objects("https://example.com/street-photo.jpg") -YOLOv8检测
✅ 呼叫 analyze_conditions("https://example.com/street-photo.jpg") -月亮梦2分析
✅ 结合两种工具的危害
✅ 将所有危险纳入安全评估

测试3：验证每个MCP工具

在Archestra中，检查工具是否可发现：

get_walking_route 来自Guardian Maps MCP
get_weather 卫报天气MCP
detect_objects 来自Guardian Vision MCP（YOLOv8）
analyze_conditions 来自守护者视觉MCP（Moondream2）
evaluate_safety 来自Guardian安全MCP

______________________________________________________________________

🔧 故障排除

问题：专用图像URL的视觉MCP-403

问题： 图像URL需要授权（私有/签名URL），Vision MCP得到403。

解决方案： 以base64格式传递图像（首选私有URL）或提供请求标头。

首选（base64）：

{
  "image_base64": "data:image/png;base64,iVBORw0KGgo..."
}

备选方案（URL+标头）：

{
  "image_url": "https://example.com/private.png",
  "image_headers": {
    "Authorization": "Bearer "
  }
}

📊 安全评分算法

安全MCP使用此透明公式：

Score = 100 - (HazardPenalty + WeatherPenalty + RoutePenalty + TimePenalty)

HazardPenalty:
- Critical hazard (fire, flood): -30 per hazard
- Major hazard (construction, dark): -15 per hazard
- Minor hazard (wet, debris): -5 per hazard

WeatherPenalty:
- Rain/Snow: -10
- Low visibility (15 m/s): -10

RoutePenalty:
- Includes alley: -10
- Poorly lit: -15
- Steep stairs: -5

TimePenalty:
- Night (9pm-5am): -15
- Evening (6pm-8pm): -5
- Morning/Afternoon: 0

______________________________________________________________________

🔮 未来范围

移动应用集成

Guardian MCP系统的设计考虑了未来的移动扩展：

📱 实时移动安全伴侣

实时摄像头危险检测：

流式电话摄像头馈送，用于连续危险分析
使用Google Cloud vision API进行实时计算机视觉处理
检测到的危险（施工区、潮湿表面、照明不良、障碍物）的即时警报

持续安全监测：

主动导航期间的背景位置跟踪
行走时动态安全评分更新
路线偏差检测，自动重新计算
关键安全下降时的紧急联系警报

智能后备系统：

网络损耗：使用设备上的TensorFlow Lite模型进行离线危险检测
GPS故障：最后已知的基于位置的推荐
API停机时间：缓存的路线数据和历史天气模式
电量不足：简化模式，功耗最小

主动安全建议：

“穿过马路，走到光线充足的那一边”
“前方施工——建议替代路径”
“天气恶化-考虑室内路线”
“高风险时段开始-保持警惕”

______________________________________________________________________

📚 其他资源

MCP SDK文档: https://github.com/modelcontextprotocol/sdk
Archestra平台文档: https://archestra.ai/docs
谷歌地图API: https://developers.google.com/maps/documentation/directions
OpenWeather API: https://openweathermap.org/api
谷歌云愿景: https://cloud.google.com/vision/docs

______________________________________________________________________

🎯 项目状态

Guardian MCP已实施 ✅
移动集成正在规划中

______________________________________________________________________

📄 许可证

MIT许可证-可在您的项目中自由使用

______________________________________________________________________

建于❤️ 行人安全

Guardian MCP V2

快速接入

详细介绍

🛡️ Guardian MCP-情境感知安全护送

🎯 它的作用

示例互动

📦 建筑

四台独立的MCP服务器

技术栈

🔑 先决条件

1.API密钥设置

谷歌地图方向API

OpenWeather API

视觉AI选项

A） Google Cloud Vision API（默认 vision-mcp/)

B） 本地视野（YOLOv8+Moondream2）-100%免费！

2.硬件要求（本地视觉MCP）

3.Archestra平台

🚀 安装和部署

第一步：构建Docker镜像

步骤2：将映像加载到Archestra的Kubernetes集群中

步骤3：在Archestra UI中配置MCP服务器

服务器1:守护者地图MCP

服务器2:守护者气象MCP

服务器3:Guardian Vision MCP（谷歌云视觉）

服务器4:守护者安全MCP

步骤4：创建网关和代理

📝 监护人代理系统提示

🧪 测试

测试1：端到端路线评估

测试2：带有危险图像（URL或Base64）

测试3：验证每个MCP工具

🔧 故障排除

问题：专用图像URL的视觉MCP-403

📊 安全评分算法

🔮 未来范围

移动应用集成

📱 实时移动安全伴侣

📚 其他资源

🎯 项目状态

📄 许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

A） Google Cloud Vision API（默认 `vision-mcp/`)

B）本地视野（YOLOv8+Moondream2）-100%免费！