CK Map MCP2

ck-map-mcp2 是一个独立的 stdio MCP server，专门用于一个固定的 ClickHouse 场景：

1. 使用只读账号连接 ClickHouse
2. 按 template_code 查询 electricity_trading.crawl_task_instance_result
3. 读取该 template_code 下 create_time 最新的一条记录
4. 提取这条记录中 result 这个 Map 字段的 key
5. 生成对应的只读展开 SQL

这个 MCP 是一个面向固定业务的专用工具，不提供任意 SQL 执行能力，也不会向 ClickHouse 写入数据。

功能说明

当前提供两个 MCP 工具：

• ping_ck：校验当前配置是否可以正常连接 ClickHouse
• analyze_template_result：读取最新记录，返回 key 列表、别名映射、最新时间和生成后的只读 SQL

生成的 SQL 会保留 template_code 过滤条件，但默认不会自动追加 ORDER BY 和 LIMIT。

目录说明

• server.py：MCP 服务入口
• ck_readonly.py：本地只读 ClickHouse 连接层
• templates/result_flatten.sql.j2：analyze_template_result 使用的 SQL 模板
• docs/tool-contracts.md：工具输入输出契约说明
• .env.example：本地配置模板

使用前提

• Python 3.12+
• pip 可用，用于安装 Python 依赖
• 当前机器可以访问目标 ClickHouse 实例
• 已有一个可用的 ClickHouse 只读账号

快速开始

1. 安装依赖

在当前目录执行下面任一命令：

python -m pip install -r requirements.txt

或者：

uv pip install -r requirements.txt

2. 配置本地 .env

先复制配置模板：

Copy-Item .env.example .env

然后把 .env 改成你自己的真实 ClickHouse 连接信息：

CLICKHOUSE_HOST=your-clickhouse-host
CLICKHOUSE_PORT=3306
CLICKHOUSE_USER=your_readonly_user
CLICKHOUSE_PASSWORD="your_password"
CLICKHOUSE_DATABASE=electricity_trading
CLICKHOUSE_SECURE=false

说明：

• ck-map-mcp2 会优先读取进程环境中的 CLICKHOUSE_* 变量
• 如果进程环境中没有对应变量，会继续读取包目录下的 .env
• 如果设置了 CK_MAP_MCP2_ENV_FILE，还会额外读取该路径指向的 .env 文件
• 建议密码统一加双引号，便于兼容特殊字符

3. 本地验证连通性

在接入 Cursor 前，建议先做一次最小验证：

python -c "import server; print(server.ping_ck())"

成功时返回结果大致如下：

{
  "ok": true,
  "server": "clickhouse",
  "version": "23.x",
  "database": "electricity_trading",
  "host": "your-clickhouse-host",
  "port": 3306,
  "secure": "false"
}

4. 手动启动 MCP 服务

python server.py

启动后它会以 stdio MCP 服务的形式等待客户端连接，例如 Cursor。

Cursor 接入方式

把这个 MCP 配到你自己的 Cursor MCP 配置里。

方式一：本地 Python 直接启动

{
  "mcpServers": {
    "ck-map-mcp2": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "D:/path/to/ck-map-mcp2"
    }
  }
}

如果你习惯使用 uv，也可以改成：

{
  "command": "uv",
  "args": ["run", "python", "server.py"]
}

方式二：通过 NPM 包启动

发布到 MCP 工具广场后，推荐把 ClickHouse 配置直接写进 env：

{
  "mcpServers": {
    "ck-map-mcp2": {
      "command": "npx",
      "args": ["-y", "@jixiaos/ck-template-map-mcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_PORT": "9000",
        "CLICKHOUSE_USER": "your_readonly_user",
        "CLICKHOUSE_PASSWORD": "your_password",
        "CLICKHOUSE_DATABASE": "electricity_trading",
        "CLICKHOUSE_SECURE": "false"
      }
    }
  }
}

如果你仍然想让广场版读取 .env 文件，可以通过 CK_MAP_MCP2_ENV_FILE 显式指定：

{
  "mcpServers": {
    "ck-map-mcp2": {
      "command": "npx",
      "args": ["-y", "@jixiaos/ck-template-map-mcp"],
      "env": {
        "CK_MAP_MCP2_ENV_FILE": "D:/path/to/ck-map-mcp2.env"
      }
    }
  }
}

说明：

• npm 启动器会先检查 Python 3，再自动安装 requirements.txt 中的依赖
• 安装后的 Python 依赖默认缓存到本机用户目录，不会写回项目仓库
• 如果需要自定义缓存目录，可以设置 CK_MAP_MCP2_CACHE_DIR
• 发布到 npm 后，推荐包名使用 @jixiaos/ck-template-map-mcp

推荐使用流程

1. 先调用 ping_ck，确认 ClickHouse 连接配置正确。
2. 再调用 analyze_template_result，传入一个真实的 template_code。
3. 查看返回的 keys、alias_map、latest_create_time 和 sql。
4. 按需要复制或继续加工返回的 SQL。

示例请求：

{
  "template_code": "TPL64680983314331",
  "base_columns": ["template_code", "create_time"]
}

示例 SQL：

SELECT
    template_code,
    create_time,
    result['period'] AS period,
    result['province_code'] AS province_code,
    result['originalSeries'] AS original_series,
    result['dt'] AS dt,
    result['pDate'] AS p_date,
    result['time_point'] AS time_point,
    result['x'] AS x,
    result['y'] AS y,
    result['text'] AS text
FROM electricity_trading.crawl_task_instance_result
WHERE template_code = 'TPL64680983314331';

运行说明

• 所有数据库查询都带只读约束
• key 的提取依据是 create_time DESC 下最新一条记录
• 如果某些字段只在历史记录中偶发出现，而最新记录里没有，这些 key 可能不会被发现
• 生成的默认 SQL 面向该 template_code 的全部匹配记录，而不是只面向最新一条
• server.py 会优先使用 site-packages 中的官方 mcp SDK，避免被本地同名目录干扰

常见问题

• Configuration CLICKHOUSE_HOST is required
  说明当前既没有从进程环境变量中读取到配置，也没有从 CK_MAP_MCP2_ENV_FILE 或包目录下的 .env 读取到配置。请检查对应配置源里是否填写了正确的 CLICKHOUSE_* 字段。

• No rows found for template_code: ...
  说明数据库连接本身是通的，但该 template_code 在 electricity_trading.crawl_task_instance_result 中没有查到数据。

• 出现超时、握手失败或连接失败
  请检查 host、port、协议、网络权限、防火墙，以及当前实例是否要求使用安全连接。

• Python 3 was not found
  说明 npm 启动器没有在当前机器上找到可用的 Python 3。请先安装 Python 3.12+，或者通过 PYTHON 环境变量显式指定解释器路径。