Historical Places MCP

历史名胜MCP

一个全面的基于Quarkus的MCP（模型上下文协议）服务，用于使用多个数据源（包括谷歌地图、Mapbox和OpenStreetMap API）发现历史地点。

特性

• 多源数据聚合：结合谷歌地图、Mapbox和OpenStreetMap的结果
• 智能重复数据删除：删除不同来源中的重复位置
• 基于距离的排序：结果按与搜索位置的接近程度排序
• 综合地点信息：评级、照片、开放时间、地址等
• RESTful API：不同用例的多个端点
• 使用Quarkus和Kotlin构建：高性能和低内存占用
• Docker支持：已准备好进行集装箱化部署
• 云就绪：针对Google Cloud Run部署进行了优化

建筑

服务

• 谷歌地图服务：从Google Maps places API获取历史地点和详细信息
• Mapbox服务：使用Mapbox Geocoding API搜索位置以获得更多覆盖范围
• OSMS服务：通过Overpass API查询OpenStreetMap以获取开源历史数据

客户

• 谷歌地图客户端：Google Maps Places API的REST客户端（附近搜索和地点详细信息）
• Mapbox客户端：Mapbox Places API的REST客户端

API终点

主搜索端点

发布 /api/historical-places/search

使用所有可用数据源搜索历史地点。

请求正文：

{
  "latitude": 41.4036,
  "longitude": 2.1744,
  "radius": 3000,
  "maxResults": 10,
  "keyword": "historical",
  "categories": ["historical", "tourist"]
}

答复：

{
  "success": true,
  "data": [
    {
      "id": "place_id_123",
      "name": "Sagrada Familia",
      "types": ["tourist_attraction", "place_of_worship"],
      "latitude": 41.4036,
      "longitude": 2.1744,
      "description": "Famous basilica designed by Antoni Gaudí",
      "address": "Carrer de Mallorca, 401, Barcelona",
      "rating": 4.7,
      "photos": [...],
      "openingHours": {...},
      "website": "https://sagradafamilia.org",
      "distance": 150.5,
      "source": "google_maps"
    }
  ],
  "error": null,
  "timestamp": 1763495605041
}

公用设施端点

获取 /api/historical-places/health

• 健康检查端点
• 返回服务状态

获取 /api/historical-places/test

• 简单测试终点
• 返回“控制器正在工作！”

获取 /api/historical-places/search-simple

• 使用查询参数进行简单搜索
• 参数： lat, lng, radius

先决条件

• Java 17+
• Docker（用于容器化部署）
• Google Cloud SDK（用于GCP部署）

配置

环境变量

# Required
export GOOGLE_MAPS_API_KEY=your_google_maps_api_key

# Optional
export MAPBOX_API_KEY=your_mapbox_api_key

应用程序属性

该服务是通过以下方式配置的 src/main/resources/application.properties:

# Server Configuration
quarkus.http.port=8080
quarkus.http.host=0.0.0.0

# API Configuration
google.maps.api.key=${GOOGLE_MAPS_API_KEY:}
mapbox.api.key=${MAPBOX_API_KEY:}

# REST Client URLs
quarkus.rest-client.google-maps-api.url=https://maps.googleapis.com/maps/api
quarkus.rest-client.mapbox-api.url=https://api.mapbox.com

# JSON Configuration
quarkus.jackson.fail-on-unknown-properties=false
quarkus.jackson.write-dates-as-timestamps=false

发展

本地运行

# Set environment variables
export GOOGLE_MAPS_API_KEY=your_api_key
export MAPBOX_API_KEY=your_mapbox_key

# Run in development mode
./gradlew quarkusDev

测试API

# Health check
curl -X GET http://localhost:8080/api/historical-places/health

# Search near Sagrada Familia
curl -X POST http://localhost:8080/api/historical-places/search \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 41.4036,
    "longitude": 2.1744,
    "radius": 3000,
    "maxResults": 10,
    "keyword": "historical",
    "categories": ["historical", "tourist"]
  }'

部署

本地Docker部署（M1架构）

这 deploy-local.sh 该脚本为M1 Mac提供了全面的本地部署，并支持Docker。

特征：

• M1架构支持：用途 --platform linux/arm64
• 全面验证：Docker安装、守护进程状态、版本格式、端口范围
• 时间跟踪：监控构建和部署时间
• 容器管理：自动清理和重启策略
• 环境变量：自动注入API密钥
• 健康检查：内置服务验证

使用示例：

# Build and deploy locally
./deploy-local.sh --build --deploy --version v1.0.0

# Deploy on custom port
./deploy-local.sh -bd -v latest -p 9090

# Build only
./deploy-local.sh --build --version v1.2.0

选项：

• -v, --version VERSION：Docker镜像版本（默认：最新）
• -b, --build：在部署之前构建应用程序
• -d, --deploy：在本地部署容器
• -p, --port PORT：要公开的本地端口（默认值：8080）
• -h, --help：显示帮助消息

