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: 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、キー元帳