wechat-oa-mcp-direct 0.2.0__tar.gz

wechat_oa_mcp_direct-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: wechat-oa-mcp-direct
+Version: 0.2.0
+Summary: 微信公众号 MCP 服务器（直连微信官方 API 版）：草稿创建/发布/删除、素材删除、access_token 获取
+Author-email: Jupiter <jupiter3019@163.com>
+License: MIT
+Keywords: wechat,mcp,fastmcp,公众号
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=4.0
+Requires-Dist: requests>=2.25
+
+# wechat-oa-mcp-direct
+
+微信公众号 MCP 服务器 —— **直连微信官方 API 版**。
+
+基于 FastMCP 4.x 实现，提供公众号草稿创建 / 发布 / 删除、永久素材删除、access_token 获取共 5 个 MCP 工具。所有请求直连 `api.weixin.qq.com`，**不经过任何第三方中转服务器**，AppID / AppSecret 只在部署机与微信之间传输。
+
+> 与 PyPI 上的 `wechat-oa-mcp 0.1.0` 的区别：旧版会把你的 AppSecret 转发到作者的服务器（106.15.125.133）中转，且依赖已废弃的 MCP SDK v1 API，无法在新环境启动。本包修复了上述问题（含 41001 access_token missing 修复）。
+
+---
+
+> ## ⚠️ 部署前必读：IP 白名单（最容易踩的坑）
+>
+> 部署好后首次调用工具，如果返回 **`40164 invalid ip ... not in whitelist`** —— **不是代码问题**，是这台部署机的公网出口 IP 还没有加进公众号的 IP 白名单。
+>
+> - **每台部署机器都要把「它自己的出口 IP」加进白名单**（不同机器的 IP 不一样）；
+> - **换网络、换服务器、IP 变化后都要重新加**，否则之前能用的机器会突然报 40164；
+> - 获取出口 IP 和配置方法见下文「2.2 配置 IP 白名单」。
+
+---
+
+## 1. 安装
+
+### Windows CMD 一键安装（最简便，无需虚拟环境）
+
+解压 zip 后，在 CMD 中进入解压出来的目录，一条命令安装：
+
+```cmd
+cd wechat-oa-mcp-direct
+pip install .
+```
+
+安装完成后验证：
+
+```cmd
+wechat-oa-mcp --help
+```
+
+### macOS / Linux，或需要环境隔离时
+
+```bash
+cd wechat-oa-mcp-direct
+python3 -m venv .venv
+source .venv/bin/activate        # Windows 虚拟环境: .venv\Scripts\activate
+pip install .
+```
+
+要求：Python >= 3.10（Windows 安装 Python 时记得勾选 **"Add Python to PATH"**，否则 CMD 里 `pip` 会提示找不到命令）。
+
+## 2. 前置配置（部署机必须完成）
+
+### 2.1 获取公众号凭证（AppID / AppSecret 在哪里）
+
+1. 用管理员微信扫码登录微信公众平台：https://mp.weixin.qq.com（需要先注册一个公众号，订阅号/服务号均可）；
+2. 左侧菜单点 **「设置与开发」→「基本配置」**；
+3. 页面上的 **开发者ID(AppID)** 就是 AppID；
+4. **开发者密码(AppSecret)** 点击「重置」后生成——**只会完整显示这一次**，请立刻复制保存；之后忘记只能再点「重置」（需管理员扫码确认），且重置后旧 AppSecret 立即失效。
+
+### 2.2 配置 IP 白名单（关键，编辑位置在这里）
+
+1. 登录微信公众平台：https://mp.weixin.qq.com；
+2. 左侧菜单点 **「设置与开发」→「开发接口管理」**；
+3. 找到 **「IP白名单」** 栏目，点右侧的 **「修改」**；
+4. 输入 **部署本服务器那台机器的公网出口 IP**（可填多个，用逗号分隔），点 **「确认修改」** 保存。
+
+> 如何获取部署机的出口 IP：在部署机的 CMD / 终端执行
+> ```cmd
+> curl "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=你的AppID&secret=你的AppSecret"
+> ```
+> 若返回 `40164 invalid ip <你的IP> not in whitelist`，尖括号里的 IP 就是要填进白名单的那个；填好后再执行一次，直到返回 `access_token` 即配置成功。
+>
+> ⚠️ 出口 IP 可能随网络环境变化（如家庭宽带重拨、换服务器），**换网络后必须重新加白名单**。
+
+## 3. 启动服务器
+
+```bash
+# 默认 SSE 协议，端口 8000（交互式终端）
+wechat-oa-mcp
+# 或
+python -m wechat_oa_mcp
+
+# 指定端口 / 协议 / 调试模式
+wechat-oa-mcp --port 8123
+wechat-oa-mcp --transport stdio        # stdio 模式（客户端自行拉起时自动生效）
+wechat-oa-mcp --debug
+```
+
+> ⚠️ **后台 / 服务化部署（nohup、systemd、launchd 等）必须显式加 `--transport sse`**：
+> ```bash
+> nohup wechat-oa-mcp --transport sse --port 8000 > mcp.log 2>&1 &
+> ```
+> 因为非终端环境下程序无法区分「后台运行」与「被 MCP 客户端以管道拉起」，未显式指定协议时默认走 stdio（供 npx inspector / 客户端拉起使用），此时不会监听端口。
+
+启动后 SSE 端点：`http://localhost:8000/sse`
+
+## 4. 接入 MCP 客户端
+
+### SSE 方式（需服务器保持运行）
+
+```json
+{
+  "mcpServers": {
+    "wechat_oa_mcp": {
+      "type": "sse",
+      "url": "http://localhost:8000/sse"
+    }
+  }
+}
+```
+
+### stdio 方式（客户端自动拉起，推荐）
+
+```json
+{
+  "mcpServers": {
+    "wechat_oa_mcp": {
+      "type": "stdio",
+      "command": "wechat-oa-mcp",
+      "args": ["--transport", "stdio"]
+    }
+  }
+}
+```
+
+> 若 `command` 用虚拟环境安装，请填 venv 内的绝对路径，如 `/path/to/.venv/bin/wechat-oa-mcp`。
+
+## 5. 可用工具
+
+| 工具 | 必填参数 | 说明 |
+|---|---|---|
+| `WeChat_get_access_token` | AppID, AppSecret | 获取 access_token（有效期 7200 秒） |
+| `WeChat_create_draft` | access_token, image_url, title, content | 下载封面图→上传永久素材→创建图文草稿；可选 author / digest / content_source_url / need_open_comment |
+| `WeChat_publish_draft` | access_token, draft_media_id | 发布草稿（异步任务，返回 publish_id） |
+| `WeChat_del_draft` | access_token, media_id | 删除草稿 |
+| `WeChat_del_material` | access_token, media_id | 删除永久素材 |
+
+**调用顺序**：先 `WeChat_get_access_token` 拿 token，再调其余工具（token 2 小时内有效）。
+
+**注意**：`WeChat_create_draft` 会真实上传图片并在公众号后台创建草稿，属真实写操作，建议先在测试号或测试内容上验证。
+
+## 6. 常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| 40164 | IP 不在白名单 | 把部署机出口 IP 加入公众号 IP 白名单 |
+| 41001 | access_token missing / invalid | 确认已先调用 get_access_token 且 token 未过期 |
+| 40007 | invalid media_id | media_id 不存在或已删除 |
+| 45009 | 接口调用超限 | 微信接口有频率限制，稍后重试 |
+
+## 7. 验证安装
+
+```bash
+# 检查命令可用
+wechat-oa-mcp --help
+
+# 无副作用验证（不创建任何资源）：
+# 用 MCP Inspector 或客户端调用 WeChat_get_access_token，成功即说明配置就绪
+npx @modelcontextprotocol/inspector python -m wechat_oa_mcp
+```
+
+## 免责声明
+
+本工具仅限研究用途，禁止用于商业目的。使用者需自行遵守微信公众平台服务条款。

