AI导哈

历史地点MCP客户端

一个基于Go的MCP客户端，用于与历史地点服务交互，支持MCP协议和HTTP API端点。

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

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

  3. 可用功能:

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

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许可证获得许可。

相关 MCP