AI导哈

本地商业发现工具

一个集成ChatGPT的应用程序，通过交互式Google地图发现本地商业。

  • by kleentekllc-cyber
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 kleentekllc-cyber/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

先决条件

安装说明

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集成

相关 MCP