Taiga MCP Bridge

Taiga MCP Bridge

talhaorak/pytaiga-mcp のコミュニティフォークで、追加機能、CI/CD、継続的なメンテナンスを提供します。

概要

Taiga MCP Bridge は、Taiga のプロジェクト管理プラットフォームと Model Context Protocol（MCP）を接続する強力な統合レイヤーで、AI ツールやワークフローが Taiga のリソースとシームレスに連携できるようにします。

このブリッジは、AI エージェントが以下を行うための包括的なツールとリソースを提供します。

• Taiga でプロジェクト、エピック、ユーザーストーリー、タスク、課題を作成・管理する
• スプリントとマイルストーンを追跡する
• 作業項目を割り当て、更新する
• プロジェクトの成果物に関する詳細情報を照会する
• プロジェクトメンバーと権限を管理する

MCP 標準を使用することで、このブリッジにより AI システムはプロジェクトの状態を文脈として把握し、複雑なプロジェクト管理タスクをプログラムから実行できます。

機能

包括的なリソースサポート

このブリッジは、以下の Taiga リソースに対する完全な CRUD 操作をサポートします。

• プロジェクト：プロジェクトの設定とメタデータを作成、更新、管理します
• エピック：複数のスプリントにまたがる大規模な機能を管理します
• ユーザーストーリー：詳細な要件と受け入れ基準を扱います
• タスク：ユーザーストーリー内の小さな作業単位を追跡します
• 課題：バグ、質問、機能強化のリクエストを管理します
• スプリント（マイルストーン）：期間を区切って作業を計画、追跡します

セキュリティと設定

• 安全な認証情報：認証には環境変数を使用し、認証情報を保護します。パスワードがログやエラーメッセージに表示されることはありません
• 自動認証：TAIGA_USERNAME と TAIGA_PASSWORD の環境変数を設定すると、手動でログインせずにシームレスに起動できます
• 入力検証：許可リストに基づくパラメーター検証により、予期しないデータが Taiga API に渡されるのを防ぎます

レスポンスのフィルタリング

すべてのツールは、レスポンスのサイズを制御して AI のコンテキスト使用量を削減する verbosity パラメーターをサポートします。

レベル	説明	使用例
minimal	基本フィールドのみ（id、ref、subject、status、project）	多数の項目を一覧表示する場合
standard	更新に使用するバージョンを含む一般的なフィールド（デフォルト）	通常の操作
full	API レスポンス全体	デバッグ、詳細情報の確認

例：

# Get minimal response for efficient context usage
stories = client.call_tool("list_user_stories", {
    "project_id": 123,
    "verbosity": "minimal"
})
# Returns: [{"id": 1, "ref": 42, "subject": "...", "status": 1, "project": 123}, ...]

インストール

このプロジェクトでは、高速で信頼性の高い Python パッケージ管理のために uv を使用します。

前提条件

• Python 3.12 以降
• uv パッケージマネージャー

基本インストール

# Clone the repository
git clone https://github.com/TETRA-2023/pytaiga-mcp.git
cd pytaiga-mcp

# Install dependencies
./install.sh

開発用インストール

開発用（テストおよびコード品質ツールを含む）：

./install.sh --dev

手動インストール

手動でインストールする場合：

# Production dependencies only
uv pip install -e .

# With development dependencies
uv pip install -e ".[dev]"

Docker

GHCR からビルド済みイメージをプルします。

docker pull ghcr.io/tetra-2023/pytaiga-mcp:latest

または、ローカルでビルドします。

docker build -t pytaiga-mcp .

環境変数を指定して実行します。

docker run -i --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  ghcr.io/tetra-2023/pytaiga-mcp:latest

stdio の代わりに SSE トランスポートを使用するには、--sse を追加します。

docker run --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  -p 8000:8000 \
  ghcr.io/tetra-2023/pytaiga-mcp:latest --sse

stdio トランスポート用の MCP クライアント設定（.mcp.json）の例：

