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

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

环境变量

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

MCP 工具

分页结果使用稳定结构：

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