Polarion MCP Servers

Polarion MCP サーバー

このリポジトリには、Polarion Application Lifecycle Management（ALM）との統合用の Model Context Protocol（MCP）サーバー実装が含まれています。

Polarion の作業項目向けに、以下の MCP ツールを利用できます。

• get_document_info：Polarion ドキュメントのメタデータとカスタムフィールドを取得します。
• get_document_outline：Polarion ドキュメント内のすべてのセクション見出し（目次）を取得します。
• get_document_revision_history：Polarion ドキュメント／モジュールの改訂履歴を取得します。
• get_document_section：Polarion ドキュメント内の特定のセクション見出しと、その下位見出しのコンテンツを取得します。
• get_workitem：作業項目のテキストコンテンツを取得します。特定の改訂を指定して取得することもできます。
• get_workitem_details：標準フィールド、カスタムフィールド、リンクされた作業項目など、作業項目の詳細情報を取得します。リンクを再帰的にたどることで、トレーサビリティをサポートします。
• get_workitem_history：各改訂時点のコンテンツを含む、作業項目の改訂履歴を取得します。
• get_workitems_in_module：Polarion モジュール／ドキュメントから作業項目を検索します。ピン留めされた参照にはそのピン留め時の改訂が表示され、解決できない参照は URI とともに報告されます。
• list_custom_fields：特定の作業項目タイプで利用可能なカスタムフィールドを一覧表示します。
• list_documents：Polarion プロジェクト内のすべてのドキュメントを一覧表示します。スペース名やタイトルで絞り込むこともできます。
• list_spaces：Polarion プロジェクト内のすべてのスペース名を一覧表示します。
• list_workitem_types：現在のプロジェクトで設定されているすべての作業項目タイプを一覧表示します。
• search_in_document：検索語に一致する作業項目を Polarion ドキュメント内で検索します。
• search_workitems：テキストコンテンツを使用して、Polarion プロジェクト全体から作業項目を検索します。
• search_workitems_sql (オプトイン)：検証済みの読み取り専用 SQL クエリ（WORKITEM に対する単一の SELECT で C_PK を取得）を Polarion の SQL:(…) フィルターとして実行します。複雑な結合を含む、プレーンな Lucene では表現できない読み取りに適しています。SqlQueryTool:Enabled=true の場合にのみ登録されます。結果はエンドポイントのプロジェクト内に限定されます。RBACを参照してください。

プロジェクト

• PolarionRemoteMcpServer：サーバーベースのインストール向けの Streamable HTTP MCP サーバーです。ステートレスで、オプションのOAuth 2.1 認証と呼び出し元ごとの RBACに対応しています。
• PolarionMcpServer：ローカルのワークステーションへのインストール向けの、Polarion 統合用コンソールベース MCP サーバーです。

Docker と Linux サーバーでの実行（推奨）

1. Linux サーバーで、設定ファイルとログ用のディレクトリを作成します。

   mkdir -p /opt/polarion-mcp-server
   cd /opt/polarion-mcp-server
   

2. Docker イメージをプルします。

   docker pull peakflames/polarion-remote-mcp-server
   

3. Polarion の設定に合わせて /opt/polarion-mcp-server/appsettings.json ファイルを作成します。

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "ApiConsumers": {
       "Consumers": {
         "my_app": {
           "Name": "My Application",
           "ApplicationKey": "your-secure-api-key-here",
           "Active": true,
           "AllowedScopes": ["polarion:read"],
           "Description": "API consumer for my application"
         }
       }
     },
     "PolarionProjects": [
          {
              "ProjectUrlAlias": "starlight", 
              "Default": true,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion.int.mycompany.com/",
                  "Username": "shared_user_read_only",
                  "Password": "linear-Vietnam-FLIP-212824", 
                  "ProjectId": "Starlight_Main", 
                  "TimeoutSeconds": 60
              },
              "PolarionWorkItemTypes": [
                {
                  "id": "requirement",
                  "fields": ["custom_field_1", "priority", "severity"]
                },
                {
                  "id": "defect",
                  "fields": ["defect_type", "found_in_build"]
                }
              ]
          },
          {
              "ProjectUrlAlias": "octopus", 
              "Default": false,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion.int.mycompany.com/",
                  "Username": "some_other_user",
                  "Password": "linear-Vietnam-FLIP-212824", 
                  "ProjectId": "octopus_gov", 
                  "TimeoutSeconds": 60
              }
          },
          {
              "ProjectUrlAlias": "grogu", 
              "Default": false,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion-dev.int.mycompany.com/",
                  "Username": "vader",
                  "Password": "12345", 
                  "ProjectId": "grogu_boss", 
                  "TimeoutSeconds": 60
              }
          }
      ]
   }
   

