oci-mcp-server

oci-mcp-server

プログラムからのクライアントと LLM を活用するクライアントの両方に対応した、Oracle Cloud Infrastructure（OCI）の API Gateway を管理する Python MCP（Multi-Client Protocol）サーバーです。

---

機能

• 指定した OCI コンパートメント内の API Gateway を一覧表示します。
• 特定の API Gateway の 詳細を取得します。
• LLM エージェントやその他のクライアントと簡単に統合できる MCP stdio トランスポートを備えています。
• 自然言語で OCI API Gateway リソースを操作できる LlamaIndex/Ollama クライアントを備えています。

---

クイックスタート

1. 前提条件

• Python 3.11（必須）
• uv（高速な Python パッケージ／依存関係マネージャー）
• API Gateway にアクセスできる OCI アカウント
• OCI セッション認証ファイル（~/.oci/sessions/DEFAULT/token および oci_api_key.pem）

2. uv をインストールする

curl -Ls https://astral.sh/uv/install.sh | sh

または、PyPI からインストールします。

# With pip.
pip install uv

# Or pipx.
pipx install uv

スタンドアロンインストーラーでインストールした場合、uv は最新バージョンに自己更新できます。

uv self-update

その他の方法については、uv のインストールに関するドキュメントをご覧ください。

3. 仮想環境を作成して有効化する

uv venv --python 3.11
source .venv/bin/activate

4. 依存関係をインストールする

uv pip install -r pyproject.toml

または、uv を直接使う場合：

uv pip install -e .

---

Cursor と MCP の統合

5. Cursor をインストールする

Cursor は、MCP サーバーとネイティブに連携できる AI 搭載コードエディターです。

Cursor をインストールするには：

• お使いのプラットフォーム（macOS、Windows、Linux）向けの Cursor を公式サイトからダウンロードしてインストールします。
• お使いの OS のインストール手順に従います。

6. mcp.json の設定を更新する

Cursor をカスタム MCP サーバーに接続するには、プロジェクトのルートにある mcp.json ファイルを更新するか、新規作成する必要があります。まず、src/mcp_template.json にあるテンプレートを使用してください。

手順

1. Cursor > Settings... > Cursor Settings に移動して Cursor の設定を開きます。

2. MCP > + Add new global MCP server を選択します。

vi ~/.cursor/mcp.json から mcp.json を編集することもできます。

手順：

1. src/mcp_template.json の内容を ~/.cursor/mcp.json（またはエディターで開いた mcp.json）にコピーします。

2. mcp.json を編集し、パスを更新します。

   • 仮想環境を使用している場合は、<path to Python> を Python 3.11 実行ファイルの絶対パスに置き換えます。
   • <path to server.py> を server.py スクリプトの絶対パスに置き換えます。

3. ファイルを保存します。これで Cursor が MCP サーバーを検出して接続できるようになります。

---

設定

必要に応じて src/config.py を編集し、OCI コンパートメントとゲートウェイの OCID、リージョン、プロファイルを設定します。

PROFILE_NAME = 'DEFAULT'
REGION = 'ap-mumbai-1'
SERVICE_ENDPOINT = '<SERVICE ENDPOINT>'
COMPARTMENT_ID = '<COMPARTMENT_ID>'
GATEWAY_ID = '<GATEWAY_ID>' # For Programmatic Client

~/.oci/sessions/DEFAULT/ に有効な OCI セッションファイルが必要です。

次のようなコマンドで認証できます：oci session authenticate --tenancy-name <TENANCY_NAME> --profile-name DEFAULT --region $REGION

---

MCP サーバーの実行

プロジェクトのルートから実行します（サーバーは別のターミナルで実行するのがおすすめです）。

python src/server.py

これにより、MCP サーバーが stdio トランスポートで起動し、次のツールを公開します。

• list_gateways_tool(compartment_id)
• get_gateway_tool(gateway_id)

---

Cursor クライアント（エージェントモード）

Cursor では MCP サーバーを実行する必要はありません。Cursor Agent が mcp.json で指定されたサーバーリソースからサーバーを実行します。

MCP サーバー設定の例については、src/mcp_template.json をご覧ください。

{
    "mcpServers": {
        "oci_api_gateway": { 
            "command": "<absolute path to Python (preferably from .venv)>",
            "args": [
                "<absolute path to server.py>"
            ]
        }
    }
}

---

Cursor エディターでは、自然言語のクエリを使って MCP サーバーとやり取りできるようになりました。

たとえば、特定のコンパートメント内のすべてのゲートウェイを一覧表示するには、次のように入力します。

例：

list all the gateways in ocid1.compartment.oc1..aaaaaaaai2zzsg.............................m4pjq

Cursor エージェントがリクエストを処理し、MCP サーバーから結果を返します。

プログラムによるクライアント

プログラムによるクライアントを使用すると、AI エージェントを介さずに、Python コードでカスタム MCP ツールを直接テストして操作できます。 ツールの機能を確認したり、サーバーの応答を簡単にスクリプトでデバッグしたりするのに便利です。

簡単な例については、src/client_stdio.py を参照してください。

python src/client_stdio.py

この例では、次の処理を行います。

• MCP サーバーに接続します
• 使用可能なツールを一覧表示します
• list_gateways_tool メソッドと get_gateway_tool メソッドを呼び出して、結果を出力します

---

開発中：LlamaIndex + Ollama クライアント

LlamaIndex + Ollama クライアントは開発中（WIP）で、セルフホスト可能な LLM エージェントを使用して、MCP ツールと自然言語でやり取りできるようにすることを目指しています。

LlamaIndex と Ollama（Llama 3.2）を使用する高度な例については、src/client_llama_react.py を参照してください。

• llama3.2 モデルを使用して、Ollama がローカルで実行されていることを確認してください。
• 必要に応じて、client_llama_react.py の server_params パスを編集してください。

python src/client_llama_react.py

この例では、次の処理を行います。

• MCP サーバーに接続します
• ツールを LlamaIndex 用にラップします
• LLM を使用して自然言語クエリを実行します

---

開発

• すべてのソースコードは src/ ディレクトリにあります。
• 依存関係は pyproject.toml で管理されています。
• 新しいツールを追加するには、src/server.py を編集し、ゲートウェイのリソースに関するロジックを src/gateway_services.py に実装してください。

---

トラブルシューティング

• OCI セッションファイルが存在し、有効であることを確認してください。
• Python 3.11 と提供されている仮想環境を使用してください。
• LlamaIndex/Ollama を使用する場合は、Ollama サーバーが実行中で、アクセス可能であることを確認してください。