ODPS MCP 서버

Alibaba Cloud MaxCompute를 위한 읽기 전용 MCP 서버입니다.

ASGI 모드

HTTP 서버에는 create_app()을 사용하세요. 이 앱은 GET /health를 노출하고, /mcp에 표준 MCP Streamable HTTP 앱을 마운트하며, 이전 호출자를 위한 호환성 경로로 /를 유지합니다.

예시:

uvicorn odps_mcp_server.server:create_app --factory

엔드포인트:

• 표준 MCP 엔드포인트: http://<host>:<port>/mcp

• 호환성 MCP 엔드포인트: http://<host>:<port>/

• 상태 확인: http://<host>:<port>/health

이 서비스는 내부 에이전트가 허용된 MaxCompute 테이블을 안전하게 쿼리할 수 있도록 streamable-http를 통해 원격 MCP 엔드포인트를 노출합니다.

환경

서버를 실행하기 전에 다음 환경 변수를 설정하세요:

• 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 .

정책 파일

허용 목록 파일은 MCP 서버가 액세스할 수 있는 MaxCompute 프로젝트와 테이블을 제어합니다. 예시:

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

default_limit: 100
max_limit: 200

MCP 서버 실행

다음 명령어로 서버를 실행하세요:

python -m odps_mcp_server.server

서버는 streamable-http 모드에서 MCP 전송을 시작하도록 구성되어 있습니다.

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"

허용 목록 및 행 제한이 검토되기 전까지는 스모크 테스트를 운영 전용 프로젝트에 지정하지 마세요.