谷歌云平台部署

这 deploy-gcp.sh 该脚本支持通过GCR集成无缝部署到Google Cloud Run。

特征：

• 云运行部署：目标 europe-southwest1 区域
• GCR集成：推到 gcr.io 仓库
• 全面验证：gcloud身份验证、项目访问、所需API
• 自动缩放配置：0-10个实例，具有智能扩展功能
• 环境变量：安全的API密钥注入
• 服务URL输出：直接链接到已部署的服务
• 时间跟踪：构建、推送和部署时间

使用示例：

# Build and deploy to GCP
./deploy-gcp.sh --build --deploy --version v1.0.0 --project my-gcp-project

# Deploy existing image
./deploy-gcp.sh -d -v latest -p my-project

# Build and push only
./deploy-gcp.sh --build --version v1.1.0 --project my-project

选项：

• -v, --version VERSION：Docker镜像版本（默认：最新）
• -p, --project PROJECT_ID：GCP项目ID（必填）
• -b, --build：构建图像并将其推送到GCR
• -d, --deploy：部署到云运行
• -h, --help：显示帮助消息

GCP部署的先决条件：

• 经过身份验证的gcloud CLI(gcloud auth login)
• 启用计费的有效GCP项目
• 启用所需的API（由脚本自动处理）：

- 云运行API - 容器注册表API

脚本功能

这两个部署脚本都包括：

1. 全面验证：工具可用性、身份验证、项目访问
2. 错误处理: set -euo pipefail 用于严格的错误处理
3. 彩色输出：带有颜色编码的信息、成功、警告和错误消息
4. 时间跟踪：单个操作和总执行时间
5. 环境变量：支持API密钥和配置
6. 帮助文档：详细的使用说明和示例
7. 灵活的选项：仅构建、仅部署或组合操作
8. 最佳实践：遵循shell脚本标准，并进行适当的错误处理

数据源

谷歌地图地点API

• 覆盖：全面的全球数据库
• 数据质量：高质量的商业数据，包括评级、照片、小时数
• 速率限制：基于API密钥配额
• 成本：按请求付费定价

地图框放置API

• 覆盖：具有本地见解的全球覆盖
• 数据质量：商业级位置数据
• 速率限制：基于订阅计划
• 成本：分层定价模型

OpenStreetMap（天桥API）

• 覆盖：社区驱动的全球数据库
• 数据质量：可变，非常适合历史遗迹
• 速率限制：合理使用政策
• 成本：免费和开源

响应格式

API的所有响应都遵循 MCPResponse 格式：

{
  "success": boolean,
  "data": T | null,
  "error": string | null,
  "timestamp": number
}

错误处理

• 服务弹性：单个服务失败不会破坏整个请求
• 故障弱化：返回可用服务的结果
• 详细日志记录：全面的错误跟踪和调试信息
• 输入验证：半径限制（500-3000m）和参数验证

性能注意事项

• 并发API调用：并行调用服务以获得最佳性能
• 结果重复数据删除：跨数据源的智能匹配
• 距离计算：用于精确距离排序的Haversine公式
• 内存优化：高效的数据结构和垃圾收集
• 缓存：考虑为生产部署实施Redis

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

该项目根据MIT许可证获得许可。

要移动：

本地部署脚本（deploy-Local.sh） M1架构支持：用途——平台linux/arm64

参数：版本、构建/部署标志、自定义端口

验证：Docker安装、守护进程状态、版本格式、端口范围

时间：跟踪构建和部署时间

功能：容器管理、环境变量、健康检查

使用示例：

在本地构建和部署

./deploy-local.sh--构建--部署--版本v1.0.0

在自定义端口上部署

./deploy-local.sh-bd-v最新版本-p 9090

复制 bash GCP部署脚本（部署GCP.sh） 云运行部署：目标欧洲-西南1地区

GCR集成：推送到GCR.io存储库

参数：版本、项目ID、构建/部署标志

验证：gcloud身份验证、项目访问、所需API、环境变量

时间：跟踪构建、推送和部署时间

功能：自动缩放、环境变量、服务URL输出

使用示例：

构建并部署到GCP

./deploy-gcp.sh--构建--部署--版本v1.0.0--投影我的gcp项目

部署现有映像

./deploy-gcp.sh-d-v latest-p我的项目

复制 bash 主要特点： 全面验证：工具可用性、身份验证、项目访问

错误处理：设置-euo pipeail以进行严格的错误处理

彩色输出：信息、成功、警告和错误消息

时间跟踪：个人和总执行时间

环境变量：支持API键

帮助文档：详细的使用说明

灵活的选项：仅构建、仅部署或组合操作

这两个脚本都遵循shell脚本最佳实践，具有适当的错误处理、输入验证和用户友好的输出。