Alicloud Ops MCP

🚀 アリババクラウドオペレーションMCPサーバー

このサーバーは、Amazon Q CLI用のアリババクラウドオペレーションMCPサーバーです。ECS、VPC、RDS、OSS、CloudMonitor、OOSなどのサービスをサポートしています。

English | 中文

🚀 クイックスタート

システム要件

• Python 3.10+ (uvによって自動管理されます)
• uv - Pythonパッケージとプロジェクトマネージャー
• アリババクラウドアクセス証憑

ステップ1: uvのインストール

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# またはpipを使用
pip install uv

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

ステップ2: プロジェクトのクローン

git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp

ステップ3: 一括インストール

# インストールスクリプトを実行（推奨）
./install.sh

# または手動でインストール
uv sync
cp .env.example .env
# .envファイルを編集し、あなたのアリババクラウド証憑を入力

ステップ4: 環境変数の設定

.envファイルを編集します。

ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
ALIBABA_CLOUD_REGION="cn-beijing"

ステップ5: インストールの検証

# 検証スクリプトを実行
uv run python verify_setup.py

# サーバーの起動をテスト
uv run python complete_fastmcp_server.py

"Server is ready to accept connections." と表示されれば、インストールは成功です。

💻 Amazon Q CLIの設定

~/.aws/amazonq/mcp.jsonに以下の設定を追加します。

