Keboola CLI MCP Server

Kepoola CLI MCP服务器

充当Keoola CLI确定性代理的模型上下文协议（MCP）服务器(kbc)操作，具有自动git到Kepoola分支映射功能。

概述

此服务器通过在执行任何CLI命令之前强制执行分支解析，确保代理不会意外使用错误的Kepoola分支。它提供：

• 确定性分支解析：始终以编程方式导出当前的git分支
• 故障安全CLI代理：所有CLI命令都必须经过分支解析
• 单一真相来源: branch-mapping.json 是权威映射文件
• 项目验证：确保Kepoola项目正确初始化为 --allow-target-env

服务器模式

服务器支持两种模式：

CLI模式（默认）

提供用于运行的本地CLI工具 kbc 具有自动分支上下文的命令：

• 分支管理（link_Branch、unlink_brance等）
• kbc命令的CLI代理（同步推送、同步拉取等）
• 文档搜索

代理模式

通过自动代理远程Kepoola MCP服务器 X-Branch-Id 集管注入：

• 所有远程Keoola MCP工具 （SQL工作区、表操作、作业等）
• 加上本地CLI工具 （分支管理、kbc命令）
• 每个请求的动态分支解析 -切换git分支立即生效

启用： KBC_MCP_PROXY_MODE=true

┌─────────────────────────────────────────────────────────────────────┐
│                         Proxy Mode Flow                              │
│                                                                      │
│  1. Claude calls any tool (e.g., "sql_query")                       │
│                    │                                                 │
│                    ▼                                                 │
│  2. client_factory() called  ◄── PER REQUEST                        │
│       ├── git branch --show-current → "feature/billing"             │
│       ├── branch-mapping.json → "22750"                             │
│       └── Headers: X-StorageAPI-Token, X-Branch-Id: 22750           │
│                    │                                                 │
│                    ▼                                                 │
│  3. Request forwarded to remote Keboola MCP server                  │
│     https://mcp-agent.{stack}.keboola.com/mcp                       │
│                    │                                                 │
│                    ▼                                                 │
│  4. Response returned to Claude                                      │
└─────────────────────────────────────────────────────────────────────┘

先决条件

1. Keboola命令行界面(kbc) 必须在PATH中安装并可用

- 从以下位置安装：https://developers.keboola.com/cli/

1. Kepoola项目必须使用初始化 --allow-target-env

   kbc sync init --allow-target-env --storage-api-host connection..keboola.com

这面旗是 必需的 为了 KBC_BRANCH_ID 环境变量覆盖工作。

1. Python 3.10+

安装

# Clone and install
git clone 
cd keboola-cli-mcp-server
pip install -e .

配置

环境变量

创建一个 .env.local Kepoola项目目录中的文件：

# Required - Keboola Storage API token
KBC_STORAGE_API_TOKEN=

# Required - Storage API host (without protocol, used to derive MCP server URL in proxy mode)
KBC_STORAGE_API_HOST=connection..keboola.com

# Optional - defaults shown
GIT_DEFAULT_BRANCH=main          # Default branch name (maps to production)
KBC_WORKING_DIR=.                # Working directory for CLI operations
KBC_MAPPING_FILE=branch-mapping.json  # Path to mapping file

# Proxy mode - enable to get remote Keboola MCP tools with branch injection
KBC_MCP_PROXY_MODE=false         # Set to "true" to enable proxy mode

MCP客户端设置

克劳德桌面

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "keboola-cli": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "cwd": "/path/to/your/keboola-project",
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here"
      }
    }
  }
}

光标

添加到您的 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "keboola-cli": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here"
      }
    }
  }
}

克劳德代码（CLI）

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "keboola-cli": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here",
        "KBC_STORAGE_API_HOST": "connection.keboola.com"
      }
    }
  }
}

代理模式配置

要启用代理模式（建议用于Kepoola MCP的完整功能）：

{
  "mcpServers": {
    "keboola-unified": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here",
        "KBC_STORAGE_API_HOST": "connection.keboola.com",
        "KBC_MCP_PROXY_MODE": "true"
      }
    }
  }
}

