使用说明
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(必須): 製品IDtopic_path(必須): トピックパス(例: 'automation-scripting-scripting-language')
使用例:
{
"product_id": "spss-modeler",
"topic_path": "automation-scripting-scripting-language"
}
インストール
方法 A: インストールスクリプトを使用(推奨)
PowerShell スクリプト install-ibm-docs-mcp.ps1 を使うと、以下の手順をすべて自動で実行できます。
実行するもの:
- 前提条件チェック(Python 3.12+、Git の存在確認)
- GitHubリポジトリのクローン(既存の場合は
git pull) - Python 依存パッケージのインストール(
pip install -e .) - Playwright Chromium のインストール
- Bob の MCP 設定ファイル(
~/.bob/settings/mcp.json)へのサーバー登録 - サーバー起動テスト(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"に変更してください(スクリプト内のコメントを参照)。
インストール完了後の次のステップ:
- Bob を再起動
- MCP パネルに
ibm-docsが表示されることを確認 - 製品を追加・管理する場合は
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の調べ方
- IBM Docsで製品ページを開く
- URLを確認(例:
https://www.ibm.com/docs/ja/spss-modeler/19.0.0) - ブラウザの開発者ツールでネットワークタブを開く
- 検索を実行
api/v1/searchへのリクエストを確認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 | ✅ 完全サポート |
新しい言語の追加方法
src/ibm_docs/i18n/locales/に新しい言語ファイルを作成(例:fr.json)- 既存の
ja.jsonまたはen.jsonをテンプレートとして使用 - すべてのメッセージを翻訳
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サーバーが起動しない
- Pythonのバージョンを確認:
python --version # 3.10以上であることを確認
- 依存パッケージを再インストール:
pip install -r requirements.txt
playwright install chromium
- MCP設定ファイルのパスを確認
製品が見つからない
list_ibm_productsで製品一覧を確認config/products.yamlで製品がenabled: trueになっているか確認- 製品IDが正しいか確認(ハイフン区切り、小文字)
検索結果が少ない
- 検索キーワードを変更してみる
max_resultsパラメータを増やす- 製品のスコープIDが正しいか確認
コンテンツが取得できない
- ツールが生成したURLを直接ブラウザで開く
config/products.yamlのセレクタ設定を確認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
新機能の追加
src/ibm_docs/scraper.pyにメソッドを追加src/ibm_docs/server.pyにツールを追加- テストを作成・実行
- README.mdを更新
注意事項
本コードは現状有姿(AS-IS)で公開しており、動作保証はありません。検証環境等で十分テストの上、自己責任でご利用ください
Made with Bob 🤖