oci-mcp-server

oci-mcp-server

一个用于管理 Oracle Cloud Infrastructure（OCI）API Gateway 的 Python MCP（Multi-Client Protocol）服务，支持程序化客户端和由 LLM 驱动的客户端。

---

功能

• 列出 API Gateway：列出指定 OCI 区间中的 API Gateway。
• 获取详情：获取指定 API Gateway 的详细信息。
• MCP stdio 传输：便于与 LLM Agent 和其他客户端集成。
• LlamaIndex/Ollama 客户端：通过自然语言与 OCI API Gateway 资源交互。

---

快速入门

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 是一款由 AI 驱动、可原生与 MCP 服务交互的代码编辑器。

安装 Cursor：

• 从官方网站下载适用于你平台（macOS、Windows、Linux）的 Cursor 并安装。
• 按照适用于你操作系统的安装说明进行操作。

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

这将通过 stdio 传输启动 MCP 服务，并提供以下工具：

• list_gateways_tool(compartment_id)
• get_gateway_tool(gateway_id)

---

Cursor 客户端（Agent 模式）

无需为 Cursor 运行 MCP 服务。Cursor Agent 会从 mcp.json 中提供的服务资源启动它。

请参阅 src/mcp_template.json，了解 MCP 服务配置示例：

{
    "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 Agent 会处理你的请求，并返回 MCP 服务的结果。

程序化客户端

程序化客户端允许你直接使用 Python 代码测试和调用自定义 MCP 工具，无需使用 AI Agent。 它适用于通过简单、可脚本化的方式验证工具功能并调试服务响应。

参见 src/client_stdio.py 中的简单示例：

python src/client_stdio.py

此示例将：

• 连接到 MCP 服务
• 列出可用工具
• 调用 list_gateways_tool 和 get_gateway_tool 方法并打印结果

---

开发中：LlamaIndex + Ollama 客户端

LlamaIndex + Ollama 客户端仍在开发中（WIP），旨在通过可自托管的大模型 Agent 实现与 MCP 工具的自然语言交互

参见 src/client_llama_react.py 中使用 LlamaIndex 和 Ollama（Llama 3.2）的进阶示例：

• 确保本地已运行 Ollama，且已安装 llama3.2 模型。
• 如有需要，请编辑 client_llama_react.py 中的 server_params 路径。

python src/client_llama_react.py

此示例将：

• 连接到 MCP 服务
• 将工具封装为 LlamaIndex 工具
• 使用大模型运行自然语言查询

---

开发

• 所有源代码都位于 src/ 目录中。
• 依赖项通过 pyproject.toml 管理。
• 要添加新工具，请编辑 src/server.py，并在 src/gateway_services.py 中实现相关逻辑（用于网关资源）。

---

故障排除

• 确保 OCI 会话文件存在且有效。
• 使用 Python 3.11 和提供的虚拟环境。
• 对于 LlamaIndex/Ollama，请确保 Ollama 服务正在运行且可访问。