这使您可以访问：

• 所有远程Kepoola MCP工具（SQL工作区、表操作等）
• 本地CLI工具（分支管理、kbc命令）
• 根据请求自动解析分支

可用工具

分行管理

CLI代理

允许的命令：

• sync push, sync pull, sync diff, sync init
• remote job run, remote table preview/download/upload
• remote create bucket, remote create branch, remote list branches
• local validate, local create config, local encrypt
• status

文档

用法示例

User: "Push my changes to Keboola"

Agent: [calls kbc(command="sync push")]
       ↓
Server: BranchResolver.branch_context()
        → git branch --show-current → "feature/auth"
        → lookup mapping → NOT FOUND
        → Return NO_MAPPING error
       ↓
Agent: "I need to link this branch first"
       [calls link_branch()]
       ↓
Server: → Creates Keboola branch via CLI
        → Saves mapping to branch-mapping.json
        → Returns success with branch ID
       ↓
Agent: "Now I can push"
       [calls kbc(command="sync push")]
       ↓
Server: → Resolves branch → "972851"
        → Sets KBC_BRANCH_ID=972851
        → Runs: kbc sync push
        → Returns success

错误处理

项目未初始化

{
  "error": "PROJECT_NOT_INITIALIZED",
  "message": "PROJECT_MISCONFIGURED: The project was not initialized with --allow-target-env flag.",
  "fix": "Run 'kbc sync init --allow-target-env' to initialize the project properly"
}

解决方案：使用以下命令重新初始化Kepoola项目：

kbc sync init --allow-target-env --storage-api-host connection..keboola.com

无映射

{
  "error": "NO_MAPPING",
  "message": "Git branch 'feature/new-thing' is not linked to any Keboola branch.",
  "git_branch": "feature/new-thing",
  "available_mappings": ["main", "feature/auth"]
}

解决方案：使用 link_branch 工具首先创建映射。

运行服务器

# Run via stdio transport (default)
python -m keboola_cli_mcp_server

# Or use the entry point
keboola-cli-mcp

发展

运行测试

pip install -e ".[dev]"
pytest tests/ -v

项目结构

keboola-cli-mcp-server/
├── pyproject.toml
├── README.md
├── src/
│   └── keboola_cli_mcp_server/
│       ├── __init__.py
│       ├── __main__.py              # Entry point
│       ├── server.py                # FastMCP server setup
│       ├── config.py                # Configuration management
│       ├── tools/
│       │   ├── branch.py            # Branch management tools
│       │   ├── cli_proxy.py         # Generic kbc CLI proxy
│       │   └── docs.py              # Documentation search
│       ├── services/
│       │   ├── git.py               # Git operations
│       │   ├── branch_mapping.py    # Mapping file management
│       │   ├── branch_resolver.py   # Core resolution logic
│       │   └── sapi_client.py       # Storage API client
│       └── models/
│           └── schemas.py           # Pydantic models
└── tests/
    ├── test_branch_resolver.py
    ├── test_cli_proxy.py
    └── test_branch_tools.py

分支映射文件

这 branch-mapping.json 文件存储git到Kepoola分支映射：

{
  "main": null,
  "feature/auth": "972851",
  "feature/data-pipeline": "983421"
}

• 钥匙：git分支名称
• 价值：Kepoola分支ID（字符串）或 null 用于生产
• null 表示“使用生产分支，不设置KBC_BRANC_ID”

备注：此文件应添加到 .gitignore 因为映射可能因开发人员而异。

分支解析的工作原理

1. Git分支检测：跑步 git branch --show-current 获取当前分支
2. 映射查找：检查 branch-mapping.json 对于映射
3. 默认分支处理: main/master 分支映射到生产（否 KBC_BRANCH_ID 以（权力）否决
4. 环境设置：集合 KBC_BRANCH_ID 非生产分支机构
5. CLI执行：跑步 kbc 在准备好的环境中指挥

这确保了当你打开时 feature/auth git分支映射到Keboola分支 972851，所有CLI操作都针对该特定开发分支。

许可证

麻省理工学院