Skip to main content
Glama

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: Governor SQL MCP

工具

工具

作用

list_tables

允许的表列表。可选 schema_name。响应中包含 engine

describe_table

列类型·主键·注释。没有的韩文说明留空

get_distinct_values

允许列的 DISTINCT。最多 200

query_table

组装 SELECT。columns、filters {column,op,value}、order_by {column,dir}

aggregate_table

count/sum/avg/max/min。总行数使用 func=count 且不指定 column

行数上限 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 是正本。代理不选择引擎。

目录 engine

数据源

postgresql / postgres / postgis

分析数据集市(本地为 kair-postgis-16)

tibero / oracle

采集 Tibero。OA 中有时会写成 oracle

引擎缺失或为未知值时,从列表中排除。即使 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 跟踪的文档中。

变量

作用

MCP_API_KEYS

HTTP X-Api-Key。本地冒烟测试密钥。不是门户的 dh_·tm_po_api_key

MCP_PG_HOST / PORT / DB / USER / PASSWORD

数据集市 SELECT 账户。默认主机 host.docker.internal,端口 5434

ROBO_META_URL

POST /meta/catalog。默认 http://robo-meta-api:8100

MCP_ROW_LIMIT

行数上限。服务器截断为 200

MCP_TB_*

采集 Tibero。仅在存在连接时

连接正本在 OA 中是 SourceDbConn。本地使用 env/CLI。

测试

python -m pytest tests -q

已知问题·限制

项目

说明

状态

Tibero 运行

有方言(FETCH FIRST)·引擎分支。无 JDBC 连接

采集 SID·JAR 到位后继续

门户密钥·审计

tm_po_api_key / th_po_api_call / 等级·使用申请

未实现。本地密钥待废弃

自由 SQL

Gemini 反馈中的 execute_read_only_sql

不加入

行数上限 1000

Gemini 反馈

不适用。保持 200

相关

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

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

  • K-AIR-Portal — 后续正本入口 POST /api/v1/mcp,密钥台账

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to inspect schemas, walk Delta table history, run read-only DuckDB queries, and check data-quality and job-run status safely.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to safely query SQL databases through read-only tools for describing entities, reading records, and aggregating records, with view-based access and fail-closed per-user row-level security.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query Postgres, BigQuery and DuckDB read-only through policy-checked SQL, with AST-based guards that refuse writes and dangerous functions, column masking on the way out, and an audit log of every query. Also exposes schema browsing and query-planning tools so agents can see allowed tables, columns and costs before running anything.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to inspect database schemas and run strictly read-only SQL queries with guardrails against destructive statements, multi-statement chaining, and unbounded scans. Supports SQLite natively and PostgreSQL optionally.
      4
      137 PyPI
      MIT