Historical Places MCP Client

历史地点MCP客户端

用于历史地点服务的全面的基于Go的MCP（模型上下文协议）客户端。该客户端实现MCP规范，并提供MCP服务器功能和HTTP API端点，用于与历史场所服务交互。

特性

• MCP协议实现：完全支持MCP 2024-11-05规范
• 双模式操作：作为MCP服务器或HTTP API服务器运行
• 多源综合：使用谷歌地图、Mapbox和OSM数据连接到历史地点服务
• 稳健的错误处理：优雅的降级和全面的错误报告
• 云就绪：针对本地开发和云部署进行了优化
• 结构化日志记录：具有可配置级别的JSON格式日志
• 健康检查：内置健康和准备端点
• Docker支持：多阶段构建，实现高效集装箱化

建筑

组件

• MCP服务器：实现用于AI模型集成的MCP协议
• HTTP客户端：与历史景点服务部门沟通
• 地点服务：业务逻辑和验证层
• HTTP句柄：用于直接HTTP访问的REST API终结点
• 模型：共享数据结构和响应格式

设计模式

• 整洁架构：明确界限的关注点分离
• 依赖注入：松散耦合的组件
• 基于界面的设计：可测试和可维护的代码
• 包装错误：上下文错误信息

API终点

MCP协议

客户端实现以下MCP方法：

• initialize：初始化MCP会话
• tools/list：列出可用工具
• tools/call：执行工具调用

可用工具

搜索历史地点

搜索给定位置附近的历史景点。

参数：

• latitude （必填）：纬度坐标（-90到90）
• longitude （必填）：经度坐标（-180至180）
• radius （可选）：搜索半径，单位为米（500-3000，默认值：1000）
• maxResults （可选）：返回的最大结果（1-50，默认值：10）
• keyword （可选）：搜索关键字（默认：“历史”）
• categories （可选）：要搜索的类别（默认：\[“历史”，“旅游”\]）

HTTP API终结点

在HTTP模式下运行时：

发布 /api/mcp-client/search

• 使用JSON请求体搜索历史地点

获取 /api/mcp-client/search

• 使用查询参数搜索： latitude, longitude, radius, maxResults

获取 /health

• 健康检查端点

获取 /ready

• 准备就绪检查端点

先决条件

• 转到1.22+
• Docker（用于容器化部署）
• 历史景点访问服务
• Google Cloud SDK（用于GCP部署）

配置

环境变量

# Historical Places service URL
export HISTORICAL_PLACES_BASE_URL=http://localhost:8080

# Log level (debug, info, warn, error)
export LOG_LEVEL=info

命令行选项

# Run as MCP server (default)
./main -mode=mcp

# Run as HTTP server
./main -mode=http -port=8081

# Set upstream service URL
./main -base-url=http://localhost:8080

# Set log level
./main -log-level=debug

发展

在当地建设

# Download dependencies
go mod download

# Build the application
go build -o main ./cmd/main.go

# Run in MCP mode
./main -mode=mcp

# Run in HTTP mode
./main -mode=http -port=8081

测试客户端

MCP模式测试

# Start MCP server
./main -mode=mcp

# Send MCP requests via stdin (example)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./main -mode=mcp

HTTP模式测试

# Start HTTP server
./main -mode=http -port=8081

# Health check
curl -X GET http://localhost:8081/health

# Search places
curl -X POST http://localhost:8081/api/mcp-client/search \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 41.4036,
    "longitude": 2.1744,
    "radius": 3000,
    "maxResults": 10,
    "keyword": "historical"
  }'

部署

本地Docker部署

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

特征：

• ARM64架构支持：针对M1 Mac进行了优化
• 双模式支持：部署为MCP服务器或HTTP API
• 全面验证：Docker安装、版本格式、端口验证
• 时间跟踪：监控构建和部署时间
• 容器管理：自动清理和重启策略
• 灵活的配置：上游URL和模式配置

使用示例：

# Build and deploy HTTP server
./deploy-local.sh --build --deploy --version v1.0.0 --mode http

# Deploy MCP server with custom upstream
./deploy-local.sh -bd -v latest -m mcp -u http://host.docker.internal:8080

# Deploy on custom port
./deploy-local.sh -bd -v latest -p 8082 -m http

选项：

• -v, --version VERSION：Docker镜像版本（默认：最新）
• -b, --build：在部署之前构建应用程序
• -d, --deploy：在本地部署容器
• -p, --port PORT：要公开的本地端口（默认值：8081）
• -m, --mode MODE：运行模式：“mcp”或“http”（默认：http）
• -u, --upstream URL：上游服务URL（默认值：http://localhost:8080)
• -h, --help：显示帮助消息

谷歌云平台部署

这 deploy-gcp.sh 该脚本允许部署到Google Cloud Run。

特征：

• 云运行部署：目标 europe-southwest1 区域
• GCR集成：推到 gcr.io 仓库
• 仅HTTP模式：云运行中不支持MCP模式
• 全面验证：gcloud身份验证、项目访问、所需API
• 自动缩放配置：0-10个实例，具有智能扩展功能
• 环境变量：上游服务URL配置
• 服务URL输出：直接链接到已部署的服务

使用示例：

# Build and deploy to GCP
./deploy-gcp.sh --build --deploy --version v1.0.0 --project my-gcp-project --upstream https://my-service.run.app

# Deploy existing image
./deploy-gcp.sh -d -v latest -p my-project -u https://historical-places.run.app

选项：

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

GCP部署的先决条件：

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

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

脚本功能

这两个部署脚本都包括：

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

MCP集成

使用AI模型

MCP客户端可以与支持MCP协议的AI模型集成：

1. 启动MCP服务器:

   ./main -mode=mcp -base-url=http://your-historical-places-service

1. 配置您的AI模型 将MCP客户端用作工具提供者

1. 可用功能:

- 按地点搜索历史景点 - 获取详细的地点信息 - 多源数据聚合

MCP协议流

1. 初始化：AI模型初始化MCP会话
2. 列出工具：AI模型发现可用工具
3. 呼叫工具：AI模型执行搜索操作
4. 结果：返回格式化的历史地点数据

错误处理

• 服务弹性：妥善处理上游服务故障
• 输入验证：全面的参数验证
• 详细日志记录：用于调试和监控的结构化日志
• 错误传播：保留上下文错误信息

性能注意事项

• HTTP客户端池：高效的连接重用
• 超时管理：可配置的请求超时
• 内存优化：高效的数据结构
• 并发安全：线程安全操作

贡献

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

故障排除

构建问题

未使用的导入错误

如果你遇到这样的错误 "fmt" imported and not used 在构建过程中：

# Remove unused imports from the code
# The fmt package import should be removed from cmd/main.go if not used

缺少的依赖

如果由于缺少依赖项而导致构建失败：

# Download all required dependencies
go mod download

# Verify go.mod and go.sum are present
go mod tidy

运行时问题

连接被拒绝

如果客户端无法连接到历史地点服务：

1. 验证上游服务是否正在运行
2. 检查基本URL配置：

   # Set correct upstream URL
   export HISTORICAL_PLACES_BASE_URL=http://your-service:8080
   ./main -mode=http

端口已在使用中

如果HTTP服务器因端口冲突而无法启动：

# Use a different port
./main -mode=http -port=8082

权限不足

如果您遇到权限错误：

# Make the binary executable
chmod +x main

快速启动命令

# Complete setup and run
go mod download
go build -o main ./cmd/main.go
./main -mode=http -port=8081

# Test the service
curl http://localhost:8081/health

许可证

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