Jama Connect MCP Server (Unofficial)

Jama Connect MCP サーバー（非公式）

このプロジェクトは、Jama Connect インスタンスと連携するための読み取り専用ツールを提供する Model Context Protocol（MCP）サーバーです。公式の Jama Software py-jama-rest-client ライブラリを MCP でラップしています。

免責事項： これはサードパーティ製のオープンソースプロジェクトであり、Jama Software との公式な提携や承認はありません。

注記： このサーバーは現在、読み取り専用の操作のみをサポートしています。今後のアップデートで書き込み操作が追加される可能性があります。

方針：ローカル実行とセキュリティ

この MCP サーバーは、PyPI やその他のインデックスにパッケージとして意図的に公開していません。この方針により、ユーザーは次のことを行えます。

1. リポジトリをクローン／フォークする： コードを直接入手します。
2. コードを確認する： 実行前に、特に API とのやり取りや認証情報の取り扱いについて、サーバーの動作を正確に把握します。
3. 必要に応じて調整する： 特定の企業要件やセキュリティ方針に合わせてコードを変更します。

この方法では、利便性よりもセキュリティへの意識とユーザーによる制御を優先し、未検証の可能性があるサードパーティ製パッケージのインストールに伴うリスクを軽減します。現時点でサポートされている方法は、リポジトリをクローンしてローカルで実行することのみです。

前提条件

ソースからのビルド

• Python： バージョン 3.12 以降。
• uv： Python パッケージインストーラー兼仮想環境マネージャーです。（インストールガイド）
• Git： リポジトリのクローンに使用します。
• Docker Docker で実行する場合に使用します。

セットアップ

Docker

1. リポジトリをクローンする：

   git clone https://github.com/t-j-thomas/jama-mcp-server.git
   cd jama-mcp-server
   

2. Docker をビルドする：

   sudo docker build -t jama-mcp-server .
   

   これにより、プロジェクトの pyproject.tonl と uv.lock の設定を使用して Docker イメージがビルドされます。

3. Jama Rest Client リポジトリの証明書が原因でビルドに問題が発生する場合：

   certificate verification failed: CAFile のようなエラーが表示された場合は、任意で https://github.com/jamasoftware-ps/py-jama-rest-client.git リポジトリをこのディレクトリにクローンし、次のコメントを解除できます。

   # py-jama-rest-client = { path = "./py-jama-rest-client", editable = true }

   pyproject.toml ファイル内の上記の行を有効にし、次の行をコメントアウトしてください。

   py-jama-rest-client = { git = "https://github.com/jamasoftware-ps/py-jama-rest-client.git" }

   その後、

   uv sync
   sudo docker build -t jama-mcp-server .
   

ソースからのビルド

1. リポジトリをクローンする：

   git clone https://github.com/t-j-thomas/jama-mcp-server.git
   cd jama-mcp-server
   

2. 依存関係をインストールする： サーバーディレクトリに移動し、uv を使用して仮想環境を作成し、依存関係をインストールします。

   uv sync
   

   これにより、認証情報に AWS Parameter Store を使用する場合に必要な boto3 を含む依存関係がインストールされます。

設定

このサーバーは、OAuth 2.0 を使用して Jama Connect インスタンスに接続するために環境変数を必要とします。認証情報は直接指定するか、AWS Parameter Store から安全に取得できます。

認証方法：

1. 環境変数で直接指定：

   • JAMA_URL（必須）：Jama Connect インスタンスのベース URL（例：https://yourcompany.jamacloud.com）。
   • JAMA_CLIENT_ID（この方法では必須）：Jama API の OAuth クライアント ID。
   • JAMA_CLIENT_SECRET（この方法では必須）：Jama API の OAuth クライアントシークレット。
   • JAMA_CLIENT_ID と JAMA_CLIENT_SECRET の両方が設定されている場合、これらが直接使用され、AWS Parameter Store の設定は無視されます。

2. AWS Parameter Store（Docker ではサポートされていません）：

   • この方法は、JAMA_CLIENT_ID と JAMA_CLIENT_SECRET の両方が環境変数に直接設定されていない場合にのみ使用されます。
   • JAMA_URL（必須）：Jama Connect インスタンスのベース URL。
   • JAMA_AWS_SECRET_PATH（この方法では必須）：Jama の認証情報を含む、AWS Parameter Store 内のシークレットの完全な名前／パス。
     • シークレットの値は、次の構造を持つ JSON 文字列でなければなりません：{"client_id": "YOUR_JAMA_CLIENT_ID", "client_secret": "YOUR_JAMA_CLIENT_SECRET"}。
   • JAMA_AWS_PROFILE（任意）：AWS への認証に使用する AWS 名前付きプロファイル。設定されていない場合、boto3 はデフォルトの認証情報解決方法を使用します。現在の aws セッションの認証情報は有効である必要があります（期限切れの場合は更新してください）。
   • **注：**この方法を使用するには、boto3 ライブラリがインストールされていること（uv sync でインストールされます）と、サーバーの実行環境に、指定された Parameter Store のシークレットへアクセスするための適切な AWS 権限が必要です。

