# 微信公众号文章读取 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