wechat_oa_mcp_direct-0.2.0/README.md

@@ -0,0 +1,162 @@
+# wechat-oa-mcp-direct
+
+微信公众号 MCP 服务器 —— **直连微信官方 API 版**。
+
+基于 FastMCP 4.x 实现，提供公众号草稿创建 / 发布 / 删除、永久素材删除、access_token 获取共 5 个 MCP 工具。所有请求直连 `api.weixin.qq.com`，**不经过任何第三方中转服务器**，AppID / AppSecret 只在部署机与微信之间传输。
+
+> 与 PyPI 上的 `wechat-oa-mcp 0.1.0` 的区别：旧版会把你的 AppSecret 转发到作者的服务器（106.15.125.133）中转，且依赖已废弃的 MCP SDK v1 API，无法在新环境启动。本包修复了上述问题（含 41001 access_token missing 修复）。
+
+---
+
+> ## ⚠️ 部署前必读：IP 白名单（最容易踩的坑）
+>
+> 部署好后首次调用工具，如果返回 **`40164 invalid ip ... not in whitelist`** —— **不是代码问题**，是这台部署机的公网出口 IP 还没有加进公众号的 IP 白名单。
+>
+> - **每台部署机器都要把「它自己的出口 IP」加进白名单**（不同机器的 IP 不一样）；
+> - **换网络、换服务器、IP 变化后都要重新加**，否则之前能用的机器会突然报 40164；
+> - 获取出口 IP 和配置方法见下文「2.2 配置 IP 白名单」。
+
+---
+
+## 1. 安装
+
+### Windows CMD 一键安装（最简便，无需虚拟环境）
+
+解压 zip 后，在 CMD 中进入解压出来的目录，一条命令安装：
+
+```cmd
+cd wechat-oa-mcp-direct
+pip install .
+```
+
+安装完成后验证：
+
+```cmd
+wechat-oa-mcp --help
+```
+
+### macOS / Linux，或需要环境隔离时
+
+```bash
+cd wechat-oa-mcp-direct
+python3 -m venv .venv
+source .venv/bin/activate        # Windows 虚拟环境: .venv\Scripts\activate
+pip install .
+```
+
+要求：Python >= 3.10（Windows 安装 Python 时记得勾选 **"Add Python to PATH"**，否则 CMD 里 `pip` 会提示找不到命令）。
+
+## 2. 前置配置（部署机必须完成）
+
+### 2.1 获取公众号凭证（AppID / AppSecret 在哪里）
+
+1. 用管理员微信扫码登录微信公众平台：https://mp.weixin.qq.com（需要先注册一个公众号，订阅号/服务号均可）；
+2. 左侧菜单点 **「设置与开发」→「基本配置」**；
+3. 页面上的 **开发者ID(AppID)** 就是 AppID；
+4. **开发者密码(AppSecret)** 点击「重置」后生成——**只会完整显示这一次**，请立刻复制保存；之后忘记只能再点「重置」（需管理员扫码确认），且重置后旧 AppSecret 立即失效。
+
+### 2.2 配置 IP 白名单（关键，编辑位置在这里）
+
+1. 登录微信公众平台：https://mp.weixin.qq.com；
+2. 左侧菜单点 **「设置与开发」→「开发接口管理」**；
+3. 找到 **「IP白名单」** 栏目，点右侧的 **「修改」**；
+4. 输入 **部署本服务器那台机器的公网出口 IP**（可填多个，用逗号分隔），点 **「确认修改」** 保存。
+
+> 如何获取部署机的出口 IP：在部署机的 CMD / 终端执行
+> ```cmd
+> curl "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=你的AppID&secret=你的AppSecret"
+> ```
+> 若返回 `40164 invalid ip <你的IP> not in whitelist`，尖括号里的 IP 就是要填进白名单的那个；填好后再执行一次，直到返回 `access_token` 即配置成功。
+>
+> ⚠️ 出口 IP 可能随网络环境变化（如家庭宽带重拨、换服务器），**换网络后必须重新加白名单**。
+
+## 3. 启动服务器
+
+```bash
+# 默认 SSE 协议，端口 8000（交互式终端）
+wechat-oa-mcp
+# 或
+python -m wechat_oa_mcp
+
+# 指定端口 / 协议 / 调试模式
+wechat-oa-mcp --port 8123
+wechat-oa-mcp --transport stdio        # stdio 模式（客户端自行拉起时自动生效）
+wechat-oa-mcp --debug
+```
+
+> ⚠️ **后台 / 服务化部署（nohup、systemd、launchd 等）必须显式加 `--transport sse`**：
+> ```bash
+> nohup wechat-oa-mcp --transport sse --port 8000 > mcp.log 2>&1 &
+> ```
+> 因为非终端环境下程序无法区分「后台运行」与「被 MCP 客户端以管道拉起」，未显式指定协议时默认走 stdio（供 npx inspector / 客户端拉起使用），此时不会监听端口。
+
+启动后 SSE 端点：`http://localhost:8000/sse`
+
+## 4. 接入 MCP 客户端
+
+### SSE 方式（需服务器保持运行）
+
+```json
+{
+  "mcpServers": {
+    "wechat_oa_mcp": {
+      "type": "sse",
+      "url": "http://localhost:8000/sse"
+    }
+  }
+}
+```
+
+### stdio 方式（客户端自动拉起，推荐）
+
+```json
+{
+  "mcpServers": {
+    "wechat_oa_mcp": {
+      "type": "stdio",
+      "command": "wechat-oa-mcp",
+      "args": ["--transport", "stdio"]
+    }
+  }
+}
+```
+
+> 若 `command` 用虚拟环境安装，请填 venv 内的绝对路径，如 `/path/to/.venv/bin/wechat-oa-mcp`。
+
+## 5. 可用工具
+
+| 工具 | 必填参数 | 说明 |
+|---|---|---|
+| `WeChat_get_access_token` | AppID, AppSecret | 获取 access_token（有效期 7200 秒） |
+| `WeChat_create_draft` | access_token, image_url, title, content | 下载封面图→上传永久素材→创建图文草稿；可选 author / digest / content_source_url / need_open_comment |
+| `WeChat_publish_draft` | access_token, draft_media_id | 发布草稿（异步任务，返回 publish_id） |
+| `WeChat_del_draft` | access_token, media_id | 删除草稿 |
+| `WeChat_del_material` | access_token, media_id | 删除永久素材 |
+
+**调用顺序**：先 `WeChat_get_access_token` 拿 token，再调其余工具（token 2 小时内有效）。
+
+**注意**：`WeChat_create_draft` 会真实上传图片并在公众号后台创建草稿，属真实写操作，建议先在测试号或测试内容上验证。
+
+## 6. 常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| 40164 | IP 不在白名单 | 把部署机出口 IP 加入公众号 IP 白名单 |
+| 41001 | access_token missing / invalid | 确认已先调用 get_access_token 且 token 未过期 |
+| 40007 | invalid media_id | media_id 不存在或已删除 |
+| 45009 | 接口调用超限 | 微信接口有频率限制，稍后重试 |
+
+## 7. 验证安装
+
+```bash
+# 检查命令可用
+wechat-oa-mcp --help
+
+# 无副作用验证（不创建任何资源）：
+# 用 MCP Inspector 或客户端调用 WeChat_get_access_token，成功即说明配置就绪
+npx @modelcontextprotocol/inspector python -m wechat_oa_mcp
+```
+
+## 免责声明
+
+本工具仅限研究用途，禁止用于商业目的。使用者需自行遵守微信公众平台服务条款。

