Chatgpt MCP App

LocalHub-本地商业探索

一个集成了ChatGPT的应用程序，用于使用交互式谷歌地图发现当地企业。

特性

• ChatGPT内的交互式全屏地图显示
• 具有平滑60fps性能的平移和缩放功能
• 商业场所的标记放置系统
• 手机、平板电脑和台式机的响应式设计
• 使用重试机制处理错误
• 辅助功能（键盘导航、ARIA标签）

技术栈

• 前端框架： React 19+与TypeScript
• 构建工具： 维特
• 地图集成： 谷歌地图JavaScript API，通过@vis.gl/react-Google-Maps
• 造型： 顺风CSS 4.x
• 测试： Vitest与React测试库
• ChatGPT集成： 基于MCP协议的OpenAI Apps SDK

先决条件

• Node.js 18+和npm
• 谷歌地图API密钥(在这里买一个)

安装说明

1.安装依赖项

npm install

2.配置环境变量

创建一个 .env.local 项目根目录中的文件：

# Google Maps API Key
# Get your API key from: https://console.cloud.google.com/google/maps-apis/
VITE_GOOGLE_MAPS_API_KEY=your_actual_api_key_here

重要提示： 替换 your_actual_api_key_here 使用您的实际谷歌地图API密钥。

3.启用所需的谷歌地图API

在Google Cloud控制台中，启用以下API：

• 映射JavaScript API
• 放置API（用于未来的商业搜索功能）

4.运行开发服务器

npm run dev

该应用程序将在 http://localhost:3000

可用脚本

• npm run dev -使用热重新加载启动开发服务器
• npm run build -构建生产捆绑包
• npm run preview -在本地预览生产构建
• npm test -运行所有测试一次
• npm run test:watch -在监视模式下运行测试
• npm run test:ui -使用UI运行测试

项目结构

src/
├── components/
│   └── map/
│       ├── MapContainer.tsx      # Main map wrapper with API initialization
│       ├── MapView.tsx           # Google Maps rendering component
│       ├── Marker.tsx            # Individual marker component
│       ├── MapLoadingSkeleton.tsx # Loading state component
│       ├── MapError.tsx          # Error state component
│       └── *.test.tsx            # Component tests
├── lib/
│   ├── api/
│   │   └── maps.ts               # Google Maps API client
│   └── mcp/
│       └── displayHandler.ts     # ChatGPT MCP communication handler
├── types/
│   └── google-maps.d.ts          # TypeScript type definitions
├── test/
│   └── setup.ts                  # Test configuration
├── App.tsx                       # Root application component
├── main.tsx                      # Application entry point
└── index.css                     # Global styles

用法

基本地图显示

应用程序启动时，地图会自动以全屏模式加载。默认视图以旧金山为中心，缩放级别为12。

平移和缩放

• 潘： 单击并拖动地图
• 缩放： 使用鼠标滚轮、捏手势或缩放控件
• 键盘： 使用箭头键和+/-键进行导航

错误处理

如果地图加载失败：

1. 检查您的Google Maps API密钥是否在中正确配置 .env.local
2. 验证API密钥是否已在Google云控制台中启用
3. 单击“重试”按钮尝试重新加载
4. 检查浏览器控制台以获取详细的错误消息

ChatGPT集成

此应用程序旨在使用模型上下文协议（MCP）在ChatGPT的全屏显示模式下工作。

显示模式

地图以全屏模式呈现，底部可见ChatGPT系统编辑器覆盖层，允许用户在查看地图的同时继续进行对话交互。

未来能力（即将发布的规格）

• 通过对话提示搜索企业
• 通过聊天命令更新地图位置
• 显示搜索结果中的业务信息
• 密集结果集的标记聚类

测试

该项目包括全面的测试，包括：

• API配置和错误处理
• 映射组件生命周期和清理
• 标记渲染和更新
• 加载和错误状态
• 端到端集成场景

使用以下工具运行测试：

npm test

无障碍

• 语义HTML元素（主、节）
• 地图控件和交互元素的ARIA标签
• 键盘导航支持
• 足够的色彩对比度
• 触摸友好型控件（最小44x44px）
• 全屏模式转换的焦点管理

演出

• 目标：平移和缩放操作时为60fps
• 初始加载时间：4G连接时\<3秒
• Google Maps API加载缓慢
• 高效的标记更新，无需完全重新渲染
• 正确清理以防止内存泄漏

浏览器支持

• Chrome/Edge 90+
• 火狐88+
• Safari 14+
• 移动浏览器（iOS Safari、Android Chrome）

故障排除

地图未加载

1. 检查 .env.local 存在具有有效API密钥的文件
2. 验证API键是否已启用Maps JavaScript API
3. 检查浏览器控制台是否有特定的错误消息
4. 确保没有广告拦截器干扰谷歌地图

开发服务器问题

1. 清除node_modules并重新安装： rm -rf node_modules && npm install
2. 清除Vite缓存： rm -rf node_modules/.vite
3. 检查Node.js版本： node --version （应该是18+）

许可证

国际学生委员会

后续步骤

看 agent-os/specs/002-business-search-integration/ 即将推出的功能包括：

• 商业搜索功能
• 搜索结果显示标记
• 业务详细信息弹出窗口
• 与搜索API集成