API.md•6.21 kB
# API 文档
本文档详细描述了微信公众号文章读取 MCP 服务器的 API 接口。
## 概述
MCP 服务器提供三个主要工具：
1. `fetch_article` - 获取文章内容
2. `search_articles` - 搜索文章
3. `extract_article_summary` - 提取文章摘要
## 工具详情
### 1. 获取文章内容 (fetch_article)
#### 描述
从指定的微信公众号文章URL获取文章内容、元数据和统计信息。
#### 参数
| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| url | string | 是 | 微信公众号文章URL |
| content_formats | array | 否 | 内容格式列表，可选值：markdown, text。默认：["markdown", "text"] |
| request_id | string | 否 | 请求ID，用于跟踪请求 |
#### 示例请求
```json
{
"name": "fetch_article",
"arguments": {
"url": "https://mp.weixin.qq.com/s/xxxxxxxx",
"content_formats": ["markdown", "text"],
"request_id": "req_123456"
}
}
```
#### 成功响应
```json
{
"success": true,
"message": "文章获取成功",
"request_id": "req_123456",
"article": {
"url": "https://mp.weixin.qq.com/s/xxxxxxxx",
"title": "文章标题",
"author": "作者名称",
"publish_time": "2023-01-01",
"account_name": "公众号名称",
"account_id": "公众号ID",
"read_count": 1000,
"like_count": 100,
"comment_count": 50,
"extracted_at": "2023-01-01T12:00:00Z"
},
"content": {
"markdown": "# 文章标题\n\n文章内容...",
"text": "文章标题\n\n文章内容..."
}
}
```
#### 错误响应
```json
{
"success": false,
"message": "无效的微信文章URL",
"error_code": "INVALID_URL",
"error_type": "ValidationError",
"request_id": "req_123456"
}
```
### 2. 搜索文章 (search_articles)
#### 描述
根据关键词搜索微信公众号文章。
#### 参数
| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| query | string | 是 | 搜索关键词 |
| account | string | 否 | 指定公众号名称 |
| sort_by | string | 否 | 排序方式，可选值：relevance, time, popularity。默认：relevance |
| limit | integer | 否 | 返回结果数量限制，默认：10，最大：50 |
| request_id | string | 否 | 请求ID，用于跟踪请求 |
#### 示例请求
```json
{
"name": "search_articles",
"arguments": {
"query": "人工智能",
"account": "科技前沿",
"sort_by": "time",
"limit": 20,
"request_id": "req_123456"
}
}
```
#### 成功响应
```json
{
"success": true,
"message": "搜索完成",
"request_id": "req_123456",
"total": 100,
"results": [
{
"url": "https://mp.weixin.qq.com/s/xxxxxxxx1",
"title": "人工智能的发展趋势",
"author": "张三",
"publish_time": "2023-01-01",
"account_name": "科技前沿",
"account_id": "tech_frontier",
"read_count": 5000,
"like_count": 200,
"comment_count": 50
},
{
"url": "https://mp.weixin.qq.com/s/xxxxxxxx2",
"title": "AI在医疗领域的应用",
"author": "李四",
"publish_time": "2022-12-15",
"account_name": "科技前沿",
"account_id": "tech_frontier",
"read_count": 3000,
"like_count": 150,
"comment_count": 30
}
]
}
```
#### 错误响应
```json
{
"success": false,
"message": "搜索请求失败",
"error_code": "SEARCH_ERROR",
"error_type": "NetworkError",
"request_id": "req_123456"
}
```
### 3. 提取文章摘要 (extract_article_summary)
#### 描述
从指定的微信公众号文章URL提取文章摘要。
#### 参数
| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| url | string | 是 | 微信公众号文章URL |
| max_length | integer | 否 | 摘要最大长度，默认：200，最大：500 |
| request_id | string | 否 | 请求ID，用于跟踪请求 |
#### 示例请求
```json
{
"name": "extract_article_summary",
"arguments": {
"url": "https://mp.weixin.qq.com/s/xxxxxxxx",
"max_length": 150,
"request_id": "req_123456"
}
}
```
#### 成功响应
```json
{
"success": true,
"message": "摘要提取成功",
"request_id": "req_123456",
"title": "文章标题",
"url": "https://mp.weixin.qq.com/s/xxxxxxxx",
"summary": "这是文章的摘要内容，包含了文章的主要观点和结论..."
}
```
#### 错误响应
```json
{
"success": false,
"message": "无法提取文章摘要",
"error_code": "SUMMARY_ERROR",
"error_type": "ParsingError",
"request_id": "req_123456"
}
```
## 错误代码
| 错误代码 | 描述 | 处理建议 |
|----------|------|----------|
| INVALID_URL | 无效的微信文章URL | 检查URL格式是否正确 |
| NETWORK_ERROR | 网络请求失败 | 检查网络连接，稍后重试 |
| BROWSER_ERROR | 浏览器操作失败 | 重试请求或检查浏览器配置 |
| PARSING_ERROR | 内容解析失败 | 检查文章是否可正常访问 |
| VALIDATION_ERROR | 参数验证失败 | 检查请求参数是否正确 |
| SEARCH_ERROR | 搜索请求失败 | 检查搜索关键词，稍后重试 |
| SUMMARY_ERROR | 摘要提取失败 | 检查文章内容，稍后重试 |
| UNKNOWN_TOOL | 未知工具 | 检查工具名称是否正确 |
| TOOL_EXECUTION_ERROR | 工具执行错误 | 检查服务器日志，联系管理员 |
## 响应格式
所有工具返回统一的响应格式：
### 成功响应
```json
{
"success": true,
"message": "操作成功描述",
"request_id": "请求ID（可选）",
"data": {
// 具体数据内容，根据工具不同而不同
}
}
```
### 错误响应
```json
{
"success": false,
"message": "错误描述",
"error_code": "错误代码",
"error_type": "错误类型",
"request_id": "请求ID（可选）"
}
```
## 限制
- 请求超时时间：30秒
- 搜索结果最大数量：50
- 摘要最大长度：500字符
- 并发请求限制：根据服务器配置
## 最佳实践
1. **URL验证**：在调用前验证URL格式
2. **错误处理**：检查响应中的success字段
3. **重试机制**：对于网络错误，实现重试逻辑
4. **请求ID**：使用请求ID跟踪请求
5. **限制处理**：遵守API限制，避免过度请求