K-AIR MCP

Это официальный MCP-сервер, открытый для того, чтобы агент выполнял только чтение из DataHub. Окно одно, а внутри сервер сам различает Postgres (аналитический март) и Tibero (сбор) как источник каталога engine. SQL-строки не принимаются.

По роли он похож на T2SQL·query_execute из robo-meta-api, но сервер не строит SQL — SELECT собирается из аргументов инструмента. Мокап портала POST /mcp как эталон не копируется.

История обновлений: change_log.md

Что делает этот сервис

• Предоставляет агенту инструменты: список таблиц, детали колонок, уникальные значения, ограниченный SELECT, агрегаты.

• Разрешённые таблицы = POST /meta/catalog ∩ таблицы·колонки, реально существующие в исходной системе соответствующего движка.

• HTTP — Streamable HTTP (/mcp) + X-Api-Key. stdio — для IDE на том же ПК.

• ИИ знает только URL MCP и API-ключ. Паролей БД и адреса robo в результатах инструментов нет.

Чего сервис не делает: свободный SQL, DML/DDL, дамп/отправка, операционный Tibero, чтение данных t2s·argus_catalog, разделение MCP по движкам.

Related MCP server: SQLite Read-Only MCP Server

Инструменты

Верхний предел строк 200. Только чтение (default_transaction_read_only), statement_timeout 15 секунд. filters.op: eq, ne, gt, gte, lt, lte, like, in, is_null, is_not_null.

Разделение движков

engine из sources[].engine в /meta/catalog — эталон. Агент движок не выбирает.

Если движок отсутствует или значение неизвестно — исключается из списка. Таблицы Tibero не смешиваются с реально существующими таблицами Postgres, даже если имена совпадают.

Локально есть только Postgres. Если нет подключения к Tibero или JDBC — источники Tibero из каталога в списке не появляются. JDBC JAR в образ не включается.

Конфигурация

app/                 FastMCP 서버 (stdio / Streamable HTTP)
tests/               단위·계약 테스트
docker-compose.yml   네트워크용 http :8110
mcp.cursor.example.json       같은 PC stdio
mcp.cursor.http.example.json  다른 PC HTTP

Предпосылки: сеть robo-meta-api и kair-metadata-platform_control-plane. Слой данных — локальный kair-postgis-16 (хост 5434). Портал·OASIS·операционный Tibero вне рамок этого репозитория.

Запуск

copy .env.example .env
# MCP_API_KEYS · MCP_PG_* 실제 값만 채움. 따옴표 넣지 않음
docker compose up -d --build
curl.exe -fsS http://127.0.0.1:8110/health

Здоровье: {"status":"ok","server":"kair-mcp-query","transport":"streamable-http","engines":["postgres"]}

CLI на том же ПК (stdio, по умолчанию):

python -m app.main

Контейнер HTTP:

python -m app.main --transport http

Регистрация MCP

Тот же ПК (рекомендуется stdio). Контейнер должен быть запущен. URL·ключ·.env не вставляются.

{
  "mcpServers": {
    "kair-query": {
      "command": "docker",
      "args": ["exec", "-i", "kair-mcp-query", "python", "-m", "app.main", "--transport", "stdio"]
    }
  }
}

Другой ПК (Streamable HTTP). Пароль БД не вставляется.

{
  "mcpServers": {
    "kair-query": {
      "url": "http://<MCP띄운PC의IP>:8110/mcp",
      "headers": {
        "X-Api-Key": "<MCP_API_KEYS 값만>"
      }
    }
  }
}

mcp.json — это JSON, поэтому ключи оборачиваются в "…". Значения, которые получает сервер, — ключи без кавычек.

Настройки

Скопируйте .env.example в .env, исключённый из Git. Пароли и API-ключи не хранятся в коде и в документах, отслеживаемых Git.

Эталон подключения — SourceDbConn в OA. Локально — env/CLI.

Тесты

python -m pytest tests -q

Известные проблемы и ограничения

Связанное

• robo-meta-api — POST /meta/catalog

• K-AIR-metadata-platform — Serving t2s_*

• K-AIR-Portal — далее эталонное окно POST /api/v1/mcp, реестр ключей