金大哥 - tomtom-mcp MCP 详情

article

README

🚀 TomTom MCP Server

TomTom MCP Server 简化了地理空间开发，它提供了对 TomTom 定位服务的无缝访问，这些服务包括搜索、路线规划、交通信息和静态地图数据。该服务器能够轻松地将精确的地理位置数据集成到 AI 工作流程和开发环境中。

🚀 快速开始

前提条件

Node.js 22+
TomTom API 密钥

如何获取 TomTom API 密钥：

在 TomTom 开发者门户创建一个开发者账户。
点击左侧菜单中的 API & SDK Keys。
点击 红色的 Create Key 按钮。
选择所有可用的 API 以确保拥有完全访问权限，为你的密钥命名，然后点击 Create。

更多详细信息，请访问 TomTom API 密钥管理文档。

安装

npm install @tomtom-org/tomtom-mcp@latest

# 或者不安装直接运行
npx @tomtom-org/tomtom-mcp@latest

配置

使用以下方法之一设置你的 TomTom API 密钥：

# 选项 1：使用 .env 文件（推荐）
echo "TOMTOM_API_KEY=your_api_key" > .env

# 选项 2：环境变量
export TOMTOM_API_KEY=your_api_key

# 选项 3：作为 CLI 参数传递
npx @tomtom-org/tomtom-mcp@latest --key your_api_key

使用

# 启动 MCP 服务器
npx @tomtom-org/tomtom-mcp@latest
# 获取帮助
npx @tomtom-org/tomtom-mcp@latest --help

✨ 主要特性

TomTom MCP Server 可轻松集成到各种 AI 开发环境和工具中，为地理空间开发提供便利。

📦 安装指南

安装命令

npm install @tomtom-org/tomtom-mcp@latest

# 或者不安装直接运行
npx @tomtom-org/tomtom-mcp@latest

💻 使用示例

基础用法

# 启动 MCP 服务器
npx @tomtom-org/tomtom-mcp@latest
# 获取帮助
npx @tomtom-org/tomtom-mcp@latest --help

📚 详细文档

集成指南

TomTom MCP Server 可以轻松集成到各种 AI 开发环境和工具中。

以下指南帮助你将 MCP 服务器与你的工具和环境进行集成：

Claude Desktop 设置 - 配置 Claude Desktop 以与 TomTom MCP 服务器配合使用的说明。
VS Code 设置 - 在 Visual Studio Code 中设置开发环境。
Cursor AI 集成 - 将 TomTom MCP 服务器与 Cursor AI 集成的指南。
WinSurf 集成 - 配置 WindSurf 以使用 TomTom MCP 服务器的说明。
Smolagents 集成 - 展示如何将 Smolagents AI 代理连接到 TomTom MCP 服务器的示例。

可用工具

| 属性 | 详情 | |------|------| | tomtom-geocode | 将地址转换为坐标，覆盖全球范围 | | tomtom-reverse-geocode | 根据 GPS 坐标获取地址 | | tomtom-fuzzy-search | 支持容错的智能搜索 | | tomtom-poi-search | 查找特定的商业类别 | | tomtom-nearby | 发现指定半径内的服务 | | tomtom-routing | 计算地点之间的最佳路线 | | tomtom-waypoint-routing | 多站点路线规划路由 API | | tomtom-reachable-range | 根据时间/距离确定覆盖区域 | | tomtom-traffic | 实时事件数据 | | tomtom-static-map | 生成自定义地图图像 |

各工具的详细文档请参考： | 工具 | 文档链接 | |------|---------------| | tomtom-geocode | https://developer.tomtom.com/geocoding-api/documentation/geocode | | tomtom-reverse-geocode | https://developer.tomtom.com/reverse-geocoding-api/documentation/reverse-geocode | | tomtom-fuzzy-search | https://developer.tomtom.com/search-api/documentation/search-service/fuzzy-search | | tomtom-poi-search | https://developer.tomtom.com/search-api/documentation/search-service/points-of-interest-search | | tomtom-nearby | https://developer.tomtom.com/search-api/documentation/search-service/nearby-search | | tomtom-routing | https://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route | | tomtom-waypoint-routing | https://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route | | tomtom-reachable-range | https://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-reachable-range | | tomtom-traffic | https://developer.tomtom.com/traffic-api/documentation/traffic-incidents/traffic-incidents-service | | tomtom-static-map | https://developer.tomtom.com/map-display-api/documentation/raster/static-image |

本地开发与贡献

本地开发设置

git clone <repository>

cd tomtom-mcp

npm install

cp .env.example .env      # 在 .env 中添加你的 API 密钥

npm run build             # 构建 TypeScript 文件

node ./bin/tomtom-mcp.js   # 启动 MCP 服务器

测试

npm run build               # 构建 TypeScript
npm test                    # 运行所有测试
npm run test:unit           # 仅运行单元测试
npm run test:comprehensive  # 运行集成测试

测试要求

⚠️ 重要提示

所有测试都需要在 .env 中设置有效的 API 密钥，因为它们会进行真实的 API 调用（非模拟），这将消耗你的 API 配额。

项目结构

src/
├── tools/             # MCP 工具定义
├── services/          # TomTom API 包装器
├── schemas/           # 验证模式
├── utils/             # 实用工具
└── createServer.ts    # MCP 服务器创建逻辑
└── index.ts           # 主入口点

故障排除

API 密钥问题

echo $TOMTOM_API_KEY  # 检查是否已设置

测试失败

ls -la .env          # 验证 .env 是否存在
cat .env             # 检查 API 密钥

构建问题

npm run build            # 重新构建
npm cache clean --force  # 清除缓存

贡献与反馈

我们欢迎对 TomTom MCP Server 进行贡献！请参阅 CONTRIBUTING.md 以了解如何提交拉取请求、报告问题和提出改进建议的详细信息。

所有贡献必须遵守我们的行为准则，并根据开发者原创证书 (DCO) 进行签名。

在 GitHub 仓库上提出问题。

安全

请参阅我们的安全策略以获取有关报告安全漏洞和我们的安全实践的信息。

📄 许可证

本项目采用 Apache 许可证 2.0 版 - 详情请参阅 LICENSE.md 文件。

tomtom-mcp