Metadata-Version: 2.4
Name: sai-feishu-mcp
Version: 0.1.4
Summary: 飞书MCP
Requires-Python: >=3.12
Requires-Dist: fastmcp>=3.0.2
Requires-Dist: playwright>=1.58.0
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: requests>=2.32.5
Requires-Dist: urllib3>=2.6.3
Description-Content-Type: text/markdown

# sai-feishu-mcp

一个面向飞书（Lark）的 MCP（Model Context Protocol）服务器。以 stdio 方式运行，把飞书开放平台的常用能力封装成一组工具，供支持 MCP 的 AI 客户端调用，实现「用自然语言操作飞书」。

## 简介

- 走 **用户身份（user_access_token）** 为主，代表「本人」操作飞书，权限清晰、可控。
- 纯工具化设计，即插即用：在支持 MCP 的客户端中登记本服务即可使用，无需二次开发。
- 覆盖云文档、云盘、多维表格、电子表格、消息、日历、任务、通讯录、知识库、审批等常用场景。

## 主要功能

- **云盘与文件**：文件/文件夹列举与创建、上传、下载、文档搜索。
- **文档导出到本地**：`export_and_download` 一体化把飞书云文档导出为本地 docx/pdf/xlsx/csv（含知识库 Wiki 文档），供后续转换为 WPS 等本地格式。
- **云文档（Docx）**：读取文档纯文本/块结构、创建文档、写入文本块与标题块。
- **多维表格（Bitable）**：创建多维表格与数据表、字段与记录的增查改。
- **电子表格（Sheets）**：读取/写入指定区域数据。
- **即时消息（IM）**：发送/回复消息、会话列举、历史与消息搜索。
- **日历（Calendar）**：日历与日程的列举、创建、忙闲查询。
- **任务（Task）**：任务创建、成员管理、更新与列举。
- **通讯录（Contact）**：查询用户与部门信息。
- **知识库（Wiki）**：节点与空间的查询、创建、移动。
- **妙记（Minutes）**：获取妙记信息。
- **审批（Approval）**：
  - 查询审批实例列表与实例详情；
  - **单个审批同意/拒绝**（不可逆写操作，多重安全保护：走用户身份、按 open_id+PENDING 精确定位本人待办任务、本地授权开关默认关闭并需用户明确授权后方可执行）。

> 说明：飞书官方仅支持导出 docx/doc/sheet/bitable 四类文档；幻灯片、思维笔记、妙记无导出接口，需改用 `download_file` 下载原始附件。

## 环境要求

- Python >= 3.12
- 已在飞书开放平台创建应用，并配置好对应能力的权限。

## 安装与运行

在支持 MCP 的客户端中，将本服务登记为一个 stdio MCP 服务器，启动命令如下。

**推荐（用户自动升级，无需任何手动操作）：**

```bash
uvx --refresh sai-feishu-mcp
```

`--refresh` 会让 uvx 每次启动时检查并拉取已发布的最新版本，因此**发布新版后，用户重启客户端即可自动用上最新版**，无需改配置、无需清缓存。

以 MCP 客户端配置为例（不锁版本 + `--refresh`）：

```json
{
  "command": "uvx",
  "args": ["--refresh", "sai-feishu-mcp"]
}
```

> 为什么不锁版本号（如 `sai-feishu-mcp@0.1.1`）？
> 锁版本会遇到两个对普通用户不友好的坑：① 刚发布时，PyPI 国内镜像（如清华源）尚未同步该版本，会报 “No solution found” 装不上；② uvx 会缓存“解析失败/旧版本”结果，用户既不知道、也无法去清缓存。用 `--refresh` 不锁版本可彻底规避。

或安装后运行（本地开发调试用）：

```bash
pip install sai-feishu-mcp
sai-feishu-mcp
```

---

## 上线前必做：打包与上传（发布到 PyPI）

> 每次发布新版本前，**务必先递增 `pyproject.toml` 中的 `version`**（PyPI 不允许覆盖同一版本号）。

```bash
# 1) 修改版本号：编辑 pyproject.toml，将 version 递增（如 0.1.1 -> 0.1.2）

# 2) 清理旧产物并重新打包
rm -f dist/*.whl dist/*.tar.gz
uv build

# 3) 上传到 PyPI（执行后按提示粘贴 API token）
uv run python -m twine upload dist/*
```

发布成功后可在 `https://pypi.org/project/sai-feishu-mcp/` 查看对应版本。

> 用户侧升级：只要客户端按上面的 `uvx --refresh sai-feishu-mcp` 配置，**用户无需做任何操作**，重启客户端即会自动拉取到本次发布的新版本。
