wutongci
Crawl-MCP Server
🚀 真正能下载图片的微信文章抓取工具 - 基于Model Context Protocol (MCP)的智能抓取服务器，专为Cursor IDE和AI工具设计。
🎉 v1.1.0 重大升级：从"指令生成器"升级为"真正下载工具"，支持完整的图片本地化！
✨ 主要特性
🎯 核心功能 (v1.1.0)
- 真正的图片下载: ✅ 实际下载微信图片，不只是生成指令
- 双模式设计: 指令模式（学习用）+ 自动模式（效率用）
- 完整本地化: 图片下载 + 路径更新 + 离线可用的Markdown文档
- 智能处理: 微信域名识别、正确Headers、并发控制、重试机制
🔧 技术特色 (v1.1.0)
- 专业图片处理:
- 🎯 微信图片域名识别（mmbiz.qpic.cn）
- 🎯 正确的HTTP Headers（Referer, User-Agent）
- 🎯 wx_fmt参数处理（jpeg, png, gif）
- 🎯 并发控制（同时下载3张）+ 重试机制
- MCP协议支持: 完整的Model Context Protocol实现
- 模块化架构: ImageDownloader + ArticleProcessor + CrawlTool
- TypeScript支持: 完整的类型定义和编译支持
- Node.js 18+: 使用内置fetch API，无额外HTTP库依赖
🎮 Cursor IDE集成
- 一键安装:
npx crawl-mcp-server@1.1.0 - 开箱即用: 无需复杂配置，直接可用
- AI工具支持: 在Cursor中直接使用AI进行完整抓取
- 工具自动识别: Agent自动调用相关抓取工具
🚀 快速开始
💻 安装使用
方法1: npx直接运行（推荐）
# 使用最新的v1.1.0版本
npx crawl-mcp-server@1.1.0方法2: 全局安装
npm install -g crawl-mcp-server@1.1.0
crawl-mcp-server方法3: 项目本地安装
npm install crawl-mcp-server@1.1.0
npx crawl-mcp-server💡 提示: 推荐使用 `@1.1.0` 版本，确保获得最新的图片下载功能
🔌 Cursor IDE配置
创建MCP配置文件 在项目根目录创建
.cursor/mcp.json:{ "mcpServers": { "crawl-mcp": { "command": "npx", "args": ["-y", "crawl-mcp-server@1.1.0"], "env": { "NODE_ENV": "production" } } } }重启Cursor 重启Cursor让配置生效
开始使用 在Cursor中直接使用AI助手进行网页抓取：
指令模式（学习推荐）：
请使用crawl mcp抓取这篇微信文章：https://mp.weixin.qq.com/s/xxxxx自动模式（效率优先）：
我已经获取了HTML内容，请使用crawl mcp自动模式处理并下载图片
🛠️ MCP工具说明
1. crawl_wechat_article
单篇文章抓取工具
参数:
url(必需): 微信文章链接outputFormat(可选): 输出格式 (markdown/json/html，默认: markdown)strategy(可选): 抓取策略 (basic/conservative/fast，默认: basic)includeImages(可选): 是否包含图片 (默认: true)
示例:
{
"url": "https://mp.weixin.qq.com/s/example123",
"outputFormat": "markdown",
"strategy": "basic",
"includeImages": true
}2. crawl_wechat_batch
批量文章抓取工具
参数:
urls(必需): 文章链接数组outputFormat(可选): 输出格式strategy(可选): 抓取策略maxConcurrent(可选): 最大并发数 (默认: 3)
示例:
{
"urls": [
"https://mp.weixin.qq.com/s/example1",
"https://mp.weixin.qq.com/s/example2"
],
"outputFormat": "markdown",
"maxConcurrent": 2
}3. crawl_get_status
状态查询工具
参数:
sessionId(可选): 会话ID，不提供则返回所有会话状态
⚙️ 抓取策略说明
| 策略 | 速度 | 稳定性 | 适用场景 |
|---|---|---|---|
| fast | ⚡ 最快 | 🔸 一般 | 网络良好，页面简单 |
| basic | 🚀 中等 | ⭐ 平衡 | 大多数情况（推荐） |
| conservative | 🐌 较慢 | 💎 最稳定 | 网络不稳定，复杂页面 |
📦 项目结构
crawl-mcp/
├── src/
│ ├── core/ # 核心模块
│ │ ├── CrawlMCPServer.ts # MCP服务器
│ │ ├── CallOrchestrator.ts # 调用编排器
│ │ └── StateManager.ts # 状态管理
│ ├── adapters/ # 输出适配器
│ │ ├── MCPOutputAdapter.ts # MCP格式转换
│ │ └── FileOutputAdapter.ts # 文件输出
│ ├── clients/ # 客户端
│ │ └── PlaywrightMCPClient.ts # Playwright客户端
│ ├── processors/ # 内容处理器
│ │ ├── ContentExtractor.ts # 内容提取
│ │ ├── MarkdownConverter.ts # Markdown转换
│ │ └── ImageProcessor.ts # 图片处理
│ ├── tools/ # MCP工具定义
│ ├── types/ # TypeScript类型
│ └── utils/ # 工具函数
├── docs/ # 文档
├── examples/ # 示例代码
└── tests/ # 测试文件🧪 开发和测试
安装依赖
pnpm install构建项目
pnpm build运行测试
pnpm test本地开发
pnpm dev📊 测试覆盖
- ✅ 25个测试 全部通过
- 🧪 单元测试: 核心组件功能验证
- 🔗 集成测试: MCP协议完整性测试
- 📋 配置测试: 所有配置文件验证
🤝 贡献指南
- Fork 这个仓库
- 创建你的特性分支 (
git checkout -b feature/AmazingFeature) - 提交你的更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启一个 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🔗 相关链接
📞 支持
如果你遇到任何问题或有建议，请：
⭐ 如果这个项目对你有帮助，请给我们一个星标！
Made with ❤️ by wutongci