wechat_oa_mcp_direct-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wechat-oa-mcp-direct"
+version = "0.2.0"
+description = "微信公众号 MCP 服务器（直连微信官方 API 版）：草稿创建/发布/删除、素材删除、access_token 获取"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Jupiter", email = "jupiter3019@163.com" }]
+keywords = ["wechat", "mcp", "fastmcp", "公众号"]
+dependencies = [
+    "fastmcp>=4.0",
+    "requests>=2.25",
+]
+
+[project.scripts]
+wechat-oa-mcp = "wechat_oa_mcp.cli:main"
+wechat-oa-mcp-direct = "wechat_oa_mcp.cli:main"
+
+[tool.setuptools]
+packages = ["wechat_oa_mcp"]

wechat_oa_mcp_direct-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp/__init__.py

@@ -0,0 +1,24 @@
+"""
+微信公众号MCP服务器源代码包
+
+此 MCP 服务器仅限研究用途，禁止用于商业目的。
+"""
+
+# 导入所有公开API
+from wechat_oa_mcp.server import (
+    WeChat_get_access_token,
+    WeChat_create_draft,
+    WeChat_publish_draft,
+    WeChat_del_draft,
+    WeChat_del_material,
+    run
+)
+
+__all__ = [
+    'WeChat_get_access_token',
+    'WeChat_create_draft',
+    'WeChat_publish_draft',
+    'WeChat_del_draft',
+    'WeChat_del_material',
+    'run'
+] 

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp/__main__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+"""
+WeChat OA MCP 包的直接执行入口点
+当使用 python -m wechat_oa_mcp 命令时会执行此文件
+"""
+
+from wechat_oa_mcp.cli import main
+
+if __name__ == "__main__":
+    main() 

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp/cli.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+"""
+WeChat OA MCP 服务器命令行入口模块
+提供便捷的启动服务器和调用微信公众号API的功能
+"""
+
+import argparse
+import sys
+import os
+from wechat_oa_mcp.server import run
+
+def main():
+    """
+    命令行入口点函数
+    启动WeChat OA MCP服务器
+    """
+    # 创建命令行参数解析器
+    parser = argparse.ArgumentParser(description="WeChat OA MCP 服务器")
+    parser.add_argument("--port", type=int, help="指定服务器端口")
+    parser.add_argument("--transport", type=str, choices=["sse", "stdio", "streamable-http"],
+                      default=None, help="指定通信协议（默认 sse；未指定且通过管道运行时自动切换 stdio）")
+    parser.add_argument("--debug", action="store_true", help="启用调试模式")
+    args = parser.parse_args()
+
+    # 检测是否通过管道方式运行（如 npx inspector）
+    is_piped = not os.isatty(sys.stdin.fileno()) or not os.isatty(sys.stdout.fileno())
+
+    # 显式指定 --transport 时尊重用户选择（后台/服务化部署场景）；
+    # 未指定时：管道运行（npx inspector）切 stdio，否则默认 sse
+    if args.transport is not None:
+        transport = args.transport
+    else:
+        transport = "stdio" if is_piped else "sse"
+
+    try:
+        run(transport=transport, port=args.port, debug=args.debug)
+    except KeyboardInterrupt:
+        print("\n服务器已停止")
+    except Exception as e:
+        print(f"服务器异常: {str(e)}")
+        return 1
+    return 0
+
+if __name__ == "__main__":
+    main() 

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp/server.py

