Skip to main content
Glama

K-AIR MCP

エージェントがデータハブの参照のみを行うために公開する公式MCPサーバーです。窓口は1つで、カタログソース 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、ダンプ/送信、運用Tibero、t2s・argus_catalog データ参照、エンジンごとにMCPを分けること。

Related MCP server: Governor SQL MCP

ツール

ツール

役割

list_tables

許可テーブル一覧。任意の schema_name。レスポンスに engine

describe_table

カラム型・PK・コメント。存在しない韓国語説明は空欄

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 かつカラムなし

行上限 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
      84 PyPI
      MIT