Allstacks MCP Server

🚀 Allstacks MCPサーバー

HTTP基本認証を使用してAllstacks APIにAI対応でアクセスできる包括的なモデルコンテキストプロトコル（MCP）サーバーです。

🚀 クイックスタート

このMCPサーバーはAllstacksとの包括的なやり取りのために、12のカテゴリーにまとめられた208以上のツールを提供します。以下に、サーバーの起動方法や使用方法を説明します。

✨ 主な機能

包括的なAPIカバレッジ

すべてのツールは公式のAllstacks OpenAPI仕様に基づいて検証されており、以下の特徴を備えています。

• ✅ すべてのエンドポイントが正しいパスとパラメータを使用している
• ✅ 公式のAPIドキュメントからの詳細なパラメータ説明
• ✅ 適切なエラーハンドリングと検証
• ✅ HTTP基本認証のサポート
• ✅ パフォーマンス向上のための非同期/待機機能

モジュール化されたアーキテクチャ

ツールはAllstacks APIの構造に合わせて論理的なカテゴリーに整理されています。

• ナビゲーションや理解が容易
• 関心事の明確な分離
• すべてのツールに一貫したパターンがある
• OpenAPI参照で十分にドキュメント化されている

充実したツール説明

各ツールには以下の情報が含まれています。

• 目的とユースケース
• 必須およびオプションのパラメータ
• 期待される戻り値の形式
• OpenAPIエンドポイントの参照
• サンプルの使用パターン

📦 インストール

1. このリポジトリをクローンします。
2. uvを使用して依存関係をインストールします。

   uv sync
   

🔒 認証とセキュリティ

必要な資格情報

サーバーはAllstacks APIに接続するためにHTTP基本認証を使用します。以下の情報が必要です。

• ユーザー名：あなたのAllstacksのユーザー名またはメールアドレス
• パスワード：あなたのAllstacksのパスワードまたはAPIキー
• ベースURL：（オプション）デフォルトはhttps://api.allstacks.com/api/v1/

🔒 セキュリティのベストプラクティス

資格情報の管理

⚠️ 重要：あなたの資格情報はあなたのAllstacksアカウントへの完全なアクセス権を与えます。

1. 環境変数を使用する（推奨）

   export ALLSTACKS_USERNAME="your-username"
   export ALLSTACKS_PASSWORD="your-api-key"
   

2. 可能な場合はパスワードの代わりにAllstacks APIキーを使用する
   • Allstacksアカウントの設定からAPIキーを生成します。
   • APIキーはパスワードを変更することなく取り消すことができます。
3. 資格情報をバージョン管理にコミットしない
   • MCPクライアントの設定ファイルに資格情報が含まれる場合があります。
   • 設定ファイルを.gitignoreに追加してください。
4. 資格情報を定期的に更新することでセキュリティを強化します。

プロセスのセキュリティ

注意：コマンドライン引数（--username、--password）はプロセスリストに表示されます。本番環境では以下の方法を検討してください。

• 環境変数を使用する
• 安全な設定ファイルを使用する
• シークレット管理システムを使用する

データアクセスとプライバシー

このMCPサーバーはAllstacks APIへのパススルーとして機能します。

• ✅ あなたの資格情報を保存またはログに記録しません。
• ✅ APIレスポンスをキャッシュしません。
• ✅ ローカルにデータを保存しません。
• ✅ APIデータを変更せずにそのまま返します。

AIアクセス：AIアシスタント（例：Claude）と一緒に使用する場合、AIは以下にアクセスできます。

• あなたのAllstacks資格情報を通じてアクセス可能なすべてのデータ
• あなたのAllstacksユーザーアカウントと同じ権限
• （あなたの権限に応じて）リソースの作成、変更、削除が可能

推奨事項：AIアクセスには制限付きの権限を持つ専用のAllstacksアカウントを使用することを検討してください。

💻 使用例

サーバーの起動

uv run server.py --username YOUR_USERNAME --password YOUR_PASSWORD

コマンドラインオプション:

• --username または -u：HTTP基本認証のユーザー名（必須）
• --password または -p：HTTP基本認証のパスワード（必須）
• --base-url または -b：デフォルトのAPIベースURLを上書きする（デフォルト：https://api.allstacks.com/api/v1/）

MCPクライアントの設定

MCPクライアントの設定ファイル（例：Claude Desktopの claude_desktop_config.json）に以下を追加します。

{
    "mcpServers": {
        "allstacks": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/allstacks-mcp",
                "run",
                "server.py",
                "--username",
                "YOUR_USERNAME",
                "--password",
                "YOUR_PASSWORD"
            ]
        }
    }
}

重要な注意事項:

• /ABSOLUTE/PATH/TO/allstacks-mcp をこのディレクトリの完全パスに置き換えてください。
• YOUR_USERNAME と YOUR_PASSWORD をあなたの実際の資格情報に置き換えてください。
• macOSでは、uv は通常 ~/.local/bin/uv にあります。PATHに含まれていることを確認するか、完全パスを使用してください。
• Claude DesktopはシェルのPATHを継承しないため、uv の完全パスを使用する方が確実です。

代替設定（直接Pythonを使用する場合）

仮想環境から直接Pythonを使用する場合は、以下の設定を使用します。

{
    "mcpServers": {
        "allstacks": {
            "command": "/ABSOLUTE/PATH/TO/allstacks-mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/allstacks-mcp/server.py",
                "--username",
                "YOUR_USERNAME",
                "--password",
                "YOUR_PASSWORD"
            ]
        }
    }
}

基本的な使用法

GMDTSメトリクスデータの取得

# Get Generated Metric Data Time Series (GMDTS)
get_gmdts_data(
    project_id=123,
    metric_type="Velocity",
    start_date=1704067200000,
    end_date=1706745600000
)

フィルタリングを使用したワークアイテムの一覧表示

# List service items with filtering
list_service_items(
    item_type="CARD",
    limit=100,
    offset=0
)

AIレポートの作成

# Generate AI analysis report
create_ai_report(
    org_id=456,
    report_type="project_health",
    project_id=123
)

ワークバンドルの予測

# Get Monte Carlo forecast for work bundle
get_work_bundle_forecast(
    project_id=123,
    bundle_id=789,
    confidence_level=80
)

📚 ドキュメント

API互換性

このサーバーは公式のAllstacks API v1仕様に基づいて構築されており、以下の機能を備えています。

• 非管理者用エンドポイントのみ（破壊的な操作はなし）
• 適切なリソースに対する完全なCRUD操作
• 効率化のための一括操作
• 適切なページネーションサポート
• クエリパラメータの検証

開発

新しいツールの追加

1. allstacks_mcp/tools/ ディレクトリ内にツールファイルを作成または更新します。
2. 既存のツール登録パターンに従います。
3. OpenAPI参照を含む完全なドキュメント文字列を追加します。
4. モジュールを allstacks_mcp/tools/__init__.py に追加します。
5. server.py の register_all_tools() 関数でツールを登録します。

テスト

# Run the server in development mode
uv run server.py --username test_user --password test_pass --base-url https://api-dev.allstacks.com/api/v1/

📄 ライセンス

MIT

サポート

Allstacks APIに関する問題や質問は、Allstacksチームにお問い合わせください。 このMCPサーバーに関する特定の問題は、リポジトリにイシューを登録してください。