@@ -0,0 +1,380 @@
+"""
+微信公众号MCP服务器核心实现（直连微信官方API版）
+
+本版本由原包改造：
+- 移除第三方中转服务器（106.15.125.133），全部请求直连微信官方接口 api.weixin.qq.com
+- 适配 FastMCP 4.x（fastmcp 包，而非 mcp.server.fastmcp）
+
+使用前置条件：
+1. 公众号后台「设置与开发 → 开发接口管理」获取 AppID / AppSecret
+2. 将本机公网出口 IP 加入公众号「IP白名单」（否则获取 access_token 会返回 40164）
+3. 注意微信接口调用频率限制
+"""
+
+import os
+import tempfile
+from typing import Any, Dict
+
+import requests
+from fastmcp import FastMCP
+
+# 微信官方 API 基础地址
+API_BASE = "https://api.weixin.qq.com"
+
+# 创建 FastMCP 服务器实例
+mcp = FastMCP("wechat_oa_mcp")
+
+
+def _unwrap(args) -> Dict[str, Any]:
+    """兼容两种入参形式：直接字典，或带 input 属性的对象"""
+    if hasattr(args, "input"):
+        return args.input
+    return args
+
+
+def _post(url: str, payload: Dict[str, Any] = None, timeout: int = 10, access_token: str = None) -> Dict[str, Any]:
+    """发送 JSON POST 请求并解析微信响应，业务错误抛出 ValueError
+
+    注意：微信的 POST 接口要求 access_token 放在 URL query 中，不能放在 body 里，
+    否则会返回 41001 access_token missing。
+    """
+    params = {"access_token": access_token} if access_token else None
+    resp = requests.post(url, json=payload, params=params, timeout=timeout)
+    resp.raise_for_status()
+    data = resp.json()
+    if isinstance(data, dict) and data.get("errcode") not in (None, 0):
+        raise ValueError(f"微信API错误: {data.get('errcode')} {data.get('errmsg')}")
+    return data
+
+
+def _upload_image_to_material(access_token: str, image_url: str) -> str:
+    """下载远程封面图并上传为永久图片素材，返回 thumb_media_id"""
+    img_resp = requests.get(image_url, timeout=20)
+    img_resp.raise_for_status()
+
+    suffix = os.path.splitext(image_url.split("?")[0])[1] or ".jpg"
+    fd, tmp_path = tempfile.mkstemp(suffix=suffix)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(img_resp.content)
+        with open(tmp_path, "rb") as f:
+            up_resp = requests.post(
+                f"{API_BASE}/cgi-bin/material/add_material",
+                params={"access_token": access_token, "type": "image"},
+                files={"media": (os.path.basename(tmp_path), f, "application/octet-stream")},
+                timeout=60,
+            )
+        up_resp.raise_for_status()
+        data = up_resp.json()
+        if data.get("errcode") not in (None, 0):
+            raise ValueError(f"上传封面图失败: {data.get('errcode')} {data.get('errmsg')}")
+        media_id = data.get("media_id")
+        if not media_id:
+            raise ValueError(f"上传封面图响应缺少media_id: {data}")
+        return media_id
+    finally:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+
+
+@mcp.tool()
+def WeChat_get_access_token(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    获取微信公众号Access Token
+
+    Metadata:
+    - input: AppID, AppSecret
+    - output: success, error, access_token, expires_in
+
+    参数说明:
+    - AppID: 公众号唯一凭证（设置与开发-开发接口管理中获取）；未传时自动读取环境变量 WECHAT_APPID
+    - AppSecret: 公众号凭证密钥（设置与开发-开发接口管理中获取）；未传时自动读取环境变量 WECHAT_APPSECRET
+    - expires_in: 凭证有效时间(秒)，默认7200
+    """
+    p = _unwrap(args)
+    logger = getattr(args, "logger", None) or type("", (), {"debug": print, "error": print})
+    try:
+        appid = p.get("AppID") or os.environ.get("WECHAT_APPID", "")
+        appsecret = p.get("AppSecret") or os.environ.get("WECHAT_APPSECRET", "")
+        if not appid or not appsecret:
+            raise ValueError("缺少 AppID/AppSecret：请传入参数或设置环境变量 WECHAT_APPID / WECHAT_APPSECRET")
+        resp = requests.get(
+            f"{API_BASE}/cgi-bin/token",
+            params={
+                "grant_type": "client_credential",
+                "appid": appid,
+                "secret": appsecret,
+            },
+            timeout=10,
+        )
+        resp.raise_for_status()
+        result = resp.json()
+        if result.get("errcode") not in (None, 0):
+            raise ValueError(f"获取access_token失败: {result.get('errcode')} {result.get('errmsg')}")
+        if not result.get("access_token"):
+            raise ValueError(f"未能获取有效的access_token: {result}")
+        logger.debug(f"获取token成功，expires_in={result.get('expires_in')}")
+        return {
+            "success": True,
+            "error": None,
+            "access_token": result.get("access_token"),
+            "expires_in": result.get("expires_in", 7200),
+        }
+    except requests.exceptions.RequestException as e:
+        logger.error(f"HTTP请求失败: {str(e)}")
+        return {"success": False, "error": f"HTTP请求异常: {str(e)}", "access_token": None, "expires_in": None}
+    except ValueError as e:
+        logger.error(f"业务错误: {str(e)}")
+        return {"success": False, "error": str(e), "access_token": None, "expires_in": None}
+    except Exception as e:
+        logger.error(f"未知错误: {str(e)}")
+        return {"success": False, "error": f"系统错误: {str(e)}", "access_token": None, "expires_in": None}
+
+
+@mcp.tool()
+def WeChat_create_draft(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    创建微信公众号草稿
+
+    Metadata:
+    - input: access_token, image_url, title, content, author, digest, content_source_url, need_open_comment
+    - output: success, error, draft_media_id, image_media_id
+
+    参数说明:
+    - access_token: 接口凭证（通过WeChat_get_access_token获取）
+    - image_url: 封面图片URL（将被下载并上传为永久素材）
+    - title: 文章标题
+    - content: 图文消息内容，支持HTML，<2万字符，<1M
+    - author: (可选)作者名称
+    - digest: (可选)摘要，默认抓取正文前54字
+    - content_source_url: (可选)原文URL，点击"阅读原文"跳转
+    - need_open_comment: (可选)0关闭评论(默认)，1开启
+    """
+    p = _unwrap(args)
+    logger = getattr(args, "logger", None) or type("", (), {"debug": print, "error": print})
+    try:
+        access_token = p.get("access_token", "")
+        image_url = p.get("image_url", "")
+        title = p.get("title", "")
+        content = p.get("content", "")
+        if not access_token or not image_url or not title or not content:
+            raise ValueError("缺少必填参数: access_token/image_url/title/content")
+
+        # 1. 上传封面图为永久图片素材
+        thumb_media_id = _upload_image_to_material(access_token, image_url)
+        logger.debug(f"封面图上传成功，thumb_media_id={thumb_media_id}")
+
+        # 2. 组装图文消息
+        article: Dict[str, Any] = {
+            "title": title,
+            "content": content,
+            "thumb_media_id": thumb_media_id,
+        }
+        if p.get("author"):
+            article["author"] = p.get("author")
+        if p.get("digest"):
+            article["digest"] = p.get("digest")
+        if p.get("content_source_url"):
+            article["content_source_url"] = p.get("content_source_url")
+        if p.get("need_open_comment") in (0, 1):
+            article["need_open_comment"] = int(p.get("need_open_comment"))
+        if p.get("need_open_reprint") in (0, 1):
+            article["need_open_reprint"] = int(p.get("need_open_reprint"))
+
+        # 3. 创建草稿
+        result = _post(
+            f"{API_BASE}/cgi-bin/draft/add",
+            payload={"articles": [article]},
+            timeout=30,
+            access_token=access_token,
+        )
+        draft_media_id = result.get("media_id")
+        if not draft_media_id:
+            raise ValueError(f"创建草稿响应缺少media_id: {result}")
+        logger.debug(f"草稿创建成功，draft_media_id={draft_media_id}")
+        return {
+            "success": True,
+            "error": None,
+            "draft_media_id": draft_media_id,
+            "image_media_id": thumb_media_id,
+        }
+    except requests.exceptions.RequestException as e:
+        logger.error(f"网络请求异常: {str(e)}")
+        return {"success": False, "error": f"网络请求异常: {str(e)}", "draft_media_id": None, "image_media_id": None}
+    except ValueError as e:
+        logger.error(f"业务错误: {str(e)}")
+        return {"success": False, "error": str(e), "draft_media_id": None, "image_media_id": None}
+    except Exception as e:
+        logger.error(f"未知错误: {str(e)}")
+        return {"success": False, "error": f"系统异常: {str(e)}", "draft_media_id": None, "image_media_id": None}
+
+
+@mcp.tool()
+def WeChat_publish_draft(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    发布微信公众号草稿
+
+    Metadata:
+    - input: access_token, draft_media_id
+    - output: success, error, errmsg, publish_id
+
+    参数说明:
+    - access_token: 接口凭证（通过WeChat_get_access_token获取）
+    - draft_media_id: 草稿ID，即WeChat_create_draft返回的draft_media_id
+    - publish_id: 发布任务ID（发布为异步任务，可通过公众号后台查看结果）
+    """
+    p = _unwrap(args)
+    logger = getattr(args, "logger", None) or type("", (), {"debug": print, "error": print})
+    try:
+        access_token = p.get("access_token", "")
+        draft_media_id = p.get("draft_media_id", "")
+        if not access_token or not draft_media_id:
+            raise ValueError("缺少必填参数: access_token/draft_media_id")
+
+        result = _post(
+            f"{API_BASE}/cgi-bin/freepublish/submit",
+            payload={"media_id": draft_media_id},
+            timeout=30,
+            access_token=access_token,
+        )
+        publish_id = result.get("publish_id", result.get("msg_id"))
+        if not publish_id:
+            raise ValueError(f"发布响应缺少publish_id: {result}")
+        logger.debug(f"发布任务已提交，publish_id={publish_id}")
+        return {
+            "success": True,
+            "error": None,
+            "errmsg": result.get("errmsg"),
+            "publish_id": publish_id,
+        }
+    except requests.exceptions.RequestException as e:
+        logger.error(f"网络请求异常: {str(e)}")
+        return {"success": False, "error": f"网络请求异常: {str(e)}", "publish_id": None}
+    except ValueError as e:
+        logger.error(f"业务错误: {str(e)}")
+        return {"success": False, "error": str(e), "publish_id": None}
+    except Exception as e:
+        logger.error(f"未知错误: {str(e)}")
+        return {"success": False, "error": f"系统错误: {str(e)}", "publish_id": None}
+
+
+@mcp.tool()
+def WeChat_del_draft(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    删除微信公众号草稿
+
+    Metadata:
+    - input: access_token, media_id
+    - output: success, error, errcode, errmsg
+
+    参数说明:
+    - access_token: 接口凭证（通过WeChat_get_access_token获取）
+    - media_id: 草稿ID，即WeChat_create_draft返回的draft_media_id
+    """
+    p = _unwrap(args)
+    logger = getattr(args, "logger", None) or type("", (), {"debug": print, "error": print})
+    try:
+        access_token = p.get("access_token", "")
+        media_id = p.get("media_id", "")
+        if not access_token or not media_id:
+            raise ValueError("缺少必填参数: access_token/media_id")
+
+        result = _post(
+            f"{API_BASE}/cgi-bin/draft/delete",
+            payload={"media_id": media_id},
+            timeout=15,
+            access_token=access_token,
+        )
+        logger.debug(f"草稿删除成功: {result}")
+        return {
+            "success": True,
+            "error": None,
+            "errcode": result.get("errcode"),
+            "errmsg": result.get("errmsg"),
+        }
+    except requests.exceptions.RequestException as e:
+        logger.error(f"网络请求异常: {str(e)}")
+        return {"success": False, "error": f"网络请求异常: {str(e)}", "errcode": None, "errmsg": None}
+    except ValueError as e:
+        logger.error(f"业务错误: {str(e)}")
+        return {"success": False, "error": str(e), "errcode": None, "errmsg": None}
+    except Exception as e:
+        logger.error(f"未知错误: {str(e)}")
+        return {"success": False, "error": f"系统错误: {str(e)}", "errcode": None, "errmsg": None}
+
+
+@mcp.tool()
+def WeChat_del_material(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    删除微信公众号永久素材
+
+    Metadata:
+    - input: access_token, media_id
+    - output: success, error, errcode, errmsg
+
+    参数说明:
+    - access_token: 接口凭证（通过WeChat_get_access_token获取）
+    - media_id: 永久素材ID，即WeChat_create_draft返回的image_media_id
+    """
+    p = _unwrap(args)
+    logger = getattr(args, "logger", None) or type("", (), {"debug": print, "error": print})
+    try:
+        access_token = p.get("access_token", "")
+        media_id = p.get("media_id", "")
+        if not access_token or not media_id:
+            raise ValueError("缺少必填参数: access_token/media_id")
+
+        result = _post(
+            f"{API_BASE}/cgi-bin/material/del_material",
+            payload={"media_id": media_id},
+            timeout=15,
+            access_token=access_token,
+        )
+        logger.debug(f"素材删除成功: {result}")
+        return {
+            "success": True,
+            "error": None,
+            "errcode": result.get("errcode"),
+            "errmsg": result.get("errmsg"),
+        }
+    except requests.exceptions.RequestException as e:
+        logger.error(f"网络请求异常: {str(e)}")
+        return {"success": False, "error": f"网络请求异常: {str(e)}", "errcode": None, "errmsg": None}
+    except ValueError as e:
+        logger.error(f"业务错误: {str(e)}")
+        return {"success": False, "error": str(e), "errcode": None, "errmsg": None}
+    except Exception as e:
+        logger.error(f"未知错误: {str(e)}")
+        return {"success": False, "error": f"系统错误: {str(e)}", "errcode": None, "errmsg": None}
+
+
+def run(transport: str = "sse", port: int = None, debug: bool = False) -> None:
+    """
+    启动WeChat OA MCP服务器
+
+    参数:
+        transport: 通信协议，支持 'sse', 'stdio', 'streamable-http'（默认 sse）
+        port: 服务器端口，默认 8000
+        debug: 是否启用调试模式
+    """
+    if transport != "stdio" or debug:
+        print(f"启动WeChat OA MCP服务器，通信协议: {transport}")
+        if port is not None:
+            print(f"使用自定义端口: {port}")
+
+    kwargs: Dict[str, Any] = {"transport": transport}
+    # stdio 模式不接受 port 参数；仅 HTTP/SSE 模式才传端口
+    if port is not None and transport != "stdio":
+        kwargs["port"] = port
+
+    try:
+        mcp.run(**kwargs)
+    except KeyboardInterrupt:
+        if transport != "stdio" or debug:
+            print("服务被用户中断")
+    except Exception as e:
+        if transport != "stdio" or debug:
+            print(f"服务启动失败: {str(e)}")
+        raise

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp_direct.egg-info/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: wechat-oa-mcp-direct
+Version: 0.2.0
+Summary: 微信公众号 MCP 服务器（直连微信官方 API 版）：草稿创建/发布/删除、素材删除、access_token 获取
+Author-email: Jupiter <jupiter3019@163.com>
+License: MIT
+Keywords: wechat,mcp,fastmcp,公众号
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=4.0
+Requires-Dist: requests>=2.25
+
+# wechat-oa-mcp-direct
+
+微信公众号 MCP 服务器 —— **直连微信官方 API 版**。
+
+基于 FastMCP 4.x 实现，提供公众号草稿创建 / 发布 / 删除、永久素材删除、access_token 获取共 5 个 MCP 工具。所有请求直连 `api.weixin.qq.com`，**不经过任何第三方中转服务器**，AppID / AppSecret 只在部署机与微信之间传输。
+
+> 与 PyPI 上的 `wechat-oa-mcp 0.1.0` 的区别：旧版会把你的 AppSecret 转发到作者的服务器（106.15.125.133）中转，且依赖已废弃的 MCP SDK v1 API，无法在新环境启动。本包修复了上述问题（含 41001 access_token missing 修复）。
+
+---
+
+> ## ⚠️ 部署前必读：IP 白名单（最容易踩的坑）
+>
+> 部署好后首次调用工具，如果返回 **`40164 invalid ip ... not in whitelist`** —— **不是代码问题**，是这台部署机的公网出口 IP 还没有加进公众号的 IP 白名单。
+>
+> - **每台部署机器都要把「它自己的出口 IP」加进白名单**（不同机器的 IP 不一样）；
+> - **换网络、换服务器、IP 变化后都要重新加**，否则之前能用的机器会突然报 40164；
+> - 获取出口 IP 和配置方法见下文「2.2 配置 IP 白名单」。
+
+---
+
+## 1. 安装
+
+### Windows CMD 一键安装（最简便，无需虚拟环境）
+
+解压 zip 后，在 CMD 中进入解压出来的目录，一条命令安装：
+
+```cmd
+cd wechat-oa-mcp-direct
+pip install .
+```
+
+安装完成后验证：
+
+```cmd
+wechat-oa-mcp --help
+```
+
+### macOS / Linux，或需要环境隔离时
+
+```bash
+cd wechat-oa-mcp-direct
+python3 -m venv .venv
+source .venv/bin/activate        # Windows 虚拟环境: .venv\Scripts\activate
+pip install .
+```
+
+要求：Python >= 3.10（Windows 安装 Python 时记得勾选 **"Add Python to PATH"**，否则 CMD 里 `pip` 会提示找不到命令）。
+
+## 2. 前置配置（部署机必须完成）
+
+### 2.1 获取公众号凭证（AppID / AppSecret 在哪里）
+
+1. 用管理员微信扫码登录微信公众平台：https://mp.weixin.qq.com（需要先注册一个公众号，订阅号/服务号均可）；
+2. 左侧菜单点 **「设置与开发」→「基本配置」**；
+3. 页面上的 **开发者ID(AppID)** 就是 AppID；
+4. **开发者密码(AppSecret)** 点击「重置」后生成——**只会完整显示这一次**，请立刻复制保存；之后忘记只能再点「重置」（需管理员扫码确认），且重置后旧 AppSecret 立即失效。
+
+### 2.2 配置 IP 白名单（关键，编辑位置在这里）
+
+1. 登录微信公众平台：https://mp.weixin.qq.com；
+2. 左侧菜单点 **「设置与开发」→「开发接口管理」**；
+3. 找到 **「IP白名单」** 栏目，点右侧的 **「修改」**；
+4. 输入 **部署本服务器那台机器的公网出口 IP**（可填多个，用逗号分隔），点 **「确认修改」** 保存。
+
+> 如何获取部署机的出口 IP：在部署机的 CMD / 终端执行
+> ```cmd
+> curl "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=你的AppID&secret=你的AppSecret"
+> ```
+> 若返回 `40164 invalid ip <你的IP> not in whitelist`，尖括号里的 IP 就是要填进白名单的那个；填好后再执行一次，直到返回 `access_token` 即配置成功。
+>
+> ⚠️ 出口 IP 可能随网络环境变化（如家庭宽带重拨、换服务器），**换网络后必须重新加白名单**。
+
+## 3. 启动服务器
+
+```bash
+# 默认 SSE 协议，端口 8000（交互式终端）
+wechat-oa-mcp
+# 或
+python -m wechat_oa_mcp
+
+# 指定端口 / 协议 / 调试模式
+wechat-oa-mcp --port 8123
+wechat-oa-mcp --transport stdio        # stdio 模式（客户端自行拉起时自动生效）
+wechat-oa-mcp --debug
+```
+
+> ⚠️ **后台 / 服务化部署（nohup、systemd、launchd 等）必须显式加 `--transport sse`**：
+> ```bash
+> nohup wechat-oa-mcp --transport sse --port 8000 > mcp.log 2>&1 &
+> ```
+> 因为非终端环境下程序无法区分「后台运行」与「被 MCP 客户端以管道拉起」，未显式指定协议时默认走 stdio（供 npx inspector / 客户端拉起使用），此时不会监听端口。
+
+启动后 SSE 端点：`http://localhost:8000/sse`
+
+## 4. 接入 MCP 客户端
+
+### SSE 方式（需服务器保持运行）
+
+```json
+{
+  "mcpServers": {
+    "wechat_oa_mcp": {
+      "type": "sse",
+      "url": "http://localhost:8000/sse"
+    }
+  }
+}
+```
+
+### stdio 方式（客户端自动拉起，推荐）
+
+```json
+{
+  "mcpServers": {
+    "wechat_oa_mcp": {
+      "type": "stdio",
+      "command": "wechat-oa-mcp",
+      "args": ["--transport", "stdio"]
+    }
+  }
+}
+```
+
+> 若 `command` 用虚拟环境安装，请填 venv 内的绝对路径，如 `/path/to/.venv/bin/wechat-oa-mcp`。
+
+## 5. 可用工具
+
+| 工具 | 必填参数 | 说明 |
+|---|---|---|
+| `WeChat_get_access_token` | AppID, AppSecret | 获取 access_token（有效期 7200 秒） |
+| `WeChat_create_draft` | access_token, image_url, title, content | 下载封面图→上传永久素材→创建图文草稿；可选 author / digest / content_source_url / need_open_comment |
+| `WeChat_publish_draft` | access_token, draft_media_id | 发布草稿（异步任务，返回 publish_id） |
+| `WeChat_del_draft` | access_token, media_id | 删除草稿 |
+| `WeChat_del_material` | access_token, media_id | 删除永久素材 |
+
+**调用顺序**：先 `WeChat_get_access_token` 拿 token，再调其余工具（token 2 小时内有效）。
+
+**注意**：`WeChat_create_draft` 会真实上传图片并在公众号后台创建草稿，属真实写操作，建议先在测试号或测试内容上验证。
+
+## 6. 常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| 40164 | IP 不在白名单 | 把部署机出口 IP 加入公众号 IP 白名单 |
+| 41001 | access_token missing / invalid | 确认已先调用 get_access_token 且 token 未过期 |
+| 40007 | invalid media_id | media_id 不存在或已删除 |
+| 45009 | 接口调用超限 | 微信接口有频率限制，稍后重试 |
+
+## 7. 验证安装
+
+```bash
+# 检查命令可用
+wechat-oa-mcp --help
+
+# 无副作用验证（不创建任何资源）：
+# 用 MCP Inspector 或客户端调用 WeChat_get_access_token，成功即说明配置就绪
+npx @modelcontextprotocol/inspector python -m wechat_oa_mcp
+```
+
+## 免责声明
+
+本工具仅限研究用途，禁止用于商业目的。使用者需自行遵守微信公众平台服务条款。

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp_direct.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+wechat_oa_mcp/__init__.py
+wechat_oa_mcp/__main__.py
+wechat_oa_mcp/cli.py
+wechat_oa_mcp/server.py
+wechat_oa_mcp_direct.egg-info/PKG-INFO
+wechat_oa_mcp_direct.egg-info/SOURCES.txt
+wechat_oa_mcp_direct.egg-info/dependency_links.txt
+wechat_oa_mcp_direct.egg-info/entry_points.txt
+wechat_oa_mcp_direct.egg-info/requires.txt
+wechat_oa_mcp_direct.egg-info/top_level.txt

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp_direct.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp_direct.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+wechat-oa-mcp = wechat_oa_mcp.cli:main
+wechat-oa-mcp-direct = wechat_oa_mcp.cli:main

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp_direct.egg-info/requires.txt

@@ -0,0 +1,2 @@
+fastmcp>=4.0
+requests>=2.25

wechat_oa_mcp_direct-0.2.0/wechat_oa_mcp_direct.egg-info/top_level.txt

@@ -0,0 +1 @@
+wechat_oa_mcp