サーバーはまず JAMA_CLIENT_ID と JAMA_CLIENT_SECRET を確認します。両方が存在する場合は、それらを使用します。そうでない場合は、JAMA_AWS_SECRET_PATH を確認し、AWS から認証情報を取得します。どちらの方法でも必要な認証情報を取得できない場合（かつモックモードがオフの場合）、サーバーは起動に失敗します。

モックモード（任意）：

実際の Jama インスタンスに接続せずにテストする場合：

• JAMA_MOCK_MODE：組み込みのモッククライアントを使用するには、true に設定します。サーバーは事前定義されたサンプルデータを返します。それ以外の値を設定するか、この変数を省略すると、モックモードは無効になります。

環境変数の設定：

MCP クライアントがサーバープロセスを起動する環境で、これらの変数を設定してください。設定場所は次のとおりです。

• ターミナルセッション（export JAMA_URL=...）。
• MCP クライアントのサーバー設定内で直接指定（以下を参照）。

サーバーの実行（単体）

環境変数が設定されていることを確認したうえで、基本的なチェックのために uv を使用してサーバーを直接実行できます。

# Ensure you are in the jama-mcp-server directory
uv run python -m jama_mcp_server.server

test_mcp_client.py を使用したテスト

このリポジトリには、主にデバッグや簡単な確認、特にモックモードで、stdio 経由でサーバーのツールを直接呼び出すためのテストクライアントスクリプト（test_mcp_client.py）が含まれています。

テストクライアントを実行するには：

# Ensure you are in the jama-mcp-server directory
# This script automatically sets JAMA_MOCK_MODE=true for the server it launches
uv run python test_mcp_client.py

このスクリプトはサーバーを起動し、事前定義されたさまざまなツール（モックモードでの成功ケースと想定される失敗ケースを含む）を呼び出して、結果を出力し、概要を表示します。特定のツールやシナリオをテストするために、このスクリプトを変更できます。

MCP クライアントとの統合（ローカル実行）

MCP クライアント（Cline、RooCode、Claude Desktop など）の設定（例：mcp_settings.json）で、このサーバーを起動するように設定してください。

Docker 設定の例（mcp_settings.json）：

{
  "mcpServers": {
    "jama-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "JAMA_URL", "-e", "JAMA_CLIENT_ID", "-e", "JAMA_CLIENT_SECRET", "-e", "JAMA_MOCK_MODE",
        "jama-mcp-server"
      ],
      "env": {
        "JAMA_URL": "https://your-jama-instance.com",
        "JAMA_CLIENT_ID": "your-client-id",
        "JAMA_CLIENT_SECRET": ""
      }
    },
  }
}

UV 設定の例（mcp_settings.json）：

{
  "mcpServers": {
    "jama-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "jama_mcp_server.server"
      ],
      
      "cwd": "/path/to/your/clone/jama-mcp-server",
      "env": {
        "JAMA_URL": "https://your.jama.instance.com",
        "JAMA_CLIENT_ID": "your_client_id",
        "JAMA_CLIENT_SECRET": "your_client_secret",
        "JAMA_AWS_SECRET_PATH": "/path/to/your/jama/secret",
        "JAMA_AWS_PROFILE": "your-aws-profile-name",
        "JAMA_MOCK_MODE": "false"
      }
    }
  }
}

重要な点：

• cwd パスは、uv がプロジェクトのコンテキストを見つけるために重要です。
• 必要な Jama の環境変数がサーバープロセスから利用できることを確認してください。

利用可能なツール

このサーバーは、さまざまな読み取り専用ツールを提供します。接続後、利用可能なツールの一覧を MCP クライアントのインターフェースで確認してください。例として、get_jama_projects、get_jama_item、get_jama_relationships などがあります。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

コントリビューション

コントリビューションやフィードバックを歓迎します！ガイドラインについては、CONTRIBUTING.md ファイルをご覧ください。

トラブルシューティング

• 接続／認証エラー：
  • JAMA_URL が正しいことを確認してください。
  • JAMA_CLIENT_ID と JAMA_CLIENT_SECRET が正しく設定されていることを確認してください。これらが優先されます。
  • 直接指定する環境変数が設定されていない場合は、AWS Parameter Store の設定を確認してください。
    • JAMA_AWS_SECRET_PATH が正しいことを確認してください。
    • サーバーの実行環境にシークレットを読み取る権限があることを確認してください（IAM ロール／ポリシーを確認してください）。
    • シークレットの値が有効な JSON であることを確認してください：{"client_id": "...", "client_secret": "..."}。
    • boto3 が正しくインストールされていることを確認してください（uv sync）。
    • JAMA_AWS_PROFILE を使用する場合は、プロファイルが存在し、正しく設定されていることを確認してください。
  • どちらの方法でも認証情報を取得できない場合、サーバーは起動に失敗します（ログを確認してください）。
  • Jama Connect 自体での Jama API クライアントの権限を確認してください。
• ツールエラー： ツールに渡した引数を確認してください。詳細については、サーバーログ（stderr）を確認してください。
• モックモードが動作しない： JAMA_MOCK_MODE 環境変数が正確に true に設定されていることを確認してください。