mcp-feishu 0.1.0__tar.gz

mcp_feishu-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+dist/
+build/
+*.egg-info/
+.venv/
+env/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+*.swp
+*.swo

mcp_feishu-0.1.0/AGENTS.md

@@ -0,0 +1,30 @@
+# mcp-feishu — AI 指南
+
+## Purpose
+
+标准 Model Context Protocol (MCP) Server，为 LLM / Agent 客户端提供 `send_to_feishu` 工具，将文本以 Markdown 格式推送到飞书自定义机器人群聊。
+
+纯环境变量驱动，零配置中心依赖，可独立打包分发至 PyPI 并迁移到任何主机。
+
+## Architecture Map
+
+| 路径 | 语义 |
+|---|---|
+| `src/mcp_feishu/__init__.py` | 包版本与入口暴露 |
+| `src/mcp_feishu/__main__.py` | MCP Server 实现、飞书签名与 Webhook 投递 |
+| `pyproject.toml` | 打包构建元数据与 CLI entry-point |
+| `README.md` | 使用指南与环境变量说明 |
+
+## Environment Variables
+
+| 变量 | 必填 | 默认值 | 说明 |
+|---|---|---|---|
+| `FEISHU_WEBHOOK` | 是 | 无 | 机器人 Webhook URL |
+| `FEISHU_SECRET` | 否 | 空 | 机器人安全签名 Secret |
+| `FEISHU_TITLE` | 否 | `📋 来自 AI 的消息` | 默认卡片标题 |
+
+## Verification
+
+```bash
+uv run --project OWNED/mcp-feishu python -m mcp_feishu --help
+```

mcp_feishu-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+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

mcp_feishu-0.1.0/README.md

@@ -0,0 +1,90 @@
+# 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

mcp_feishu-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "mcp-feishu"
+version = "0.1.0"
+description = "把消息发到飞书自定义机器人的标准 MCP Server (Model Context Protocol)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["mcp", "model-context-protocol", "feishu", "lark", "llm", "notification"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp>=2.1.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+mcp-feishu = "mcp_feishu.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_feishu"]

mcp_feishu-0.1.0/src/mcp_feishu/__init__.py

@@ -0,0 +1 @@
+"""把消息发到飞书自定义机器人的 MCP server。"""

mcp_feishu-0.1.0/src/mcp_feishu/__main__.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""飞书通知 MCP server。
+
+只做一件事：把一段文本发到飞书自定义机器人，方便人在手机或客户端里直接复制。
+
+配置全部来自环境变量，**不读取任何本机配置中心**——这样整个目录拷到别的机器上、
+或者换一个机器人，改环境变量即可，不需要改代码：
+
+    FEISHU_WEBHOOK   必填，自定义机器人的 webhook 地址
+    FEISHU_SECRET    选填，机器人开启「签名校验」时才需要
+    FEISHU_TITLE     选填，默认卡片标题
+
+为什么不复用本仓库的 runtime.notify：那个库从 r-nacos 读配置，绑死在这台主机上，
+与本 server「可迁移」的目标冲突。飞书签名逻辑本身只有几行，独立实现换来的是零外部依赖。
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import logging
+import os
+import sys
+import time
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+
+# httpx 默认在 INFO 级别打印完整请求 URL。webhook 地址本身就是凭据，
+# 打出来等于把它写进日志——密钥契约明确禁止。这里直接压到 WARNING。
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+SEND_TIMEOUT_SECONDS = 10
+DEFAULT_TITLE = os.environ.get("FEISHU_TITLE", "📋 来自 AI 的消息")
+
+mcp = MCPServer("feishu-notify")
+
+
+def _sign(timestamp: int, secret: str) -> str:
+    """飞书签名：待签名串是 "{timestamp}\\n{secret}"，消息体为空。"""
+    string_to_sign = f"{timestamp}\n{secret}"
+    digest = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()
+    return base64.b64encode(digest).decode("utf-8")
+
+
+def _post(title: str, text: str) -> str:
+    webhook = os.environ.get("FEISHU_WEBHOOK", "").strip()
+    if not webhook:
+        return "未配置 FEISHU_WEBHOOK，无法发送"
+    secret = os.environ.get("FEISHU_SECRET", "").strip()
+
+    payload: dict = {
+        "msg_type": "interactive",
+        "card": {
+            "header": {"title": {"tag": "plain_text", "content": title},
+                       "template": "blue"},
+            # lark_md 里的 ``` 代码块在客户端是等宽显示，长按/右键可整段复制，
+            # 这正是这个 server 存在的理由——让人不用从终端里手抄命令。
+            "elements": [{"tag": "div",
+                          "text": {"tag": "lark_md", "content": text}}],
+        },
+    }
+    if secret:
+        timestamp = int(time.time())
+        payload["timestamp"] = str(timestamp)
+        payload["sign"] = _sign(timestamp, secret)
+
+    try:
+        response = httpx.post(webhook, json=payload, timeout=SEND_TIMEOUT_SECONDS)
+        data = response.json()
+    except Exception as error:  # noqa: BLE001
+        # 异常正文可能带上完整 URL，只回类型不回原文。
+        return f"发送异常: {type(error).__name__}"
+    if data.get("code", -1) == 0:
+        return "已送达"
+    return f"发送失败: {data.get('msg', '未知错误')}"
+
+
+@mcp.tool()
+def send_to_feishu(text: str, title: str = "") -> str:
+    """把一段文本发到飞书，方便用户直接复制。
+
+    适合发：要用户手工执行的命令、需要保存的配置片段、过长不便在终端复制的内容。
+
+    Args:
+        text: 正文，支持 Markdown。命令请用 ``` 代码块包起来，客户端里可整段复制。
+        title: 卡片标题，留空则用默认标题。
+    """
+    if not text.strip():
+        return "正文为空，未发送"
+    return _post(title.strip() or DEFAULT_TITLE, text)
+
+
+def main() -> int:
+    if not os.environ.get("FEISHU_WEBHOOK"):
+        print("警告：未设置 FEISHU_WEBHOOK，send_to_feishu 会直接返回失败",
+              file=sys.stderr)
+    mcp.run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())