______________________________________________________________________
标题：冲浪点查找器——基于人工智能的MCP代理 表情符号🏄♂️ 颜色来源：蓝色 颜色To：靛蓝色 sdk：毕业 sdk版本：5.49.1 应用文件：hf_space/app.py 固定：false 许可证：mit 标签：
- mcp在行动中跟踪客户
- 构建mcp跟踪消费者
short_description：使用MCP协议进行自主推理的AI冲浪代理
______________________________________________________________________
🏄♂️ 冲浪点查找器-AI代理（MCP在行动）
基于人工智能的冲浪点推荐，具有自主推理和实时条件
该项目展示了 MCP在行动 智能代理能够自主分析冲浪条件、最佳地点的原因，并为其决策过程提供自然语言解释。
🎬 演示和社交
   
👤 团队
- 拥抱的脸： @D3MI4N
🤖 代理能力
- 🧠 自主推理：AI代理分析波浪条件并提出智能建议
- 🌊 实时条件：Stormglass API的活波数据
- 📍 位置智能：地理编码和基于距离的过滤
- 🎯 多因素评分：复杂的评估（波浪、风、涌浪、技能兼容性）
- 💬 自然语言：LLM驱动的解释和见解
- 🛡️ 注重安全：技能水平适当的建议
🔧 MCP资源实施
冲浪点暴露在外 MCP资源 遵循模型上下文协议。
资源
- 统一资源标识符:
surf://spots/database - 内容：22个带有元数据的世界级冲浪点
- 格式：JSON
服务器实现(mcp_server/mcp_server.py)
@server.list_resources()
async def list_resources():
return [Resource(uri="surf://spots/database", name="Surf Spots Database", ...)]
@server.read_resource()
async def read_resource(uri: str):
# Returns surf_spots.json content客户端使用情况(tools/spot_finder_tool.py)
- 主要的，重要的：通过read_resource（）访问MCP资源
- 后备方案：文件I/O用于异步上下文兼容性
测试MCP资源
python tests/test_mcp_resources.py
# Expected output:
# ✅ Found 1 resource(s)
# ✅ Loaded 22 surf spots
# 🎉 All tests passed!🏗️ MCP架构
MCP服务器(mcp_server/)
可用工具：
find_surf_spots-具有AI推理的主编排工具surf_llm_agent-LLM驱动的分析和解释get_wave_data-Stormglass的实时条件resolve_location-地理编码和坐标分辨率calculate_distance-距离计算
HF空间消费者(hf_space/)
- Gradio界面：用户友好的web UI
- MCP客户端：与MCP服务器通信
- 实时演示：实时冲浪推荐
🚀 快速开始
本地开发
# Clone repository
git clone
cd surf-spot-finder-mcp
# Install dependencies
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
# Set API keys (optional - works with fallback)
export STORMGLASS_API_KEY=your_key
export OPENAI_API_KEY=your_key # For enhanced LLM reasoning
# Quick demo
python scripts/run_local_demo.py🌊 运作原理
- 用户输入：地点+偏好（技能水平、棋盘类型）
- 位置分辨率：将地址转换为坐标
- 现场发现：从精心策划的数据库中查找附近的冲浪点
- 条件分析：通过Stormglass获取实时波浪数据
- AI评估：复杂的评分算法+LLM推理
- 智能排名：按与用户偏好的兼容性排序
- 自然语言输出：人工智能生成的解释和见解
📊 评估算法
实时数据源（自动优先级）：
- 🥇 风暴级API → 🥈 开放天气 （自由回退）
- 🥇 OpenAI → 🥈 Anthropic → 🥉 开放路由 → 🔄 基于规则
多因素评分系统（0-100分）：
- 波浪条件（35%）:
- 最佳范围匹配（地点偏好与当前高度） - 技能水平安全调整（初学者限制在2米以内） - 收益递减的累进评分曲线
- 风力分析（25%）:
- 速度兼容性（首选海上，惩罚陆上） - 方向优化（侧向离岸=理想） - 热风模式识别
- 膨胀方向（25%）:
- 与斑点最佳膨胀窗口的角度匹配 - 波浪折射的测深考虑 - 季节性涌浪模式分析
- 技能兼容性（15%）:
- 休息类型与经验水平 - 危险评估（岩石、水流、人群） - 进步机会评分
AI推理层：
- 跨多种条件的自主模式识别
- 决策过程的自然语言解释
- 当地知识整合和安全建议
- 利用天气预报优化会话时间
🗺️ 冲浪点数据库
演示数据集（当前实现）
22个世界级景点 精心挑选用于演示：
🇪🇸 西班牙 （8点）
- 塔里法、埃尔帕尔马、拉巴罗萨、索托格兰德、巴尔巴特、特拉法尔加角、马贝拉、蒙达卡
🇺🇸 美国加州 （4个点）
- 马里布-冲浪者海滩、威尼斯海滩、曼哈顿海滩、雷东多海滩
🇵🇹 葡萄牙 （4个点）
- 埃里塞拉 - Ribeira d'Islas， Carcavelos， Guincho， Peniche - 超级管
🌍 国际的 （6点）
- Hossegor（法国）、Pipeline（夏威夷）、Bells Beach（澳大利亚）、Supertubes（南非）
生产规模架构
当前：JSON文件 (mcp_server/data/surf_spots.json)
- ✅ 非常适合演示和开发
- ✅ 易于理解和修改
- ✅ 无外部依赖关系
生产部署选项：
- PostgreSQL/PostGIS：地理空间查询和高级过滤
- MongoDB：灵活的模式，用于演变斑点特征
- Redis缓存：通过地理索引快速查找
- API集成：来自冲浪数据库的实时现场数据
可扩展性路径：
JSON (22 spots) → Database (1000s spots) → API Federation (global coverage)当前的JSON方法演示了 算法与体系结构 同时保留演示 可访问和可维护 用于黑客马拉松评估。
🧪 测试
运行测试
# Test MCP resources
python tests/test_mcp_resources.py
# Test complete workflow
python tests/test_workflow.py
# Run unit tests (if pytest installed)
cd mcp_server
pytest tests/测试依赖关系
该项目包括以下方面的综合测试：
- MCP资源：资源列表和阅读
- MCP工具：单个工具功能
- LLM集成：AI推理组件
- API集成：外部服务连接
🔧 配置
API密钥（所有可选-包括智能回退）：
波浪数据源：
STORMGLASS_API_KEY：优质海洋数据→ 回到Open Meteo（免费）
AI推理提供者（优先级顺序）：
OPENAI_API_KEY：GPT-4分析（第一选择）ANTHROPIC_API_KEY：克劳德推理（第二选择）OPENROUTER_API_KEY：多模式访问（第三选择）- *没有API密钥*：基于规则的分析（始终有效）
🎯 MCP黑客马拉松提交
轨道：MCP在行动-客户\ 类别：演示自主AI代理行为
评判的关键特征：
- ✅ Agent推理：LLM驱动的自主决策
- ✅ 现实世界影响：以安全为重点的实用冲浪建议
- ✅ MCP协议：适当的资源和工具架构
- ✅ 用户体验：直观的Gradio界面
- ✅ 文档：全面的设置和使用文档
🏆 创新亮点
- 自主代理行为：人工智能对条件进行推理并解释决策
- 多模式智能：结合实时数据、空间分析和LLM推理
- MCP资源：正确实现模型上下文协议原语
- 安全第一方针：技能水平适当的建议可防止危险情况
- 灵活的体系结构：直接模式，智能回退，可靠性高
📁 项目结构
surf-spot-finder-mcp/
├── mcp_server/ # MCP Server Implementation
│ ├── mcp_server.py # MCP resource handlers (list_resources, read_resource)
│ ├── tools/ # MCP Tools
│ │ ├── spot_finder_tool.py # Main orchestration (uses MCP resources)
│ │ ├── llm_agent_tool.py # AI reasoning & analysis
│ │ ├── surf_eval_tool.py # Multi-factor scoring algorithm
│ │ ├── stormglass_tool.py # Wave data API integration
│ │ ├── location_tool.py # Geocoding & coordinates
│ │ └── marine_data_tool.py # Fallback weather data
│ ├── data/ # Surf spots database
│ │ └── surf_spots.json # 22 world-class surf spots (exposed via MCP)
│ ├── utils/ # Utility functions
│ └── tests/ # Unit & integration tests
│
├── hf_space/ # Gradio UI
│ ├── app.py # Main interface with enhanced UX
│ ├── mcp_client.py # Direct Mode client
│ └── requirements.txt # HF Space dependencies
│
├── scripts/ # Utility scripts
│ ├── run_local_demo.py # Quick demo launcher
│ └── print_tree.py # Repository structure visualization
│
├── tests/ # Root-level integration tests
│ ├── test_mcp_resources.py # MCP resources validation
│ └── test_workflow.py # End-to-end workflow testing
│
├── requirements.txt # Project dependencies
└── README.md # This documentation🤝 贡献
专为拥抱脸MCP黑客马拉松而打造。欢迎投稿！
📄 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
🏄♂️ 用AI智能找到你的完美波浪！
🔮 未来的增强功能
- 模态无服务器部署：计划进行生产规模部署
- 全球现货数据库：与冲浪数据库集成，覆盖全球
- 预测集成：多日天气预报和会议规划
- 社区特征：用户评分、照片和本地提示