4. Docker コンテナーを実行します。

   docker run -d \
     --name polarion-mcp-server \
     -p 8080:8080 \
     -v appsettings.json:/app/appsettings.json \
     peakflames/polarion-remote-mcp-server
   

5. これでサーバーが起動します。MCP クライアントは、目的のプロジェクト設定エイリアスに応じた URL を使用して接続します。

   1. Streamable HTTP トランスポート：http://{{your-server-ip}}:8080/{ProjectUrlAlias}/mcp。

6. サーバーは以下も提供します。

   • REST API：http://{{your-server-ip}}:8080/polarion/rest/v1/projects/{ProjectId}/...（SessionConfig.ProjectId を使用します）
     • 注： REST API エンドポイントでは、X-API-Key ヘッダーによる API キー認証が必要です。
   • API ドキュメント：http://{{your-server-ip}}:8080/scalar/v1（認証 UI を含みます）
   • ヘルスチェック：http://{{your-server-ip}}:8080/api/health

7. 📢重要 - セッション接続はレプリカ間で共有されないため、サーバーをレプリカインスタンスで実行しないでください。

設定オプション

設定ファイル：

• appsettings.json - 本番環境／サーバーのデプロイ向けの基本設定です。Gitで追跡され、シークレットではないデフォルト値のみを保持します。
• appsettings.Development.json - ローカル開発用に基本設定を上書きします。こちらもGitで追跡されます（シークレットではないデフォルト値のみ）。Developmentモードではこちらが優先されます。実際の認証情報を入力したバリアントはコミットしないでください。.gitignoreを参照してください。
• .env - 任意の環境変数です（.env.exampleからコピー）。POLARION_DEFAULT_PROJECTを設定できます。

サーバーは、appsettings.jsonのPolarionProjects配列を使用して、1つ以上のPolarionインスタンス設定を定義します。配列内の各オブジェクトは、一意のURLエイリアスでアクセスできる個別の設定を表します。

トップレベル設定	説明
PolarionProjects	（配列）1つ以上のPolarionプロジェクト設定オブジェクトを含みます。
McpAuth	（オブジェクト、省略可）MCPエンドポイント向けのOAuth 2.1リソースサーバー認証です。デフォルトでは無効です。
Rbac	（オブジェクト、省略可）MCPツール呼び出しに対する、呼び出し元ごとのPolarionプロジェクト可視性ゲートです。デフォルトでは無効で、McpAuthが必要です。
Credentials	（オブジェクト、省略可）MCP呼び出しで上流のPolarion認証情報を誰のものにするかを制御します。デフォルトでは、現在の共有サービスアカウントの動作が使用されます。

各プロジェクト設定オブジェクト：

設定	説明	必須	デフォルト
ProjectUrlAlias	この設定を識別するために接続URL（/{ProjectUrlAlias}/mcp）で使用する一意の文字列です。	はい	なし
Default	（ブール値）trueの場合、クライアントがProjectUrlAliasを指定せずに接続すると、この設定が使用されます。trueにできるエントリは1つだけです。	いいえ	false
SessionConfig	（オブジェクト）このPolarionインスタンスの接続情報を含みます。	はい	なし
PolarionWorkItemTypes	（配列、省略可）このプロジェクト内の特定のWorkItemタイプについて、取得するカスタムフィールドを定義します。配列内の各オブジェクトには、id（文字列、WorkItemタイプID）とfields（文字列の配列、カスタムフィールド名）が必要です。	いいえ	空のリスト

