README.md•5.76 kB
# 微信公众号文章读取 MCP 服务器
这是一个基于 Model Context Protocol (MCP) 的服务器，用于读取微信公众号文章内容、搜索文章以及生成文章摘要。
## 功能特性
- **文章获取**：从微信公众号文章URL获取文章内容、元数据和统计信息
- **文章搜索**：根据关键词搜索微信公众号文章
- **文章摘要**：自动生成文章摘要，支持自定义长度
- **多格式输出**：支持Markdown和纯文本格式输出
- **错误处理**：完善的错误处理和响应格式化
- **性能优化**：支持并发请求和性能监控
## 安装与配置
### 环境要求
- Python 3.8+
- Playwright（用于浏览器自动化）
### 安装步骤
1. 克隆项目仓库：
```bash
git clone https://github.com/your-username/mcp-server-wechat.git
cd mcp-server-wechat
```
2. 创建虚拟环境：
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
```
3. 安装依赖：
```bash
pip install -r requirements.txt
```
4. 安装Playwright浏览器：
```bash
playwright install
```
### 配置
服务器支持多种配置方式：
1. **配置文件**：创建 `config.json` 文件：
```json
{
"transport": "stdio",
"host": "localhost",
"port": 8080,
"browser": {
"headless": true,
"timeout": 30000,
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
},
"request": {
"timeout": 30000,
"max_retries": 3,
"retry_delay": 1000
}
}
```
2. **环境变量**：
```bash
export MCP_SERVER_TRANSPORT=stdio
export MCP_SERVER_HOST=localhost
export MCP_SERVER_PORT=8080
export MCP_BROWSER_HEADLESS=true
export MCP_BROWSER_TIMEOUT=30000
```
## 使用方法
### 启动服务器
1. **STDIO模式**（默认）：
```bash
python main.py
```
2. **HTTP模式**：
```bash
python main.py --transport http --host 0.0.0.0 --port 8080
```
### MCP工具
#### 1. 获取文章内容
```python
# 调用fetch_article工具
{
"name": "fetch_article",
"arguments": {
"url": "https://mp.weixin.qq.com/s/xxxxxxxx",
"content_formats": ["markdown", "text"],
"request_id": "optional_request_id"
}
}
```
#### 2. 搜索文章
```python
# 调用search_articles工具
{
"name": "search_articles",
"arguments": {
"query": "搜索关键词",
"account": "可选的公众号名称",
"sort_by": "relevance", # relevance, time, popularity
"limit": 10,
"request_id": "optional_request_id"
}
}
```
#### 3. 提取文章摘要
```python
# 调用extract_article_summary工具
{
"name": "extract_article_summary",
"arguments": {
"url": "https://mp.weixin.qq.com/s/xxxxxxxx",
"max_length": 200,
"request_id": "optional_request_id"
}
}
```
### 响应格式
所有工具返回统一的响应格式：
```json
{
"success": true,
"message": "操作成功",
"request_id": "optional_request_id",
"data": {
// 具体数据内容
}
}
```
错误响应：
```json
{
"success": false,
"message": "错误描述",
"error_code": "ERROR_CODE",
"error_type": "ErrorType",
"request_id": "optional_request_id"
}
```
## 开发指南
### 项目结构
```
mcp-server-wechat/
├── src/
│ └── mcp_server_wechat/
│ ├── __init__.py
│ ├── main.py # 主服务器文件
│ ├── models.py # 数据模型和类型定义
│ ├── tools/
│ │ ├── __init__.py
│ │ └── wechat_tools.py # MCP工具实现
│ └── utils/
│ ├── __init__.py
│ ├── browser_client.py # 浏览器客户端
│ ├── article_parser.py # 文章解析器
│ ├── search_client.py # 搜索客户端
│ ├── summary_generator.py # 摘要生成器
│ └── response_formatter.py # 响应格式化器
├── tests/
│ ├── __init__.py
│ ├── test_wechat_tools.py # 单元测试
│ ├── test_integration.py # 集成测试
│ └── test_performance.py # 性能测试
├── config.json # 配置文件
├── requirements.txt # 依赖列表
├── run_tests.py # 测试运行器
└── README.md # 项目文档
```
### 运行测试
1. 运行所有测试：
```bash
python run_tests.py --type all
```
2. 运行单元测试：
```bash
python run_tests.py --type unit
```
3. 运行集成测试：
```bash
python run_tests.py --type integration
```
4. 运行性能测试：
```bash
python run_tests.py --type performance
```
### 添加新工具
1. 在 `src/mcp_server_wechat/tools/wechat_tools.py` 中添加新工具类
2. 在 `handle_list_tools` 函数中注册新工具
3. 在 `handle_call_tool` 函数中添加工具调用逻辑
4. 添加相应的测试用例
## 常见问题
### 1. 浏览器启动失败
确保已安装Playwright浏览器：
```bash
playwright install
```
### 2. 微信文章URL无效
确保URL格式正确：
```
https://mp.weixin.qq.com/s/xxxxxxxx
```
### 3. 搜索结果为空
检查搜索关键词是否正确，或尝试使用更通用的关键词。
### 4. 性能问题
调整浏览器配置中的超时时间，或使用HTTP模式以提高性能。
## 许可证
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
## 贡献
欢迎提交问题和拉取请求。请确保：
1. 代码符合项目风格
2. 添加适当的测试
3. 更新相关文档
## 联系方式
如有问题或建议，请通过以下方式联系：
- 提交 Issue: [GitHub Issues](https://github.com/your-username/mcp-server-wechat/issues)
- 邮箱: your-email@example.com