# lark-lite-mcp

一个面向 AI Agent 的轻量飞书多维表格（Bitable）MCP。它通过飞书官方 Node.js SDK 访问数据，并在 MCP 工具与飞书 SDK 之间提供稳定的兼容层。

## 设计目标

- 通用：不绑定学者库或其他业务项目。
- 安全：默认只读，凭证只从进程环境变量读取。
- 完整：查询显式返回分页状态，可受控拉取多页。
- 稳定：Agent 只依赖本项目定义的返回结构，不依赖飞书原始响应字段。
- 可升级：飞书 SDK 与 MCP SDK 使用精确版本，由测试验证后再升级。

当前只支持飞书多维表格，不支持飞书文档、消息、日历等其他能力。

## 安装与配置

生产或团队环境建议固定具体版本，避免启动时自动获取不兼容的新版本：

```json
{
  "mcpServers": {
    "lark-bitable": {
      "command": "npx",
      "args": ["-y", "lark-lite-mcp@2.0.1"],
      "env": {
        "LARK_APP_ID": "cli_xxx",
        "LARK_APP_SECRET": "xxx",
        "LARK_READ_ONLY": "true",
        "LARK_ALLOWED_BASE_TOKENS": "bascnAllowedBase",
        "LARK_ALLOWED_TABLE_IDS": "tblAllowedOne,tblAllowedTwo"
      }
    }
  }
}
```

也可以从源码运行：

```json
{
  "mcpServers": {
    "lark-bitable": {
      "command": "node",
      "args": ["/absolute/path/to/lark-lite-mcp/index.js"],
      "env": {
        "LARK_APP_ID": "cli_xxx",
        "LARK_APP_SECRET": "xxx"
      }
    }
  }
}
```

应用仍需在飞书开放平台申请相应权限，并加入目标多维表格的协作者。

## 环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `LARK_APP_ID` | 必填 | 飞书自建应用 App ID |
| `LARK_APP_SECRET` | 必填 | 飞书自建应用 App Secret |
| `LARK_READ_ONLY` | `true` | 为 `false` 时才暴露更新工具 |
| `LARK_ALLOWED_BASE_TOKENS` | 空 | 逗号分隔；为空时依赖飞书应用自身权限 |
| `LARK_ALLOWED_TABLE_IDS` | 空 | 逗号分隔；为空时依赖飞书应用自身权限 |
| `LARK_MAX_RETRIES` | `2` | 429、408 和 5xx 传输错误的最大重试次数 |
| `LARK_RETRY_DELAY_MS` | `250` | 指数退避的初始等待时间 |
| `LARK_REQUEST_TIMEOUT_MS` | `10000` | 单次飞书 HTTP 请求超时毫秒数 |
| `LARK_MAX_FETCH_ALL_RECORDS` | `1000` | `fetchAll` 可返回的硬上限 |

不要在对话或 MCP 工具参数中提供 App Secret。Secret 只应存在于 MCP 进程环境变量或密钥管理系统中。

## MCP 工具

| 工具 | 说明 |
| --- | --- |
| `lark_resolve_url` | 从普通 Base URL 提取坐标，或将 `/record/{share_token}` 单记录分享链接解析为真实的 Base、Table 和 Record 标识 |
| `lark_list_tables` | 分页列出 Base 中的数据表 |
| `lark_get_record` | 查询单条记录 |
| `lark_search_records` | 分页搜索记录；支持有上限的 `fetchAll` |
| `lark_update_record` | 更新单条记录，仅在写模式下暴露 |

分页结果使用稳定结构：

```json
{
  "items": [],
  "hasMore": false,
  "nextPageToken": null,
  "requestId": null
}
```

当 `fetchAll=true` 且命中安全上限时，结果额外返回 `"truncated": true`。调用方必须把它视为不完整结果。

## 兼容性策略

飞书原始响应只允许在 `src/bitable-adapter.js` 中处理。MCP 工具不直接读取 `res.data.items`、`record_id` 或 `page_token` 等飞书字段。SDK 或 OpenAPI 返回结构变化时，应只修改 Adapter，并保持工具返回结构不变。

依赖升级流程：

1. 修改精确依赖版本。
2. 运行离线单元与契约测试。
3. 使用专用测试 Base 运行在线冒烟测试。
4. 确认 MCP 客户端连接和工具列表。
5. 按语义化版本发布，并在生产配置中显式升级版本。

不建议直接使用 `^` 或 `latest` 自动追踪飞书 SDK、MCP SDK 或本 MCP 的新版本。

## 开发与验证

```bash
npm install
npm test
npm run check
```

在线冒烟测试只访问专用测试 Base：

```bash
LARK_APP_ID=cli_xxx \
LARK_APP_SECRET=xxx \
LARK_SMOKE_BASE_TOKEN=bascnTestBase \
npm run smoke
```

在线冒烟测试不应使用生产表，也不应把凭证提交到仓库。

## License

[MIT](./LICENSE)