{
  "mcpServers": {
    "alibaba-cloud-ops-mcp-server": {
      "timeout": 30000,
      "command": "uv",
      "args": [
        "--directory",
        "/絶対パス/to/alicloud-ops-mcp",
        "run",
        "python",
        "complete_fastmcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

⚠️ 重要提示

/絶対パス/to/alicloud-ops-mcp をプロジェクトの実際の絶対パスに置き換えてください。

設定例

プロジェクトが /home/user/alicloud-ops-mcp にあると仮定します。

{
  "mcpServers": {
    "alibaba-cloud-ops-mcp-server": {
      "timeout": 30000,
      "command": "uv",
      "args": [
        "--directory",
        "/home/user/alicloud-ops-mcp",
        "run",
        "python",
        "complete_fastmcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

✨ 主な機能

🔧 開発説明

プロジェクト構造

alicloud-ops-mcp/
├── pyproject.toml              # プロジェクト設定と依存関係
├── requirements.txt            # 依存関係リスト（互換性）
├── complete_fastmcp_server.py  # メインサーバーファイル
├── alibaba_cloud_ops_mcp_server/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py              # サーバーの核心ロジック
│   ├── config.py              # 設定管理
│   └── tools/                 # 各サービスのツール
│       ├── __init__.py
│       ├── api_tools.py       # 汎用APIツール
│       ├── cms_tools.py       # CloudMonitorツール
│       ├── common_api_tools.py # 共通APIツール
│       ├── oos_tools.py       # OOSツール
│       └── oss_tools.py       # OSSツール
├── .env.example               # 環境変数のテンプレート
├── .env                       # 環境変数（作成が必要）
├── install.sh                 # インストールスクリプト
├── verify_setup.py            # 検証スクリプト
├── README.md                  # 日本語ドキュメント
├── README_EN.md               # 英語ドキュメント
└── LICENSE

uvを使用した開発

# 開発用依存関係のインストール
uv sync --dev

# テストの実行
uv run pytest

# サーバーの実行
uv run python complete_fastmcp_server.py

# 新しい依存関係の追加
uv add package-name

# 開発用依存関係の追加
uv add --dev package-name

# 依存関係の更新
uv sync --upgrade

# 依存関係ツリーの表示
uv tree

Pythonバージョン管理

プロジェクトは pyproject.toml でPythonバージョンの要件を指定しています。

requires-python = ">=3.10"

uvは自動的に以下のことを行います。

• 適切なPythonバージョンを検出してインストール
• 隔離された仮想環境を作成
• すべての依存関係を管理
• クロスプラットフォームの互換性を確保

🐞 トラブルシューティング

一般的な問題と解決策

1. Permission denied (os error 13)

原因：設定エラーまたは権限問題

解決策：

# uvコマンドを使用し、直接のpythonパスではないことを確認
uv run python complete_fastmcp_server.py

# プロジェクトパスが正しいことを確認
pwd

# スクリプトに実行権限があることを確認
chmod +x complete_fastmcp_server.py

2. Pythonバージョンの互換性問題

エラーメッセージ：Could not find a version that satisfies the requirement fastmcp>=2.8.0

解決策：

# uvが自動的にPythonバージョンを処理するため、手動でのインストールは不要
uv sync

# 依然として問題がある場合は、キャッシュをクリアして再インストール
uv clean
uv sync

3. 依存関係のインストール失敗

解決策：

# キャッシュをクリアして再インストール
uv clean
uv sync

# 詳細なエラーメッセージを表示
uv sync --verbose

4. 環境変数が読み込まれない

解決策：

# .envファイルが存在し、形式が正しいことを確認
ls -la .env
cat .env

# 環境変数の形式を確認
uv run python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print('Access Key ID:', os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID', 'Not found'))
print('Region:', os.getenv('ALIBABA_CLOUD_REGION', 'Not found'))
"

5. MCPサーバーが起動しない

解決策：

# Amazon Q CLIの設定を確認
cat ~/.aws/amazonq/mcp.json

# パスが正しいことを確認
ls -la /絶対パス/to/alicloud-ops-mcp/complete_fastmcp_server.py

# サーバーを直接起動してテスト
cd /絶対パス/to/alicloud-ops-mcp
uv run python complete_fastmcp_server.py

デバッグモード

詳細なログを有効にするには：

# 環境変数を設定してデバッグを有効にする
export FASTMCP_LOG_LEVEL=DEBUG
uv run python complete_fastmcp_server.py

# または.envファイルに設定する
echo "FASTMCP_LOG_LEVEL=DEBUG" >> .env

設定の検証

完全な環境チェックを実行するには：

# 検証スクリプトを実行
uv run python verify_setup.py

# 特定のコンポーネントをチェック
uv run python -c "
import sys
print(f'Python version: {sys.version}')

try:
    import fastmcp
    print(f'FastMCP version: {fastmcp.__version__}')
except ImportError as e:
    print(f'FastMCP import error: {e}')

try:
    from alibaba_cloud_ops_mcp_server import server
    print('Server module loaded successfully')
except ImportError as e:
    print(f'Server module error: {e}')
"

⚙️ パフォーマンス最適化

起動最適化

# Pythonバイトコードを事前コンパイル
uv run python -m compileall .

# より高速な起動オプションを使用
uv run python -O complete_fastmcp_server.py

メモリ最適化

.envファイルに以下を追加します。

# メモリ使用量を制限
PYTHONHASHSEED=0
PYTHONDONTWRITEBYTECODE=1

🤝 コントリビューションガイド

1. プロジェクトをForkする
2. 機能ブランチを作成する (git checkout -b feature/amazing-feature)
3. 開発用依存関係をインストールする (uv sync --dev)
4. テストを実行する (uv run pytest)
5. 変更をコミットする (git commit -m 'Add some amazing feature')
6. ブランチにプッシュする (git push origin feature/amazing-feature)
7. Pull Requestを作成する

開発環境の設定

# リポジトリをクローン
git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp

# 開発用依存関係をインストール
uv sync --dev

# pre-commit hooksを設定
uv run pre-commit install

# テストを実行
uv run pytest

# コードのフォーマット
uv run black .
uv run isort .

# 型チェック
uv run mypy .

📄 ライセンス

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

🆘 サポート

問題が発生した場合は、以下の手順を試してください。

1. トラブルシューティング セクションを確認する
2. uv run python verify_setup.py を実行して環境をチェックする
3. GitHub Issues を確認する
4. 新しいIssueを作成して問題を報告する

ヘルプの取得

• 📖 ドキュメント
• 🐛 バグ報告
• 💡 機能リクエスト
• 💬 ディスカッション

📋 更新履歴

v0.9.2 (2024-12-XX)

• ✨ uvを使用したパッケージ管理をサポート
• 🚀 インストールと設定の流れを簡素化
• 🐛 エラー処理とデバッグ情報を改善
• 📚 ドキュメントとトラブルシューティングガイドを更新
• 🔧 環境検証スクリプトを追加
• 📦 一括インストールスクリプトを追加

v0.9.1

• 🔧 依存関係のバージョン互換性問題を修正
• 📝 ドキュメント構造を改善
• 🐛 環境変数の読み込み問題を修正

v0.9.0

• 🎉 初期バージョンをリリース
• ✅ ECS、VPC、RDS、OSS、CloudMonitor、OOSサービスをサポート
• 🔐 アリババクラウドアクセス証憑の設定をサポート
• 📖 完全なドキュメントとサンプルを提供

🙏 謝辞

すべての貢献者とコミュニティメンバーのサポートに感謝します！

⭐ このプロジェクトが役に立った場合は、Starをしてください！