SessionConfigオブジェクトの詳細：

設定	説明	必須	デフォルト
ServerUrl	PolarionサーバーのURL（例："https://polarion.example.com/"）	はい	なし
Username	適切な権限を持つPolarionのユーザー名です。	はい	なし
Password	Polarionユーザーのパスワードです。（安全な代替手段の使用を検討してください）	はい	なし
ProjectId	操作対象となるPolarionプロジェクトの実際のIDです。	はい	なし
TimeoutSeconds	接続タイムアウト（秒）です。	いいえ	60
MaxReceivedMessageSize	（任意の整数、バイト単位）Polarionクライアントが受け入れる最大レスポンスサイズです。設定する場合は、ゼロより大きい値にする必要があります。	いいえ	未設定（上限なし、int.MaxValue）

環境変数によるパスワードの上書き

パスワードを設定ファイルに記載する代わりに、環境変数 POLARION_PASSWORD を設定してください。この環境変数が設定されている場合、構成済みのすべてのプロジェクトで SessionConfig.Password が上書きされます。

Docker の例：

docker run -d \
  --name polarion-mcp-server \
  -p 8080:8080 \
  -e POLARION_PASSWORD=your-secret-password \
  -v appsettings.json:/app/appsettings.json \
  peakflames/polarion-remote-mcp-server

これは PolarionRemoteMcpServer（HTTP）と PolarionMcpServer（stdio）の両方で機能します。

注：appsettings.json にプレーンテキストのパスワードを記載するのではなく、環境変数 POLARION_PASSWORD や、User Secrets、Azure Key Vault などのより安全な方法で認証情報を保存することを強く推奨します。

REST API 仕様との整合性

REST API は、https://testdrive.polarion.com/polarion/rest/v1/definition で公開されている公式の Polarion REST API仕様に準拠するよう設計されています。エンドポイントの実装や拡張時の参照用として、この仕様のローカルコピーを docs/polarion-rest-vq-definition.json に保存しています。

API キー認証（REST API のみ）

REST API エンドポイントへのアクセスには、API キーによる認証が必要です。appsettings.json の ApiConsumers セクションで API 利用者を構成してください。

設定	説明	必須
ApiConsumers.Consumers	利用者 ID をキーとする利用者構成の辞書	はい
Name	API 利用者の表示名	はい
ApplicationKey	認証に使用する API キー	はい
Active	利用者に認証を許可するかどうか	はい
AllowedScopes	スコープのリスト（例：["polarion:read"]）	はい
Description	任意の利用者の説明	いいえ

利用可能なスコープ：

• polarion:read - すべての REST API エンドポイントへの読み取りアクセス

使用方法：

curl -H "X-API-Key: your-api-key" http://localhost:8080/polarion/rest/v1/projects/{projectId}/spaces

**注：**ヘルスチェック（/api/health、/api/version）と API ドキュメント（/scalar/v1）には認証は必要ありません。MCP エンドポイントにも認証は必要ありません。ただし、これは McpAuth:Enabled が false（デフォルト）の場合に限ります。次のセクションを参照してください。

任意：MCP 認証と呼び出し元ごとのアクセス制御

PolarionRemoteMcpServer は、MCP エンドポイントで既定では無効になっている、独立した以下の 2 つの機能をサポートしています。

• OAuth 2.1 認証（McpAuth:Enabled）— tools/call の実行を許可する前に、外部認可サーバーからのベアラートークンを要求します。提供される各プロジェクトエイリアスは、独自の RFC 9728 保護リソースメタデータを /.well-known/oauth-protected-resource/{alias}/mcp で公開するため、準拠した MCP クライアントは認証方法を自動的に検出できます。
• 呼び出し元ごとの RBAC（Rbac:Enabled）— さらに、認証済みのすべての呼び出し元に同じアクセスを共有させるのではなく、各 tools/call を呼び出し元ユーザー自身の Polarion プロジェクトメンバーシップに基づいて認可します。McpAuth:Enabled=true が必要です。

