lark-lite-mcp

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

设计目标

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

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

安装与配置

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

{
  "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"
      }
    }
  }
}

也可以从源码运行：

{
  "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	更新单条记录，仅在写模式下暴露

分页结果使用稳定结构：

{
  "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 的新版本。

开发与验证

npm install
npm test
npm run check

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

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

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

License

MIT