SF Events MCP

SF Rec活动MCP

一个小型FastMCP服务器和自定义web小部件，用于浏览即将举办的旧金山娱乐和公园活动。Python服务公开了一个MCP工具(search_sf_events)通过HTTP，它提供了一个用React/TypeScript构建的可嵌入UI小部件。

特性

• HTTP MCP服务器 search_sf_events
• 按日期、类别、邻居、邻近度和自由文本进行事件过滤
• 可嵌入的结果UI（卡片+地图视图）编译为单个小部件
• 简单的缓存层可减少API调用

快速入门

1） Python环境

• python -m venv .venv && source .venv/bin/activate
• python -m pip install -r requirements.txt

环境配置：

• 复制/编辑 env 并设置 APPTOKEN 如果你有自己的Socrata应用代币。回购中存在开发令牌 env 文件，默认使用。

2） 构建web小部件

• cd web
• npm ci （或 npm install)
• npm run build （输出 web/dist/component.js 和可选CSS）
• 可选开发循环： npm run watch

注意：地图视图使用Mapbox GL。公共开发令牌嵌入在 web/src/MapView.tsx。对于生产，请用您自己的令牌替换它。

3） 运行MCP服务器（HTTP）

从存储库根目录（在构建小部件之后）：

• python -m uvicorn src.instacart_chatgpt.services.fastmcp_rec_events:app --reload --host 127.0.0.1 --port 8000

MCP端点位于 http://127.0.0.1:8000/mcp.

工具与资源

• 工具： search_sf_events --带筛选器的主搜索端点：

- 论点包括 limit，日期范围字段(start_date_from, start_date_to, end_date_from, end_date_to)，位置(latitude, longitude, radius_km), category, neighborhood, search, relative_date，以及 use_cache.

• 资源： ui://widget/sf-events.html --提供已编译的小部件标记；在工具结果可用时自动嵌入。

有关确切的行为和返回的结构，请参阅：

• 服务器： src/instacart_chatgpt/services/fastmcp_rec_events.py
• 模型： src/instacart_chatgpt/services/events/models.py
• 过滤器： src/instacart_chatgpt/services/events/filtering.py

项目结构

• src/instacart_chatgpt/services/fastmcp_rec_events.py --MCP服务器（ASGI应用程序）和工具
• src/instacart_chatgpt/services/events/ --数据模型、过滤和配置
• web/ --React/TypeScript小部件（与esbuild捆绑在一起） web/dist)
• requirements.txt --Python deps（FastMCP、Uvicorn、httpx等）