Servidor MCP de ODPS

Servidor MCP de solo lectura para Alibaba Cloud MaxCompute.

Modo ASGI

Utilice create_app() para el servidor HTTP. La aplicación expone GET /health, monta la aplicación HTTP estándar de MCP Streamable en /mcp y mantiene / como una ruta de compatibilidad para llamadores antiguos.

Ejemplo:

uvicorn odps_mcp_server.server:create_app --factory

Endpoints:

• Endpoint MCP estándar: http://<host>:<port>/mcp

• Endpoint MCP de compatibilidad: http://<host>:<port>/

• Comprobación de estado: http://<host>:<port>/health

Este servicio expone un endpoint MCP remoto a través de streamable-http para que un agente interno pueda consultar de forma segura las tablas de MaxCompute incluidas en la lista de permitidos.

Entorno

Establezca estas variables de entorno antes de ejecutar el servidor:

• ALIBABA_CLOUD_ACCESS_KEY_ID

• ALIBABA_CLOUD_ACCESS_KEY_SECRET

• ODPS_ENDPOINT

• ODPS_PROJECT

• ODPS_ALLOWLIST_PATH

ODPS_ALLOWLIST_PATH debe apuntar a su archivo de política. Comience con config/allowlist.example.yaml y reemplace los nombres de proyecto y tabla de ejemplo con su lista de permitidos aprobada.

Si desea un flujo de inicio local con un solo clic, copie .env.local.example a .env.local y rellene sus credenciales de ODPS. El archivo es ignorado por git.

Configuración local

Instale las dependencias en un entorno virtual:

python -m venv .venv
.venv\Scripts\activate
pip install -e .

Si prefiere uv, el flujo equivalente es:

uv venv
uv pip install -e .

Archivo de política

El archivo de lista de permitidos controla a qué proyectos y tablas de MaxCompute puede acceder el servidor MCP. Ejemplo:

projects:
  analytics:
    tables:
      sales_orders:
        allowed_columns:
          - order_id
          - order_date

default_limit: 100
max_limit: 200

Ejecutar el servidor MCP

Ejecute el servidor con:

python -m odps_mcp_server.server

El servidor está configurado para iniciar el transporte MCP en modo streamable-http.

Para el desarrollo local en Windows, también puede usar:

.\scripts\start-local-mcp.ps1

Si prefiere un flujo de inicio con un solo clic respaldado por .env.local, use:

.\scripts\start-local-mcp-oneclick.ps1

Integración del agente interno

Su agente interno debe conectarse al endpoint MCP estándar http://<host>:<port>/mcp. La ruta raíz / permanece disponible solo por compatibilidad con versiones anteriores. El servicio expone estas herramientas:

• list_allowed_tables

• describe_table

• preview_table

• run_select_sql

Flujo de agente recomendado:

1. Listar las tablas permitidas.

2. Leer el esquema de una tabla elegida.

3. Previsualizar filas si es necesario.

4. Ejecutar una consulta SELECT filtrada contra la tabla incluida en la lista de permitidos.

Prueba de humo manual

Utilice scripts/manual_smoke_test.py para validar la conectividad y el comportamiento de la política contra un proyecto de MaxCompute que no sea de producción.

Ejemplos:

python scripts/manual_smoke_test.py list-tables --project analytics
python scripts/manual_smoke_test.py describe-table --project analytics --table sales_orders
python scripts/manual_smoke_test.py run-sql --project analytics --sql "SELECT order_id FROM analytics.sales_orders LIMIT 10"

No apunte la prueba de humo a un proyecto exclusivo de producción hasta que se revisen la lista de permitidos y los límites de filas.