Metadata-Version: 2.5
Name: mcp-feishu
Version: 0.1.0
Summary: 把消息发到飞书自定义机器人的标准 MCP Server (Model Context Protocol)
License-Expression: MIT
Keywords: feishu,lark,llm,mcp,model-context-protocol,notification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=2.1.0
Description-Content-Type: text/markdown

# mcp-feishu

面向大语言模型与智能 Agent 的标准 **Model Context Protocol (MCP)** Server。

它的作用是为 AI 提供 `send_to_feishu` 工具，将长文本、运维命令、配置片段等内容以富文本卡片的形式推送到飞书自定义机器人群组中。用户在飞书客户端可以直接一键整段复制命令，无需在终端手动抄写。

---

## 特性

- **标准协议支持**：基于 Model Context Protocol Python SDK 实现，遵循 MCP 标准规范。
- **零配置中心依赖**：纯粹通过环境变量读取参数，不强绑定任何特定主机或配置中心（如 Nacos）。可跨机器无缝迁移部署。
- **即装即用**：支持直接通过 `uvx mcp-feishu` 或 `pip install mcp-feishu` 启动。
- **安全与防泄露**：内置敏感请求日志脱敏机制，确保 Webhook 凭据不打印至终端或日志。
- **富文本排版**：飞书交互式卡片渲染，支持 Markdown 与等宽代码块整段复制。

---

## 环境变量配置

本服务完全由环境变量控制，无需修改任何代码文件：

| 环境变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `FEISHU_WEBHOOK` | **是** | 无 | 飞书群自定义机器人的 Webhook 地址（形如 `https://open.feishu.cn/open-apis/bot/v2/hook/...`） |
| `FEISHU_SECRET` | 否 | 空 | 机器人开启「签名校验」时的校验 Secret |
| `FEISHU_TITLE` | 否 | `📋 来自 AI 的消息` | 发送卡片的默认标题 |

---

## 快速使用

### 1. Claude Desktop / Codex 配置 (推荐使用 uvx)

在你的客户端配置文件（如 `claude_desktop_config.json` 或 `~/.codex/config.toml`）中加入配置：

#### JSON 格式 (Claude Desktop / Cursor 等)
```json
{
  "mcpServers": {
    "feishu": {
      "command": "uvx",
      "args": ["mcp-feishu"],
      "env": {
        "FEISHU_WEBHOOK": "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_ROBOT_WEBHOOK_KEY",
        "FEISHU_SECRET": "YOUR_SECRET_IF_ENABLED"
      }
    }
  }
}
```

#### TOML 格式 (Codex 等)
```toml
[mcp_servers.feishu]
type = "stdio"
command = "uvx"
args = ["mcp-feishu"]

[mcp_servers.feishu.env]
FEISHU_WEBHOOK = "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_ROBOT_WEBHOOK_KEY"
FEISHU_SECRET = "YOUR_SECRET_IF_ENABLED"
```

### 2. 通过 pip 安装运行

```bash
pip install mcp-feishu
export FEISHU_WEBHOOK="https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
mcp-feishu
```

---

## 提供的工具 (Tools)

### `send_to_feishu`

向指定的飞书群机器人发送通知卡片。

- **参数**：
  - `text` (string, required): 消息正文。支持 Markdown；长命令或代码建议使用 ```` ``` ```` 包裹，以便在客户端整段复制。
  - `title` (string, optional): 卡片头部标题。留空时使用 `FEISHU_TITLE` 默认标题。
- **返回**：发送状态结果描述（例如 `"已送达"` 或失败原因）。

---

## 开源协议

MIT License
