IBM文档MCP服务器

这是一个基于配置的通用IBM产品文档检索与引用MCP服务器,支持通过YAML配置管理多个IBM产品文档,提供统一搜索和内容获取功能,适用于需要集成IBM文档查询的AI助手场景。

  • by hkwd
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 hkwd/ibm-docs-mcp

使用说明

IBM Documentation MCP Server

設定ベースアプローチによる汎用IBM製品ドキュメント検索・参照MCPサーバーです。

概要

このMCPサーバーは、YAML設定ファイルで管理された複数のIBM製品ドキュメントに簡単にアクセスできるツールを提供します。新しい製品の追加は設定ファイルの編集だけで完了します。

前提条件

  • Python 3.12以上
  • Git
  • pip

主な特徴

  • 📝 設定ベース: YAML設定ファイルで製品を管理
  • 🔍 統一検索: IBM Docs検索APIを使用した高速検索
  • 🌐 動的コンテンツ対応: Playwrightによるブラウザ自動化
  • 🔧 拡張性: 新製品の追加が容易
  • 🎯 製品別フィルタリング: 特定製品内での検索が可能
  • 🌍 多言語対応: 日本語と英語に対応(環境変数で切り替え可能)

機能

1. list_ibm_products - 製品一覧取得

利用可能なIBM製品の一覧を表示します。

パラメータ: なし

使用例:

list_ibm_products()

出力例:

# IBM製品ドキュメント一覧

## 有効な製品

### IBM SPSS Modeler (v19.0.0)
- ID: spss-modeler
- 説明: 統計分析とデータマイニングのためのビジュアルデータサイエンスツール
- 状態: ✅ 有効

2. search_ibm_docs - ドキュメント検索

指定した製品のドキュメント内をキーワードで検索します。

パラメータ:

  • product_id (必須): 製品ID(例: 'spss-modeler')
  • keyword (必須): 検索キーワード
  • max_results (オプション): 最大結果数(デフォルト: 5)

使用例:

{
  "product_id": "spss-modeler",
  "keyword": "stream save script",
  "max_results": 5
}

3. get_ibm_topic - トピック取得

特定のトピックページの内容を取得します。

パラメータ:

  • product_id (必須): 製品ID
  • topic_path (必須): トピックパス(例: 'automation-scripting-scripting-language')

使用例:

{
  "product_id": "spss-modeler",
  "topic_path": "automation-scripting-scripting-language"
}

インストール

方法 A: インストールスクリプトを使用(推奨)

PowerShell スクリプト install-ibm-docs-mcp.ps1 を使うと、以下の手順をすべて自動で実行できます。

実行するもの:

  1. 前提条件チェック(Python 3.12+、Git の存在確認)
  2. GitHubリポジトリのクローン(既存の場合は git pull)
  3. Python 依存パッケージのインストール(pip install -e .)
  4. Playwright Chromium のインストール
  5. Bob の MCP 設定ファイル(~/.bob/settings/mcp.json)へのサーバー登録
  6. サーバー起動テスト(3秒間起動確認)

実行方法:

# スクリプトをダウンロードして実行
irm https://raw.githubusercontent.com/hkwd/ibm-docs-mcp/main/install-ibm-docs-mcp.ps1 | iex

または、スクリプトファイルを直接実行:

.\install-ibm-docs-mcp.ps1

インストール先:

項目 パス
サーバー本体 %USERPROFILE%\.mcp-servers\ibm-docs-mcp
MCP 設定ファイル %USERPROFILE%\.bob\settings\mcp.json
製品設定ファイル %USERPROFILE%\.mcp-servers\ibm-docs-mcp\config\products.yaml

スクリプト内の設定変更:

スクリプト冒頭の Config セクションを編集することで、インストール先などをカスタマイズできます:

$RepoUrl    = "https://github.com/hkwd/ibm-docs-mcp.git"
$InstallDir = "$env:USERPROFILE\.mcp-servers\ibm-docs-mcp"  # インストール先
$McpJson    = "$env:USERPROFILE\.bob\settings\mcp.json"      # MCP設定ファイル

ワークスペース単位の MCP 設定を使う場合は $McpJson = ".bob\mcp.json" に変更してください(スクリプト内のコメントを参照)。

