K-AIR MCP

这是供代理仅对数据枢纽进行查询而开放的官方 MCP 服务器。入口只有一个，目录源 engine 会在内部区分 Postgres（分析数据集市）和 Tibero（采集）。不接受 SQL 字符串。

与 robo-meta-api 的 T2SQL·query_execute 角色类似，但服务器不生成 SQL，而是通过工具参数组装 SELECT。不复制门户 POST /mcp 原型作为正本。

更新历史： change_log.md

该服务的工作内容

• 向代理提供表列表·列详情·唯一值·受限 SELECT·聚合工具。

• 允许的表 = POST /meta/catalog ∩ 对应引擎数据源中实际存在的表·列。

• HTTP 采用 Streamable HTTP（/mcp）+ X-Api-Key。stdio 用于同一台 PC 上的 IDE。

• AI 只知道 MCP URL 和 API Key。DB 密码·robo 地址不会出现在工具结果中。

不做的事：自由 SQL、DML/DDL、dump/发送、运营 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。

引擎区分

/meta/catalog 的 sources[].engine 是正本。代理不选择引擎。

引擎缺失或为未知值时，从列表中排除。即使 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"]}

同一台 PC 上的 CLI（stdio，默认）：

python -m app.main

容器 HTTP：

python -m app.main --transport http

MCP 注册

同一台 PC（推荐 stdio）。容器必须处于运行状态。不填写 URL·密钥·.env。

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

其他 PC（Streamable HTTP）。不填写 DB 密码。

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

mcp.json 是 JSON，因此密钥需要用 "…" 包裹。服务器接收的值是不带引号的密钥。

设置

将 .env.example 复制为 Git 排除的 .env。密码·API Key 不存储在代码和 Git 跟踪的文档中。

连接正本在 OA 中是 SourceDbConn。本地使用 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，密钥台账