どちらもデフォルトでは false で、構成しない限り、サーバーの動作は以前のリリースから変わりません。セットアップ、構成リファレンス表、起動時の検証エラーについては、docs/authentication.md と docs/rbac.md を参照してください。

3 つ目の既定では無効になっている機能は、SQL クエリツールです。

キー	デフォルト	効果
SqlQueryTool:Enabled	false	true の場合、両方のサーバーに search_workitems_sql ツールを登録します。このツールはプロジェクト内に限定されるため（docs/rbac.md を参照）、ツールごとの RBAC ルールは不要です。ただし、複雑な結合を通じて他のプロジェクトにデータが存在するかどうかを判定できるため、このリスクを許容できない場合は無効のままにしてください。

MCP クライアントの設定

Cline の設定方法：

1. Cline の MCP 設定 UI を開きます
2. 「Remote Servers」タブをクリックします
3. ユーザーが接続を希望する appsettings.json 内の各 ProjectUrlAlias について：

{
  "mcpServers": {
    ...
    ...

    "Polarion Starlight": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/starlight/mcp",
      "transportType": "streamableHttp"
    },
    "Polarion Octopus": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/octopus/mcp",
    "transportType": "streamableHttp"
    }
  ...
  ...
}

1. 接続する各 ProjectUrlAlias について、同じ手順を繰り返します。

Visual Studio Code の設定方法：

次の設定を settings.json ファイルに追加します：

"servers": {
    "polarion-starlight": { // Use a descriptive key
        "type": "http",
        "url": "http://{{your-server-ip}}:8080/starlight/mcp", // Replace with your alias
        "env": {}
    },
    "polarion-octopus": { 
        "type": "http",
        "url": "http://{{your-server-ip}}:8080/octopus/mcp", // Replace with your alias
        "env": {}
    }
    // Add entries for each ProjectUrlAlias
}

または CLI から：

claude mcp add --transport http polarion-starlight http://{{your-server-ip}}:8080/starlight/mcp

Claude Desktop の場合：

Claude Desktop はまだストリーミング可能な HTTP をネイティブサポートしていませんが、claude_desktop_config.json ファイルに次の設定を追加してプロキシを使用できます：

{
  "mcpServers": {
    "polarion-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://{{your-server-ip}}:8080/{ProjectUrlAlias}/mcp" // Replace {ProjectUrlAlias}
      ]
    }
    // Add entries for each ProjectUrlAlias, potentially using different keys like "polarion-starlight"
  }
}

ローカルでの実行（stdio）

ローカル開発またはワークステーションでの使用では、stdio ベースの MCP サーバーを実行できます：

1. リリースページから、お使いのプラットフォームに適した実行ファイルをダウンロードします
2. MCP クライアントで、実行ファイルのパスを指定して stdio トランスポートを使用するように設定します

トラブルシューティング

POST /{alias}/mcp が 401 を返し、クライアントがログインを促さない — クライアントが MCP の OAuth ディスカバリーフロー（RFC 9728）を実装していることを確認してください。/.well-known/oauth-protected-resource/{alias}/mcp を自分で取得してください。404 が返される場合、実行中のサーバーで McpAuth:Enabled が実際には true になっていません。docs/authentication.md を参照してください。

POST /{alias}/mcp が 403 を返す — 呼び出し元は認証されていますが、必要なスコープが不足しているか、その OAuth クライアント ID が McpAuth:AllowedClientIds に含まれていません。401 と 403 を参照してください。

McpAuth または Rbac の検証エラーでサーバーが起動を拒否する — 各メッセージに修正が必要な正確なキーが示されます。docs/authentication.md および docs/rbac.md の検証エラー表を参照してください。

RBAC のもとですべての MCP ツール呼び出しが拒否される — RBAC は設計上、フェイルクローズ方式です。Rbac:AuditOnly=true を設定し、アクセス監査レコードの DecisionReason フィールドを確認してください。docs/rbac.md#troubleshooting を参照してください。

貢献

貢献またはソースからのビルドを希望する開発者は、CONTRIBUTING.md を参照してください。

ライセンス

詳細は LICENSE を参照してください。