npm package: @junjun-org/bd-ke-mcp
Description: MCP (Model Context Protocol) tools for BD-KE - Knowledge Engine application management
Latest version: 1.0.2

# BD-KE MCP Server

这是一个符合 MCP (Model Context Protocol) 规范的 Node.js 服务器，用于管理 KE (Knowledge Engine) 应用。

## 快速开始

### 1. 安装

**使用 npx（推荐）：**

```bash
npx bd-ke-mcp
```

**全局安装：**

```bash
npm install -g bd-ke-mcp
```

**本地开发：**

```bash
cd /path/to/bd-ke-mcp
npm install
```

### 2. 配置 Cursor

在 Cursor 的 MCP 配置文件中添加：

**使用 npx（推荐）：**

```json
{
  "mcpServers": {
    "bd-ke-mcp": {
      "command": "npx",
      "args": ["-y", "bd-ke-mcp"],
      "env": {
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

**本地开发模式：**

```json
{
  "mcpServers": {
    "bd-ke-mcp": {
      "command": "node",
      "args": ["/path/to/bd-ke-mcp/index.js"],
      "env": {
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

配置文件位置：
- 通过 Cursor 设置界面：Settings → Features → Model Context Protocol

### 3. 配置项目

在项目根目录创建 `.mcp/bd-ke-mcp.json`：

```json
{
  "domain": "https://ke.example.com",
  "access_token": "your_access_token_here",
  "tenant": "your_tenant",
  "project": "your_project",
  "application": "your_application",
  "env": "production"
}
```

**注意：**
- 配置采用扁平化结构，所有配置项直接放在顶层
- 配置文件包含敏感信息，建议添加到 `.gitignore`
- 可通过环境变量覆盖配置（使用 `BD_KE_MCP_` 前缀）

### 4. 使用

配置完成后，重启 Cursor。MCP 服务器会自动启动，可以在 Cursor 中使用以下工具。

## 项目结构

```
bd-ke-mcp/
├── index.js             # MCP服务器主文件（包含所有工具实现）
├── package.json         # 项目配置文件
├── .mcp/               # 配置目录
│   └── bd-ke-mcp.json.example  # 配置示例
├── README.md           # 项目说明文档
└── LICENSE             # 许可证
```

## 配置说明

### 配置文件位置

`.mcp/bd-ke-mcp.json` - 项目根目录下的 `.mcp` 目录

### 配置项

| 配置项 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| `domain` | string | 是 | KE服务地址 |
| `access_token` | string | 是 | 授权token |
| `tenant` | string | 是 | 租户名称 |
| `project` | string | 是 | 项目名称 |
| `application` | string | 是 | 应用名称 |
| `env` | string | 是 | 环境（如：development, staging, production） |

**配置说明：**
- `tenant` 和 `project` 组合后形成 KE 的命名空间（namespace），格式为 `tenant-project`
- 例如：`tenant=app`, `project=xxx`，则实际的命名空间为 `app-xxx`
- 在 KE API 调用中，URL 路径中的 `namespace` 参数使用的是 `tenant-project` 格式

### 环境变量

配置可通过环境变量设置（优先级高于配置文件）：

```bash
export BD_KE_MCP_DOMAIN="https://ke.example.com"
export BD_KE_MCP_ACCESS_TOKEN="your_access_token"
export BD_KE_MCP_TENANT="your_tenant"
export BD_KE_MCP_PROJECT="your_project"
export BD_KE_MCP_APPLICATION="your_application"
export BD_KE_MCP_ENV="production"
```

环境变量命名规则：
- 使用 `BD_KE_MCP_` 前缀
- 配置键全部大写：`BD_KE_MCP_DOMAIN` → `domain`

### 配置查找逻辑

1. 从 `PROJECT_ROOT` 环境变量获取项目根目录
2. 在项目根目录查找 `.mcp/bd-ke-mcp.json`
3. 加载配置文件后，用环境变量覆盖同名配置

## 可用工具

### ke_app_restart

重启 KE 应用（通过删除 Pod 触发自动重建）。

**使用方式：**

在 Cursor 中直接调用，无需参数。工具会自动从项目配置中读取应用信息。

### ke_pipeline_info

获取 KE 流水线信息，包括流水线名称和执行参数。

**使用方式：**

在 Cursor 中直接调用，无需参数。工具会从项目配置中读取流水线地址和授权token，返回流水线名称和可修改的执行参数。

### ke_pipeline_create

执行 KE 流水线（创建流水线运行时）。

**使用方式：**

在 Cursor 中调用，需要传入 `globalArguments` 参数（参数字典）。工具会从项目配置中读取流水线地址和授权token，执行流水线。

**参数：**
- `globalArguments` (必需): 全局参数字典，键为参数名，值为参数值
- `deadline` (可选): 超时时间（秒），默认 86400
- `review` (可选): 审核信息，默认为空字符串

### ke_tenants_list

列出所有的租户。

### ke_projects_list

列出所有的项目。

### ke_app_list

列出所有的应用。

### ke_env_list

获取当前租户下的所有环境列表。

**参数：**
- `projectName` (可选): 已废弃，保留以保持向后兼容，实际不使用此参数

### ke_pods_list

获取指定应用的Pod实例列表。

**参数：**
- `appName` (必需): 应用名称，可通过 `ke_app_list` 获取

**返回信息：**
- 实例名称
- 实例状态（Running、Pending 等）
- 创建时间
- 容器IP
- 运行节点
- 重启次数

### ke_pod_log_list

获取指定应用的Pod日志列表。

**参数：**
- `namespace` (必需): 命名空间，格式为 tenant-project（如：app-sheyang）
- `service` (必需): 服务名称（应用名称），可通过 `ke_app_list` 获取
- `env` (必需): 环境名称，可通过 `ke_env_list` 获取
- `start_time` (必需): 开始时间（纳秒时间戳）
- `end_time` (必需): 结束时间（纳秒时间戳）
- `size` (可选): 返回记录数量，默认100
- `offset` (可选): 偏移量，默认0
- `sort` (可选): 排序方式，默认desc（降序），可选asc（升序）

**返回信息：**
- 日志内容（body）
- 时间戳
- Pod名称
- Pod IP
- 日志级别

## 开发

### 运行本地开发

```bash
# 安装依赖
npm install

# 运行服务
npm start
```

### 调试模式

设置 `BD_KE_MCP_DEBUG` 环境变量可启用 DEBUG 级别日志：

```bash
BD_KE_MCP_DEBUG=1 npm start
```

## 从 Python 版本迁移

如果你之前使用的是 Python 版本，迁移步骤如下：

1. **配置文件兼容**：`.mcp/bd-ke-mcp.json` 配置格式完全相同，无需修改
2. **更新 Cursor 配置**：将 MCP 配置中的 `command` 从 `python3` 改为 `node` 或 `npx`
3. **功能完全兼容**：所有 9 个工具的功能和参数完全一致

## 常见问题

### 1. 配置文件未加载
- **原因**：项目根目录未正确识别
- **解决**：设置 `PROJECT_ROOT` 环境变量指向项目根目录

### 2. 网络请求超时
- **原因**：KE 服务响应慢或网络问题
- **解决**：检查 `domain` 配置是否正确，确保网络可达

### 3. 认证失败
- **原因**：`access_token` 无效或过期
- **解决**：更新配置文件中的 `access_token`

## 日志

日志输出到 stderr，可在 Cursor 的 MCP 日志面板查看。

设置 `BD_KE_MCP_DEBUG` 环境变量可启用 DEBUG 级别日志。

## 许可证

MIT License