ODPS MCP Server

MCP-сервер с правами только на чтение для Alibaba Cloud MaxCompute.

Режим ASGI

Используйте create_app() для HTTP-сервера. Приложение предоставляет GET /health, монтирует стандартное HTTP-приложение MCP Streamable по адресу /mcp и сохраняет / в качестве пути совместимости для старых клиентов.

Пример:

uvicorn odps_mcp_server.server:create_app --factory

Конечные точки:

• Стандартная конечная точка MCP: http://<host>:<port>/mcp

• Конечная точка совместимости MCP: http://<host>:<port>/

• Проверка работоспособности: http://<host>:<port>/health

Этот сервис предоставляет удаленную конечную точку MCP через streamable-http, чтобы внутренний агент мог безопасно запрашивать разрешенные таблицы MaxCompute.

Окружение

Установите следующие переменные окружения перед запуском сервера:

• ALIBABA_CLOUD_ACCESS_KEY_ID

• ALIBABA_CLOUD_ACCESS_KEY_SECRET

• ODPS_ENDPOINT

• ODPS_PROJECT

• ODPS_ALLOWLIST_PATH

ODPS_ALLOWLIST_PATH должен указывать на ваш файл политики. Начните с config/allowlist.example.yaml и замените примеры имен проектов и таблиц на ваш утвержденный список разрешенных объектов.

Если вы хотите использовать локальный запуск в один клик, скопируйте .env.local.example в .env.local и введите свои учетные данные ODPS. Файл игнорируется git.

Локальная настройка

Установите зависимости в виртуальном окружении:

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

Если вы предпочитаете uv, аналогичный процесс выглядит так:

uv venv
uv pip install -e .

Файл политики

Файл списка разрешенных объектов контролирует, к каким проектам и таблицам MaxCompute может обращаться MCP-сервер. Пример:

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

default_limit: 100
max_limit: 200

Запуск MCP-сервера

Запустите сервер с помощью:

python -m odps_mcp_server.server

Сервер настроен на запуск транспорта MCP в режиме streamable-http.

Для локальной разработки в Windows вы также можете использовать:

.\scripts\start-local-mcp.ps1

Если вы предпочитаете запуск в один клик с использованием .env.local, используйте:

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

Интеграция с внутренним агентом

Ваш внутренний агент должен подключаться к стандартной конечной точке MCP http://<host>:<port>/mcp. Корневой путь / остается доступным только для обратной совместимости. Сервис предоставляет следующие инструменты:

• list_allowed_tables

• describe_table

• preview_table

• run_select_sql

Рекомендуемый порядок работы агента:

1. Получить список разрешенных таблиц.

2. Прочитать схему выбранной таблицы.

3. Предварительно просмотреть строки, если необходимо.

4. Выполнить отфильтрованный запрос SELECT к таблице из списка разрешенных.

Ручное дымовое тестирование

Используйте scripts/manual_smoke_test.py для проверки подключения и поведения политики в проекте MaxCompute, не являющемся рабочим.

Примеры:

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"

Не направляйте дымовой тест на рабочий проект, пока не будут проверены список разрешенных объектов и ограничения на количество строк.