インストール完了後の次のステップ:

  1. Bob を再起動
  2. MCP パネルに ibm-docs が表示されることを確認
  3. 製品を追加・管理する場合は config/products.yaml を編集

方法 B: 手動インストール

前提条件

  • Python 3.12以上
  • pip

1. プロジェクトファイルのコピー

# MCPサーバー用ディレクトリを作成
mkdir "C:\Users\<ユーザー名>\.mcp-servers"

# プロジェクトファイルをコピー
# 方法1: エクスプローラーでibm-docs-mcpフォルダ全体をコピー
# 方法2: コマンドラインでコピー(現在のディレクトリから)
xcopy /E /I <ダウンロードしたフォルダ> "C:\Users\<ユーザー名>\.mcp-servers\ibm-docs-mcp"

2. 依存パッケージのインストール

# プロジェクトディレクトリに移動
cd "C:\Users\<ユーザー名>\.mcp-servers\ibm-docs-mcp"

# 開発モードでインストール(推奨)
pip install -e .

# Playwrightブラウザをインストール
python -m playwright install chromium

3. MCP設定への追加

C:\Users\<ユーザー名>\.bob\settings\mcp.jsonに以下を追加:

{
  "mcpServers": {
    "ibm-docs": {
      "command": "python",
      "args": ["-m", "ibm_docs.server"],
      "cwd": "C:\\Users\\<ユーザー名>\\.mcp-servers\\ibm-docs-mcp"
    }
  }
}

注意: cwdパスは実際のプロジェクトディレクトリに合わせて変更してください。

4. 動作確認

サーバーが正しく起動するか確認:

python -m ibm_docs.server

製品の追加・管理

新しい製品を追加する

config/products.yamlを編集して新しい製品を追加します:

products:
  # 新しい製品を追加
  your-product:
    name: "Your Product Name"
    base_url: "https://www.ibm.com/docs/ja/your-product/1.0.0"
    scope: "YOUR_SCOPE_ID"
    language: "ja"
    version: "1.0.0"
    description: "製品の説明"
    selectors:
      title: "h1"
      content: "article"
      fallback_title: "title"
      fallback_content: "main"
    enabled: true  # 有効化

製品を無効化する

enabled: falseに設定すると、その製品は利用できなくなります:

products:
  watson-studio:
    # ... 他の設定 ...
    enabled: false  # 無効化

