Integrated Search MCP Server

集成搜索 MCP 服务

一个模型上下文协议（MCP）服务，集成了 Google Custom Search API 和 Redmine API，让 AI 助手能够无缝搜索网页并管理 Redmine 项目。

功能

Google Custom Search

• 网页搜索：使用 Google Custom Search API 搜索网页
• 图片搜索：通过高级筛选选项查找图片
• 高级参数：支持语言限制、站点专属搜索、文件类型筛选等

Redmine API 集成

• 问题管理：列出、创建、查看和更新 Redmine 问题，并进行详细分析
• 项目管理：浏览 Redmine 项目
• 高级筛选：按项目、状态、指派对象等筛选问题
• 全面详情：访问包括自定义字段在内的完整问题信息
• 批量操作：同时更新多个问题
• 问题评论：添加新的日志备注，并使用分页辅助功能列出现有评论
• 智能进度跟踪：更新问题进度、截止日期、预估工时和指派对象，并在工作流感知的错误处理中进行处理
• 详细更新报告：通过更新前后对比，显示哪些字段更新成功，哪些字段因 Redmine 限制而失败
• 工作流感知更新：智能处理 Redmine 工作流限制和字段权限

通用功能

• 错误处理：健壮的错误处理，并提供详细的错误消息
• 输入验证：使用 Zod 模式进行全面的输入验证
• 可配置：基于环境的配置
• 双 API 支持：在 Google Search 和 Redmine 操作之间无缝切换

安装

1. 克隆此仓库：

git clone <repository-url>
cd mcp-integrated-search-server

2. 安装依赖项：

npm install

3. 设置环境变量：

cp .env.example .env

4. 编辑 .env 文件并填入 API 凭据：

# Google Custom Search API Configuration
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_SEARCH_ENGINE_ID=your_custom_search_engine_id_here

# Redmine API Configuration (optional)
REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your_redmine_api_key_here

# MCP Server Configuration
LOG_LEVEL=info

5. 构建项目：

npm run build

Google API 设置

1. 获取 Google API 密钥

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Custom Search API
4. 前往“凭据”并创建 API 密钥
5. 为安全起见，将 API 密钥的使用范围限制为 Custom Search API

2. 创建 Custom Search Engine

1. 前往 Google Custom Search Engine
2. 点击“添加”以创建新的搜索引擎
3. 输入要搜索的网站（可使用 * 搜索整个网络）
4. 点击“创建”
5. 前往“设置”并复制“搜索引擎 ID”

Redmine API 设置

多仓库（推荐）

此服务支持多个 Redmine 仓库，并可安全处理密钥。

1. 根据示例创建配置文件：

Copy-Item redmine-repositories.example.json redmine-repositories.json

2. 设置配置中引用的环境变量（参见 .env.example）：

Copy-Item .env.example .env
# then edit .env to set REDMINE_MAIN_API_KEY, REDMINE_DEV_API_KEY, etc.

3. 也可以指定自定义配置路径：

$env:REDMINE_CONFIG_PATH = "./redmine-repositories.json"

注意：

• 不要在 JSON 中硬编码 API 密钥。请使用 ${VAR_NAME} 引用。
• 调用任何 Redmine 工具时，都可以传入 repository_id 来选择仓库。如果省略，则使用默认仓库。

1. 获取 Redmine API 密钥

1. 登录 Redmine 实例
2. 前往“我的账户”（通常位于右上角）
3. 点击右侧边栏中的“API 访问密钥”
4. 点击“显示”以查看 API 密钥，或点击“重置”以生成新密钥
5. 复制 API 密钥

2. 配置 Redmine URL（旧版单仓库配置）

1. 将 REDMINE_URL 设置为 Redmine 实例的 URL（例如，https://redmine.example.com）
2. 将 REDMINE_API_KEY 设置为第 1 步获取的 API 密钥

注意：如果不存在多仓库配置，仍支持旧版基于环境变量的配置作为回退方案。

使用方法

使用 Claude Desktop

将服务添加到 Claude Desktop 配置中：

MacOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "integrated-search-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-integrated-search-server/build/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key_here",
        "GOOGLE_SEARCH_ENGINE_ID": "your_custom_search_engine_id_here",
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_redmine_api_key_here"
      }
    }
  }
}

可用工具（共 10 个）

Google Search 工具（2 个）

1. google_search

使用 Google Custom Search API 搜索网页。

参数：

• query（必填）：搜索查询字符串
• num（可选）：返回结果数量（1-10，默认：10）
• start（可选）：起始索引（默认：1）
• lr（可选）：语言限制（例如：'lang_en'、'lang_ja'）
• safe（可选）：安全搜索设置（'active' 或 'off'，默认：'active'）
• siteSearch（可选）：将搜索限制在特定网站（例如：'github.com'）
• fileType（可选）：将搜索限制为特定文件类型（例如：'pdf'、'doc'）

使用示例：

Search for "TypeScript tutorial" with 5 results
Search for "machine learning" on site:arxiv.org
Search for "documentation" filetype:pdf

2. google_search_images

使用 Google Custom Search API 搜索图片。

参数：

• query（必填）：图片搜索查询字符串
• num（可选）：返回结果数量（1-10，默认：10）
• start（可选）：起始索引（默认：1）
• safe（可选）：安全搜索设置（'active' 或 'off'，默认：'active'）
• imgSize（可选）：图片尺寸筛选（'huge'、'icon'、'large'、'medium'、'small'、'xlarge'、'xxlarge'）
• imgType（可选）：图片类型筛选（'clipart'、'face'、'lineart'、'stock'、'photo'、'animated'）

使用示例：

Search for images of "golden retriever"
Find large photos of "sunset landscape"
Search for clipart images of "business icons"

Redmine API 工具（8 个）

所有 Redmine 工具都接受可选的 repository_id 参数，用于指定目标仓库。省略时，将使用 redmine-repositories.json 中配置的默认仓库。

3. redmine_list_issues

列出并筛选 Redmine 问题。

参数：

