# 自定义飞书 MCP Server

## 项目结构

```
lark-mcp-custom/
├── src/
│   ├── index.ts              # 入口：初始化 MCP Server + 注册工具
│   ├── lark-client.ts        # 飞书 SDK 客户端封装
│   └── tools/
│       ├── im-tools.ts       # 消息工具（发消息、群列表、消息历史）
│       ├── calendar-tools.ts # 日历工具（查询事件、创建事件）
│       └── docs-tools.ts     # 文档工具（搜索文档、多维表格读写）
├── .env.example
├── package.json
├── tsconfig.json
└── claude_desktop_config.example.json
```

## 已实现工具

| 工具名 | 功能 |
|--------|------|
| `lark_send_message` | 发送文本消息到群或用户 |
| `lark_list_chats` | 获取机器人所在群列表 |
| `lark_get_messages` | 获取群内最近消息 |
| `lark_calendar_events` | 查询日历事件 |
| `lark_create_event` | 创建日历事件 |
| `lark_search_docs` | 搜索云空间文档 |
| `lark_bitable_list_records` | 读取多维表格记录 |
| `lark_bitable_create_record` | 向多维表格写入记录 |

## 安装和运行

### 前置条件
- Node.js >= 20
- 飞书企业自建应用（App ID + App Secret）

### 步骤

1. 安装依赖
```bash
npm install
```

2. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env，填入 FEISHU_APP_ID 和 FEISHU_APP_SECRET
```

3. 构建
```bash
npm run build
```

4. 测试运行
```bash
FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx node dist/index.js
```

5. 配置 Claude 桌面版（见下方）

## 配置 Claude 桌面版

编辑 Claude 配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "lark-mcp-custom": {
      "command": "node",
      "args": ["/你的绝对路径/lark-mcp-custom/dist/index.js"],
      "env": {
        "FEISHU_APP_ID": "cli_你的AppID",
        "FEISHU_APP_SECRET": "你的AppSecret"
      }
    }
  }
}
```

重启 Claude 桌面版后即可使用。

## 飞书应用权限配置

在飞书开放平台（https://open.feishu.cn/app）为应用开启以下权限：

**IM（消息）**
- `im:message` 读写消息
- `im:chat:readonly` 查看群信息

**日历**
- `calendar:calendar` 读写日历

**云文档 & 多维表格**
- `drive:drive:readonly` 搜索文档
- `bitable:app` 多维表格读写

## 扩展开发

新增工具只需两步：

1. 在 `src/tools/` 下创建新文件，导出 `registerXxxTools(server, client)` 函数
2. 在 `src/index.ts` 中 import 并调用

工具定义格式：
```typescript
server.tool(
  "工具唯一名称",
  "工具功能描述（Claude 会看这个来决定何时调用）",
  { 参数: z.string().describe("参数说明") },
  async (params) => {
    // 调用飞书 API
    return { content: [{ type: "text", text: "返回结果" }] };
  }
);
```