スコープIDの調べ方

  1. IBM Docsで製品ページを開く
  2. URLを確認(例: https://www.ibm.com/docs/ja/spss-modeler/19.0.0)
  3. ブラウザの開発者ツールでネットワークタブを開く
  4. 検索を実行
  5. api/v1/searchへのリクエストを確認
  6. productsパラメータの値がスコープID

プロジェクト構造

260306ibm-docs-mcp/
├── config/
│   └── products.yaml          # 製品設定ファイル
├── src/
│   └── ibm_docs/
│       ├── __init__.py
│       ├── server.py          # MCPサーバー実装
│       ├── scraper.py         # 汎用スクレイパー
│       ├── config_loader.py   # 設定読み込み
│       └── i18n/              # 多言語対応
│           ├── __init__.py
│           ├── messages.py    # メッセージ管理
│           └── locales/       # 言語ファイル
│               ├── ja.json    # 日本語
│               └── en.json    # 英語
├── pyproject.toml             # プロジェクト設定
├── requirements.txt           # 依存パッケージ
├── README.md                  # このファイル
├── test_server.py             # テストスクリプト
└── test_i18n.py               # 多言語対応テスト

設定ファイルリファレンス

製品設定

フィールド 型 必須 説明
name string ✅ 製品の表示名
base_url string ✅ ドキュメントのベースURL
scope string ✅ IBM Docs検索APIのスコープID
language string ✅ 言語コード(ja, en等)
version string ✅ 製品バージョン
description string ❌ 製品の説明
enabled boolean ✅ 有効/無効フラグ
selectors object ✅ HTMLセレクタ設定

グローバル設定

フィールド 型 デフォルト 説明
search_api_url string IBM Docs API 検索APIのURL
search_base_url string IBM Docs検索 検索ページのURL
default_max_results integer 10 デフォルト最大結果数
timeout integer 30 リクエストタイムアウト(秒)
use_browser boolean true Playwrightを使用するか
browser_headless boolean true ヘッドレスモードで実行するか
wait_for_content integer 2 コンテンツ読み込み待機時間(秒)
default_language string ja デフォルト言語(環境変数で上書き可能)
supported_languages array ["ja", "en"] サポートする言語のリスト

多言語対応

このMCPサーバーは日本語と英語に対応しています。

言語の切り替え方法

方法1: 環境変数を使用(推奨)

環境変数 IBM_DOCS_LANG を設定することで言語を切り替えられます。

Bobの場合: C:\Users\<ユーザー名>\.bob\settings\mcp_settings.jsonを編集:

{
  "mcpServers": {
    "ibm-docs": {
      "command": "python",
      "args": ["-m", "ibm_docs.server"],
      "cwd": "C:\\Users\\<ユーザー名>\\.mcp-servers\\ibm-docs-mcp",
      "env": {
        "IBM_DOCS_LANG": "en"
      }
    }
  }
}

コマンドラインから実行する場合:

Windows (PowerShell):

$env:IBM_DOCS_LANG="en"
python -m ibm_docs.server

Windows (コマンドプロンプト):

set IBM_DOCS_LANG=en
python -m ibm_docs.server

Linux/Mac:

export IBM_DOCS_LANG=en
python -m ibm_docs.server

方法2: 設定ファイルを編集

config/products.yamlのdefault_languageを変更:

global:
  default_language: "en"  # 'ja' または 'en'
  supported_languages: ["ja", "en"]

サポートされる言語

言語コード 言語名 状態
ja 日本語 ✅ 完全サポート
en English ✅ 完全サポート

新しい言語の追加方法

  1. src/ibm_docs/i18n/locales/に新しい言語ファイルを作成(例: fr.json)
  2. 既存のja.jsonまたはen.jsonをテンプレートとして使用
  3. すべてのメッセージを翻訳
  4. config/products.yamlのsupported_languagesに言語コードを追加
global:
  supported_languages: ["ja", "en", "fr"]

多言語対応の仕組み

  • 優先順位: 環境変数 IBM_DOCS_LANG > 設定ファイル default_language > デフォルト(日本語)
  • フォールバック: 翻訳が見つからない場合は英語にフォールバック
  • メッセージ管理: すべてのメッセージはsrc/ibm_docs/i18n/locales/のJSONファイルで管理

使用方法

Bobでの使用

MCPサーバーが登録されているため、Bobを再起動すると自動的にツールが利用可能になります。

使用例:

ユーザー: "利用可能なIBM製品を教えて"
Bob: list_ibm_products()を使用...

ユーザー: "SPSS Modelerでストリームを保存する方法を教えて"
Bob: search_ibm_docs(product_id="spss-modeler", keyword="stream save script")を使用...

トラブルシューティング

MCPサーバーが起動しない

  1. Pythonのバージョンを確認:
python --version  # 3.10以上であることを確認
  1. 依存パッケージを再インストール:
pip install -r requirements.txt
playwright install chromium
  1. MCP設定ファイルのパスを確認

製品が見つからない

  1. list_ibm_productsで製品一覧を確認
  2. config/products.yamlで製品がenabled: trueになっているか確認
  3. 製品IDが正しいか確認(ハイフン区切り、小文字)

検索結果が少ない

  • 検索キーワードを変更してみる
  • max_resultsパラメータを増やす
  • 製品のスコープIDが正しいか確認

コンテンツが取得できない

  1. ツールが生成したURLを直接ブラウザで開く
  2. config/products.yamlのセレクタ設定を確認
  3. use_browser: falseに設定して検索APIのみを使用

技術スタック

  • Python: 3.10以上
  • MCP SDK: 1.0.0以上
  • requests: HTTP通信
  • BeautifulSoup4: HTMLパース
  • lxml: XMLパーサー
  • Playwright: ブラウザ自動化
  • PyYAML: YAML設定ファイル読み込み

開発

テストの実行

# 基本テスト
python test_server.py

# 特定の製品をテスト
python test_server.py --product spss-modeler

新機能の追加

  1. src/ibm_docs/scraper.pyにメソッドを追加
  2. src/ibm_docs/server.pyにツールを追加
  3. テストを作成・実行
  4. README.mdを更新

注意事項


本コードは現状有姿(AS-IS)で公開しており、動作保証はありません。検証環境等で十分テストの上、自己責任でご利用ください


Made with Bob 🤖