• repository_id（可选）：目标仓库 ID（省略时使用默认仓库）
• project_id（可选）：项目 ID 或标识符（省略时默认为仓库设置）
• status_id（可选）：状态 ID、状态名称/部分匹配，或 open/closed/*
• assigned_to_id（可选）：被分配者的用户 ID
• limit（可选）：返回的问题数量（1-100，默认：25）
• offset（可选）：分页起始索引（默认：0）
• sort（可选）：排序字段（例如：'id'、'created_on'、'updated_on'）
• created_on（可选）：按创建日期筛选（例如：'>=2023-01-01'）
• updated_on（可选）：按更新日期筛选

使用示例：

List all open issues
List issues for project 1
List issues assigned to user 5

4. redmine_create_issue

创建新的 Redmine 问题。

• repository_id（可选）：目标仓库 ID（省略时使用默认仓库）
• project_id（可选）：项目 ID 或标识符（省略时使用仓库默认值）
• subject（必填）：问题主题/标题
• description（可选）：问题描述
• tracker_id（可选）：跟踪器 ID 或名称（允许部分匹配）
• status_id（可选）：状态 ID 或名称（允许部分匹配）
• priority_id（可选）：优先级 ID 或名称（允许部分匹配）
• assigned_to_id（可选）：要将问题分配给的用户 ID
• start_date（可选）：开始日期（YYYY-MM-DD）
• due_date（可选）：截止日期（YYYY-MM-DD）
• estimated_hours（可选）：预估工时

使用示例：

Create a bug report for project 1
Create a feature request with high priority
Create an assigned task with due date

5. redmine_list_projects

列出可用的 Redmine 项目。

参数：

• limit（可选）：返回的项目数量（1-100，默认：25）
• offset（可选）：分页起始索引（默认：0）

使用示例：

List all projects
List first 10 projects
Browse projects with pagination

6. redmine_get_issue

获取特定 Redmine 问题的详细信息。

参数：

• issue_id（必填）：要获取的问题 ID
• include（可选）：要包含的附加数据（'attachments'、'relations'、'journals'、'watchers'）

使用示例：

Get issue #123 details
Get issue #456 with attachments and journals
Get full issue information including relations

7. redmine_update_issue

使用详细的分析报告更新现有 Redmine 问题。

• issue_id（必需）：要更新的问题 ID
• status_id（可选）：新状态 ID 或名称（仍受工作流限制）
• assigned_to_id（可选）：新受派人用户 ID
• done_ratio（可选）：进度百分比（0-100）
• notes（可选）：要添加的评论/备注
• priority_id（可选）：新优先级 ID 或名称
• due_date（可选）：截止日期（YYYY-MM-DD 格式）
• estimated_hours（可选）：预计工时
• custom_fields（可选）：自定义字段更新数组

增强功能：

• 更改前后对比：准确显示发生了哪些更改
• 成功/失败分析：明确指出哪些字段更新成功
• 考虑工作流限制：说明 Redmine 工作流限制何时会阻止更新
• 详细报告：全面反馈所有尝试的更改

用法示例：

Update issue #123 status to completed
Update issue #456 progress to 75% and add notes
Change assignee and due date for issue #789

8. redmine_bulk_update_issues

一次更新多个 Redmine 问题。

• issue_ids（必需）：要更新的问题 ID 数组
• status_id（可选）：所有问题的新状态 ID 或名称
• assigned_to_id（可选）：所有问题的新受派人用户 ID
• notes（可选）：要添加到所有问题的评论/备注

用法示例：

Mark multiple issues as completed
Reassign several issues to a different user
Add bulk comments to multiple issues

9. redmine_list_issue_comments

列出 Redmine 问题的现有评论（包含备注的日志），并支持客户端分页。

• repository_id（可选）：目标仓库 ID（未指定时使用默认仓库）
• issue_id（必需）：要检查其评论的问题
• offset（可选）：按 created_on 排序后的 0 起始偏移量（默认值：0）
• limit（可选）：要返回的评论数量（1-100，默认值：20）

返回格式化列表及元数据（总数、是否还有更多评论，以及下次请求时使用的偏移量）。

用法示例：

List the latest 5 comments for issue #42
Paginate through comments using next offset values
Inspect whether private comments exist (requires proper Redmine permissions)

10. redmine_add_issue_comment

使用官方 notes 字段向 Redmine 问题追加一条日志备注。

• repository_id（可选）：目标仓库 ID（未指定时使用默认仓库）
• issue_id（必需）：要追加评论的问题
• notes（必需）：评论文本（必须包含非空白字符）
• private_notes（可选）：将评论标记为私密（取决于 Redmine 权限）

成功更新后，工具会获取最新的日志条目，以便你验证作者、时间戳和可见性。

用法示例：

Add a public handoff comment to issue #77
Create an internal/private status update for issue #501
Post deployment notes directly from an MCP client

开发

构建

npm run build

在开发环境中运行

npm run dev

测试

npm test

配置

环境变量：

• GOOGLE_API_KEY：你的 Google API 密钥（Google 搜索必需）
• GOOGLE_SEARCH_ENGINE_ID：你的自定义搜索引擎 ID（Google 搜索必需）
• REDMINE_URL：你的 Redmine 实例 URL（可选，Redmine 功能必需）
• REDMINE_API_KEY：你的 Redmine API 密钥（可选，Redmine 功能必需）
• LOG_LEVEL：日志级别（'error'、'warn'、'info'、'debug'，默认值：'info'）

API 限制

Google Custom Search API

• 免费版每天 100 次查询
• 启用计费后每天最多 10,000 次查询
• 每次查询最多返回 10 条结果

Redmine API

• 限制取决于你的 Redmine 实例配置
• 大多数 Redmine 实例没有内置的 API 速率限制
• 批量请求时请考虑服务器资源

错误处理

该服务会针对常见问题提供详细的错误消息：

• API 密钥或搜索引擎 ID 无效
• 超出配额
• 参数无效
• 网络错误

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 根据需要添加测试
5. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

1. 查看 Google Custom Search API 文档
2. 验证你的 API 密钥和搜索引擎 ID
3. 查看服务日志中的详细错误消息
4. 在此仓库中创建问题