Integrated Search MCP Server

統合検索 MCP サーバー

Google Custom Search API と Redmine API の両方を統合し、AI アシスタントがウェブ検索や Redmine プロジェクト管理をシームレスに行える Model Context Protocol（MCP）サーバーです。

機能

Google Custom Search

• ウェブ検索：Google Custom Search API を使ってウェブを検索します
• 画像検索：高度なフィルタリングオプションで画像を検索します
• 高度なパラメーター：言語制限、サイト指定検索、ファイル形式によるフィルタリングなどに対応します

Redmine API の統合

• チケット管理：詳細な分析とともに、Redmine チケットの一覧表示、作成、表示、更新を行います
• プロジェクト管理：Redmine プロジェクトを閲覧します
• 高度なフィルタリング：プロジェクト、ステータス、担当者などでチケットをフィルタリングします
• 詳細情報：カスタムフィールドを含むチケットの全情報にアクセスできます
• 一括操作：複数のチケットを同時に更新します
• チケットのコメント：新しいジャーナルノートの追加や、ページネーションヘルパーを使った既存コメントの一覧表示を行います
• スマートな進捗管理：ワークフローを考慮したエラー処理で、チケットの進捗、期日、見積もり時間、担当者を更新します
• 詳細な更新レポート：変更前後を比較し、成功したフィールドと Redmine の制約により失敗したフィールドを表示します
• ワークフローを考慮した更新：Redmine のワークフロー制限とフィールド権限を適切に処理します

共通機能

• エラー処理：詳細なエラーメッセージを含む堅牢なエラー処理
• 入力検証：Zod スキーマを使った包括的な入力検証
• 設定可能：環境変数に基づく設定
• 2 種類の 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. 「Credentials」に移動し、API キーを作成します
5. セキュリティのため、API キーの使用を Custom Search API に制限します

2. Custom Search Engine を作成する

1. Google Custom Search Engine にアクセスします
2. 「Add」をクリックして、新しい検索エンジンを作成します
3. 検索するサイトを入力します（* を使うとウェブ全体を検索できます）
4. 「Create」をクリックします
5. 「Setup」に移動し、「Search engine 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. 「My account」に移動します（通常は右上にあります）
3. 右サイドバーの「API access key」をクリックします
4. 「Show」をクリックして API キーを表示するか、「Reset」をクリックして新しいキーを生成します
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 検索ツール（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

Redmine 課題の公式な notes フィールドを使用して、新しいジャーナルメモを追加します。

• 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

• 無料では 1 日あたり 100 件のクエリ
• 課金を有効にすると、1 日あたり最大 10,000 件のクエリ
• 1 クエリあたり最大 10 件の結果

Redmine API

• 制限は Redmine インスタンスの設定によって異なります
• ほとんどの Redmine インスタンスには、組み込みの API レート制限はありません
• 一括リクエストを行う場合は、サーバーリソースを考慮してください

エラー処理

サーバーは、次のような一般的な問題について詳細なエラーメッセージを提供します：

• API キーまたは検索エンジン ID が無効
• クォータ超過
• パラメーターが無効
• ネットワークエラー

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

ライセンス

MIT License - 詳細については LICENSE ファイルを参照してください。

サポート

問題や質問がある場合：

1. Google Custom Search API のドキュメントを確認します
2. API キーと検索エンジン ID を確認します
3. 詳細なエラーメッセージについて、サーバーログを確認します
4. このリポジトリで課題を作成します