{
  "mcpServers": {
    "taigaApi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TAIGA_API_URL",
        "-e", "TAIGA_USERNAME",
        "-e", "TAIGA_PASSWORD",
        "ghcr.io/tetra-2023/pytaiga-mcp:latest"
      ]
    }
  }
}

注：stdio トランスポートでは、-t（疑似 TTY）を指定せずに -i（インタラクティブ）を使用してください。-e VAR 形式（=value なし）を使うと、ホスト環境から変数が引き継がれます。

設定

ブリッジは、環境変数または .env ファイルで設定できます。

環境変数	説明	デフォルト
TAIGA_API_URL	Taiga API のベース URL	http://localhost:9000
TAIGA_USERNAME	自動認証に使用する Taiga のユーザー名	（なし）
TAIGA_PASSWORD	自動認証に使用する Taiga のパスワード	（なし）
TAIGA_TRANSPORT	トランスポートモード（stdio または sse）	stdio
LOG_LEVEL	ログレベル	INFO

値を設定するには、プロジェクトのルートに .env ファイルを作成します。

TAIGA_API_URL=https://api.taiga.io/api/v1/
TAIGA_USERNAME=your_username
TAIGA_PASSWORD=your_password
TAIGA_TRANSPORT=stdio
LOG_LEVEL=INFO

セキュリティに関する注意：認証情報は保護され、ログ、エラーメッセージ、スタックトレースに表示されることはありません。TAIGA_USERNAME と TAIGA_PASSWORD を設定すると、サーバーは起動時に自動認証するため、手動でログインする必要はありません。

使用方法

stdio モードの場合

以下の json を Claude App または Cursor の mcp 設定セクションに貼り付けます。

推奨：認証情報が平文で公開されないよう、設定ファイルではなくシェルプロファイルで環境変数を設定してください。

{
    "mcpServers": {
        "taigaApi": {
            "command": "uv",
            "args": [
                "--directory",
                "<path to local pyTaigaMCP folder>",
                "run",
                "src/server.py"
            ],
            "env": {
                "TAIGA_TRANSPORT": "<stdio|sse>",                
                "TAIGA_API_URL": "<Taiga API Url (ex: http://localhost:9000)",
                "TAIGA_USERNAME": "<taiga username>",
                "TAIGA_PASSWORD": "<taiga password>"
            }
        }
}

ブリッジの実行

次のコマンドで MCP サーバーを起動します。

# Default stdio transport
./run.sh

# For SSE transport
./run.sh --sse

または、手動で起動します。

# For stdio transport (default)
uv run python src/server.py

# For SSE transport
uv run python src/server.py --sse

トランスポートモード

サーバーは 2 つのトランスポートモードに対応しています。

1. stdio（標準入力／出力） - ターミナルベースのクライアント向けのデフォルトモード
2. SSE（Server-Sent Events） - サーバープッシュ機能に対応したウェブベースのトランスポート

トランスポートモードは、いくつかの方法で設定できます。

• run.sh または server.py で --sse フラグを使用する（デフォルトは stdio）
• TAIGA_TRANSPORT 環境変数を設定する
• .env ファイルに TAIGA_TRANSPORT=sse を追加する

認証フロー

自動認証（推奨）

TAIGA_USERNAME と TAIGA_PASSWORD の環境変数が設定されている場合、サーバーは起動時に自動認証します。デフォルトのセッションを使用する場合、ツール呼び出しで session_id を省略できます。

# No login needed - uses auto-authenticated default session
projects = client.call_tool("list_projects", {})
stories = client.call_tool("list_user_stories", {"project_id": 123})
new_story = client.call_tool("create_user_story", {
    "project_id": 123,
    "subject": "New feature request"
})

手動セッション管理

複数のセッションが必要な場合や、明示的に制御する場合は、セッションベースのモデルを使用します。

1. ログイン：login ツールを使用して認証します。

   session = client.call_tool("login", {
       "username": "your_taiga_username",
       "password": "your_taiga_password",
       "host": "https://api.taiga.io" # Optional
   })
   # Save the session_id from the response
   session_id = session["session_id"]
   

2. ツールとリソースの使用：すべての API 呼び出しに session_id を含めます。

   # For resources, include session_id in the URI
   projects = client.get_resource(f"taiga://projects?session_id={session_id}")
   
   # For project-specific resources
   epics = client.get_resource(f"taiga://projects/123/epics?session_id={session_id}")
   
   # For tools, include session_id as a parameter
   new_project = client.call_tool("create_project", {
       "session_id": session_id,
       "name": "New Project",
       "description": "Description"
   })
   

3. セッション状態の確認：セッションが引き続き有効かどうかを確認できます。

   status = client.call_tool("session_status", {"session_id": session_id})
   # Returns information about session validity and remaining time
   

4. ログアウト：終了時にログアウトしてセッションを終了できます。

   client.call_tool("logout", {"session_id": session_id})
   

例：プロジェクト作成の完全なワークフロー

エピックとユーザーストーリーを含むプロジェクトを作成する完全な例を示します。

from mcp.client import Client

# Initialize MCP client
client = Client()

# Authenticate and get session ID
auth_result = client.call_tool("login", {
    "username": "admin",
    "password": "password123",
    "host": "https://taiga.mycompany.com"
})
session_id = auth_result["session_id"]

# Create a new project
project = client.call_tool("create_project", {
    "session_id": session_id,
    "name": "My New Project",
    "description": "A test project created via MCP"
})
project_id = project["id"]

# Create an epic
epic = client.call_tool("create_epic", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Authentication",
    "description": "Implement user authentication features"
})
epic_id = epic["id"]

