K-AIR MCP

Es el servidor MCP oficial que se abre para que los agentes solo realicen consultas al datahub. Hay una única puerta de entrada y, en el origen del catálogo, el engine distingue internamente entre Postgres (mart de análisis) y Tibero (recopilación). No recibe cadenas SQL.

Su rol es similar al de T2SQL·query_execute de robo-meta-api, pero el servidor no genera SQL; ensambla el SELECT a partir de los argumentos de la herramienta. No replica el mock del portal POST /mcp como versión canónica.

Historial de actualizaciones: change_log.md

Qué hace este servicio

• Proporciona al agente herramientas de listado de tablas, detalle de columnas, valores únicos, SELECT limitado y agregación.

• Tablas permitidas = POST /meta/catalog ∩ tablas y columnas que realmente existen en el origen de ese motor.

• HTTP usa Streamable HTTP (/mcp) + X-Api-Key. stdio es para IDE en el mismo PC.

• La IA solo conoce la URL del MCP y la API Key. La contraseña de la BD y la dirección de robo no aparecen en los resultados de las herramientas.

Lo que no hace: SQL libre, DML/DDL, volcado/envío, Tibero de operación, consulta de datos de t2s·argus_catalog, ni dividir el MCP por motor.

Related MCP server: governed-mcp

Herramientas

Límite de filas 200. Solo lectura (default_transaction_read_only), statement_timeout 15 segundos. filters.op: eq, ne, gt, gte, lt, lte, like, in, is_null, is_not_null.

Distinción de motores

El sources[].engine de /meta/catalog es la fuente canónica. El agente no elige el motor.

Si el motor no existe o es un valor desconocido, se excluye de la lista. Aunque una tabla de Tibero tenga el mismo nombre que una tabla real de Postgres, no se mezclan.

En local solo hay Postgres. Si no hay conexión ni JDBC a Tibero, las fuentes Tibero del catálogo no aparecen en la lista. Los JAR de JDBC no se incluyen en la imagen.

Configuración

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

Premisa: red de robo-meta-api y kair-metadata-platform_control-plane. El lado de datos es el kair-postgis-16 local (host 5434). El portal, OASIS y el Tibero de operación están fuera del alcance de este repositorio.

Ejecución

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

Salud: {"status":"ok","server":"kair-mcp-query","transport":"streamable-http","engines":["postgres"]}

CLI en el mismo PC (stdio, por defecto):

python -m app.main

HTTP en contenedor:

python -m app.main --transport http

Registro en MCP

Mismo PC (se recomienda stdio). El contenedor debe estar levantado. No se incluyen URL, clave ni .env.

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

Otro PC (Streamable HTTP). No se incluye la contraseña de la BD.

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

mcp.json es JSON, así que las claves van entre "…". Los valores que recibe el servidor son claves sin comillas.

Ajustes

Copie .env.example a .env, que está excluido de Git. Las contraseñas y API Keys no se guardan en el código ni en documentos rastreados por Git.

La conexión canónica es SourceDbConn en OA. En local es env/CLI.

Pruebas

python -m pytest tests -q

Problemas y limitaciones conocidos

Relacionado

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

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

• K-AIR-Portal — Futura puerta canónica POST /api/v1/mcp, registro de claves