Metadata-Version: 2.4
Name: feishu-mcp
Version: 0.2.1
Summary: A safe Feishu MCP server for task-delivery notifications
Author: Internal Platform Team
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0.0,>=1.0.0

# 飞书 MCP

这是一个通过 MCP 向飞书用户或群聊发送文本、文件的工具。它支持按名称查找收件人，并会将已成功发送的目标缓存到本机，以减少重复查询。

## 开始使用

### 1. 安装 uv

在 Windows PowerShell 中运行：

```powershell
winget install --id=astral-sh.uv -e
```

安装完成后，重新打开终端或 Codex，确认命令可用：

```powershell
uvx --version
```

### 2. 配置 MCP 客户端

在 MCP 客户端的配置文件中添加以下内容。以 Codex 为例，配置文件通常是 `C:\\Users\\你的用户名\\.codex\\config.toml`。

```toml
[mcp_servers.feishu]
command = "uvx"
args = ["--from", "feishu-mcp==0.2.1", "feishu-mcp"]
enabled = true

[mcp_servers.feishu.env]
FEISHU_APP_ID = "你的飞书应用 App ID"
FEISHU_APP_SECRET = "你的飞书应用 App Secret"
FEISHU_TARGETS_FILE = "C:\\Users\\你的用户名\\.feishu-mcp\\targets.json"
FEISHU_AUDIT_LOG = "C:\\Users\\你的用户名\\.feishu-mcp\\audit.jsonl"
```

保存配置并重启 MCP 客户端。首次启动时，`uvx` 会自动下载工具及其依赖；之后会复用本机缓存。

## 使用方式

配置完成后，可以直接让支持 MCP 的客户端完成以下操作：

- 查找飞书用户或群聊：`查询用户“张三”`、`查询群聊“研发部门”`
- 发送消息：`向李四发送：项目已完成。`
- 发送文件：`将 D:\\报告.xlsx 发送给李四`

如果同名用户或群聊有多个匹配项，工具不会猜测收件人，而会提示你提供更准确的名称或直接提供飞书 `open_id` / `chat_id`。

## 飞书应用要求

使用前需要创建并启用一个飞书自建应用，并将它的 `App ID` 与 `App Secret` 填入 MCP 配置。应用还需申请与实际功能匹配的通讯录、消息发送、文件上传权限；若要按群聊名称查询，还需要 `im:chat:readonly` 权限。

请勿将 `App Secret` 写入代码、上传到仓库，或发送给他人。

## 更新

将配置中 `feishu-mcp==` 后的版本号改为新版本，重启 MCP 客户端即可更新。建议始终固定版本号，方便回滚和排查问题。