# Create a user story in the epic
story = client.call_tool("create_user_story", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Login",
    "description": "As a user, I want to log in with my credentials",
    "epic_id": epic_id
})

# Logout when done
client.call_tool("logout", {"session_id": session_id})

開発

プロジェクト構成

pytaiga-mcp/
├── src/
│   ├── server.py          # MCP server implementation with tools
│   ├── taiga_client.py    # Taiga API client wrapper
│   └── config.py          # Configuration settings with Pydantic
├── tests/
│   ├── test_server.py     # Unit tests
│   └── test_integration.py # Integration tests
├── .github/workflows/
│   └── ci.yml             # CI pipeline (test, lint, Docker, release)
├── .pre-commit-config.yaml # Pre-commit hooks (ruff, pytest)
├── Dockerfile             # Container image definition
├── pyproject.toml         # Project configuration and dependencies
├── install.sh             # Installation script
├── run.sh                 # Server execution script
└── README.md              # Project documentation

テスト

コミットごとに pre-commit フックが自動的に実行されます（ruff lint、ruff format、単体テスト）。手動で実行するには、次のコマンドを使用します。

# Run pre-commit hooks on all files
uv run pre-commit run --all-files

# Run tests directly
uv run pytest tests/test_server.py -v --tb=short

# Run with coverage reporting
uv run pytest --cov=src

デバッグと調査

デバッグには、同梱されているインスペクターツールを使用します。

# Default stdio transport
./inspect.sh

# For SSE transport
./inspect.sh --sse

# For development mode
./inspect.sh --dev

エラー処理

すべての API 操作は、次の形式で標準化されたエラーレスポンスを返します。

{
  "status": "error",
  "error_type": "ExceptionClassName",
  "message": "Detailed error message"
}

今後の機能

以下の機能を今後のリリースで予定しています。

• セッションの有効期限と自動クリーンアップ
• API 呼び出しのレート制限
• 指数バックオフによる再試行メカニズム
• コネクションプーリング

貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 開発用の依存関係をインストールします（./install.sh --dev）
4. pre-commit フックを設定します（uv run pre-commit install）
5. 変更を加えます
6. 変更をコミットします — pre-commit フックにより、リントとテストが自動的に実行されます
7. ブランチにプッシュします（git push origin feature/amazing-feature）
8. Pull Request を作成します

ライセンス

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

謝辞

• 優れたプロジェクト管理プラットフォームを提供する Taiga
• 標準化された AI 通信フレームワークを提供する Model Context Protocol (MCP)
• このプロジェクトの発展に貢献してくださったすべての方々