谷歌搜索服务

Elos谷歌搜索MCP服务器

模型上下文协议（MCP）服务器，使用FastMCP和Google自定义搜索API提供Google搜索功能。

特性

• 谷歌搜索：使用Google Custom Search API执行web搜索
• 图像搜索：使用谷歌图片搜索搜索图片
• 网页搜索：专门的网络搜索功能
• 健康监测：内置健康检查和状态监测
• 灵活的身份验证：支持API密钥和服务帐户
• FastMCP集成：基于FastMCP框架构建，实现最佳性能

先决条件

Google API设置

1. 谷歌云项目：在中创建项目 谷歌云控制台
2. 启用API：启用以下API：
   • 自定义搜索API
   • 自定义搜索引擎API
3. 创建自定义搜索引擎:
   • 首选 谷歌可编程搜索引擎
   • 创建新的搜索引擎
   • 注意搜索引擎ID（cx）
4. API密钥或服务帐户:
   • 选项A：在Google云控制台中创建API密钥
   • 选项B：创建服务帐户并下载JSON凭据

当地发展要求

• Python 3.9+
• Docker/Podman
• 访问quay.io注册表

安装

地方发展

1. 克隆存储库:

   复制

   git clone <repository-url>
   cd elos-mcp-google-search
   

2. 安装依赖项:

   复制

   pip install -e .
   

3. 设置环境变量:

   复制

   export GOOGLE_API_KEY="your-api-key"
   export GOOGLE_CSE_ID="your-search-engine-id"
   # OR for service account:
   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
   

4. 运行服务器:

   复制

   python -m elos_google_search_mcp.server
   

Docker构建

1. 塑造形象:

   复制

   podman build -t elos-google-search-mcp:latest .
   

2. 本地测试:

   复制

   podman run -p 8000:8000 \
     -e GOOGLE_API_KEY="your-api-key" \
     -e GOOGLE_CSE_ID="your-search-engine-id" \
     elos-google-search-mcp:latest
   

部署

推送到Quay.io

1. 登录Quay.io:

   复制

   podman login quay.io
   

2. 标记图像:

   复制

   podman tag elos-google-search-mcp:latest quay.io/elostech/elos-mcp-google-search:latest
   

3. 推送图像:

   复制

   podman push quay.io/elostech/elos-mcp-google-search:latest
   

Kubernetes部署

1. 更新秘密 使用您的实际凭据：

   复制

   # Edit kubernetes/elos-google-search-secret.yaml
   # Replace placeholder values with actual credentials
   

2. 应用配置:

   复制

   kubectl apply -k kubernetes/
   

3. 验证部署:

   复制

   kubectl get pods -l app=elos-google-search-mcp
   kubectl get services -l app=elos-google-search-mcp
   

配置

环境变量

Kubernetes的秘密

该部署使用Kubernetes secrets来存储敏感信息：

• google-api-key：您的Google API密钥
• google-cse-id：您的自定义搜索引擎ID
• google-credentials：服务帐户JSON（如果使用服务帐户身份验证）

API终点

MCP服务器提供以下工具：

google_search(query, num_results)

进行一般的谷歌搜索。

参数：

• query （str）：搜索查询字符串
• num_results （int）：结果数量（最多10个）

退货： 包含标题、链接和片段的搜索结果列表

google_search_web(query, num_results)

执行特定于网络的搜索。

参数：

• query （str）：搜索查询字符串
• num_results （int）：结果数量（最多5个）

退货： 网络搜索结果列表

google_search_images(query, num_results)

搜索图像。

参数：

• query （str）：搜索查询字符串
• num_results （int）：结果数量（最多5个）

退货： 图片搜索结果列表

get_search_health()

检查服务器运行状况和配置。

退货： 健康状态和配置信息

使用示例

基本搜索

from elos_google_search_mcp.server import google_search

results = google_search("OpenAI GPT-4", num_results=5)
for result in results:
    print(f"Title: {result['title']}")
    print(f"Link: {result['link']}")
    print(f"Snippet: {result['snippet']}")
    print("---")

健康检查

from elos_google_search_mcp.server import get_search_health

health = get_search_health()
print(f"Status: {health['status']}")
print(f"Credentials Available: {health['credentials_available']}")

故障排除

常见问题

1. “没有可用的Google凭据”

   • 确保环境变量设置正确
   • 检查API密钥或服务帐户文件是否有效

2. “GOOGLE_CSE_ID环境变量未设置”

   • 设置 GOOGLE_CSE_ID 环境变量
   • 验证自定义搜索引擎ID是否正确

3. 超过API配额

   • 检查您的Google Cloud控制台是否有配额限制
   • 考虑升级API计划

4. 身份验证错误

   • 验证API密钥权限
   • 检查服务帐户角色和权限

调试模式

通过设置日志级别启用调试日志记录：

import logging
logging.basicConfig(level=logging.DEBUG)

发展

项目结构

elos-mcp-google-search/
├── elos_google_search_mcp/
│   ├── __init__.py
│   └── server.py
├── kubernetes/
│   ├── elos-google-search-deployment.yaml
│   ├── elos-google-search-secret.yaml
│   └── kustomization.yaml
├── Containerfile
├── pyproject.toml
└── README.md

添加新工具

要添加新的搜索工具，请使用 @mcp.tool() 装饰师：

@mcp.tool()
def new_search_function(query: str) -> Dict[str, Any]:
    """Description of the new tool."""
    # Implementation here
    return {"result": "data"}

测试

在本地运行测试：

pytest tests/

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

有关支持和问题：

• 在GitHub存储库中创建问题
• 联系Elos技术团队

更新日志

v0.1.0

• 初始版本
• 谷歌搜索功能
• 图像搜索支持
• 健康监测
• Kubernetes部署支持