Medium Scraper MCP

中型刮板MCP服务器

一个全面的模型上下文协议（MCP）服务器，用于搜索Medium文章，将其转换为降价，并使用代理服务绕过付费墙。

特性

🔍 文章检索

• 按关键字和标签搜索媒体文章
• 可配置的结果限制（1-50篇文章）
• 丰富的文章元数据，包括标题、作者和片段

📝 Markdown转换

• 将Medium文章转换为干净、可读的标记
• 保留格式、代码块和图像
• 可定制的内容包含（图像、代码块）

🚫 支付墙旁路

• 自动付费墙检测
• 多种代理服务：freedium.cfd、readmedium.com、archive.today
• 可配置的代理首选项，具有自动回退功能
• 智能内容验证

⚡ 统一接口

• 单一工具，可执行多种操作
• 智能参数验证
• 全面的错误处理
• 具有完全类型安全的TypeScript实现

安装

选项1：从npm安装（推荐）

# Install globally
npm install -g medium-scraper-mcp

# Or run directly with npx
npx medium-scraper-mcp

# For MCP configuration, use npx in your MCP client settings

选项2：从源代码安装

# Clone repository
git clone https://github.com/hongkongkiwi/medium-scraper-mcp.git
cd medium-scraper-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run type-check

MCP服务器工具

服务器为所有Medium操作提供了一个统一的工具：

medium_scraper

一个统一的工具，用于搜索、转换和获取具有付费墙绕过功能的Medium文章信息。

参数：

• operation （必填）：要执行的操作

- "search"：通过查询/标签查找文章 - "convert"：将文章转换为markdown - "info"：获取文章元数据

• query （可选）：搜索查询字符串（搜索时必需）
• url （可选）：中等文章URL（转换/info需要）
• tag （可选）：要过滤的中等标签（例如“python”、“technology”）-仅用于搜索
• limit （可选）：最大结果数（默认值：10，最大值：50）-仅用于搜索
• includeImages （可选）：在markdown中包含图像引用（默认值：true）-仅用于转换
• includeCode （可选）：保留代码块（默认值：true）-仅用于转换
• bypassPaywall （可选）：尝试绕过付费墙（默认值：false）-仅适用于转换
• preferredProxy （可选）：首选代理服务（默认：“auto”）-仅用于转换

- "freedium"：使用freedium.cfd - "readmedium"：使用readmedium.com - "archive"：使用archive.today - "auto"：自动尝试所有代理

示例：

搜索文章

{
  "name": "medium_scraper",
  "arguments": {
    "operation": "search",
    "query": "machine learning",
    "tag": "python",
    "limit": 5
  }
}

使用付费墙旁路将文章转换为降价

{
  "name": "medium_scraper",
  "arguments": {
    "operation": "convert",
    "url": "https://medium.com/@author/article-title-1234567890",
    "includeImages": true,
    "includeCode": true,
    "bypassPaywall": true,
    "preferredProxy": "auto"
  }
}

获取文章信息

{
  "name": "medium_scraper",
  "arguments": {
    "operation": "info",
    "url": "https://medium.com/@author/article-title-1234567890"
  }
}

运行服务器

命令行接口命令模式

# Build and run
npm run build
npm start

# Development mode
npm run dev

# Verbose logging
npm run dev -- --verbose

MCP配置

添加到MCP客户端配置中：

对于npm安装：

{
  "mcpServers": {
    "medium-scraper": {
      "command": "npx",
      "args": ["medium-scraper-mcp"]
    }
  }
}

对于全局安装：

{
  "mcpServers": {
    "medium-scraper": {
      "command": "medium-scraper-mcp"
    }
  }
}

示例用法

搜索Python文章

{
  "name": "medium_scraper",
  "arguments": {
    "operation": "search",
    "query": "asyncio",
    "tag": "python",
    "limit": 3
  }
}

使用付费墙旁路将文章转换为降价

{
  "name": "medium_scraper",
  "arguments": {
    "operation": "convert",
    "url": "https://medium.com/@author/understanding-asyncio-in-python-1234567890",
    "bypassPaywall": true,
    "preferredProxy": "auto"
  }
}

获取文章信息

{
  "name": "medium_scraper",
  "arguments": {
    "operation": "info",
    "url": "https://medium.com/@author/understanding-asyncio-in-python-1234567890"
  }
}

依赖项

运行时依赖关系

• @modelcontextprotocol/sdk：MCP框架
• axios：HTTP客户端
• cheerio：HTML解析
• turndown：HTML到Markdown的转换
• zod：架构验证

开发依赖

• typescript：TypeScript编译器
• ts-node：TypeScript执行
• jest：测试框架
• eslint：代码linting
• @types/*：TypeScript定义

项目结构

src/
├── cli.ts              # Command line interface
├── server.ts           # MCP server implementation
├── medium-scraper.ts   # Medium scraping logic
├── types.ts           # TypeScript type definitions
└── index.ts           # Main exports

dist/                   # Compiled JavaScript files (generated)
├── cli.js
├── server.js
├── medium-scraper.js
├── types.js
└── index.js

api参考

中型刮刀类

`searchArticles(params: SearchParams): Promise

`

搜索Medium文章。

const articles = await mediumScraper.searchArticles({
  query: 'typescript',
  tag: 'programming',
  limit: 10
});

convertToMarkdown(params: ConvertParams): Promise

使用可选的付费墙旁路将Medium文章转换为markdown。

const markdown = await mediumScraper.convertToMarkdown({
  url: 'https://medium.com/@author/article-url',
  includeImages: true,
  includeCode: true,
  bypassPaywall: true,
  preferredProxy: 'auto'
});

`getArticleInfo(url: string): Promise

`

获取文章元数据。

const info = await mediumScraper.getArticleInfo('https://medium.com/@author/article-url');

支付墙旁路

服务器包括智能付费墙旁路功能：

自动检测：

• 检测HTML内容中的付费墙指示器
• 识别优质内容障碍
• 识别订阅提示

代理服务：

• 自由流体动力学：直接代理服务
• readmedium.com：特定文章代理
• 今日档案：基于存档的代理
• 自动模式：服务之间的智能回退

智能回退：

• 先尝试直接访问
• 检测到付费墙时回退到代理服务
• 故障时自动切换服务
• 内容验证以确保质量

许可证

MIT许可证

CI/CD管道

该项目使用GitHub Actions进行自动化测试、安全扫描和npm发布：

自动化测试

• 多节点测试：在Node.js 18、20和22上运行
• 类型检查：TypeScript编译验证
• 代码linting：使用TypeScript规则的ESLint
• 测试覆盖率：对报道进行恶作剧
• 安全审计：npm漏洞扫描
• 许可证合规性：自动许可证检查

自动发布

• 请释放：基于传统提交的自动化版本管理
• npm发布：发布时自动发布到npm
• GitHub发布：自动生成发行说明

发布过程

1. 功能开发：处理功能分支
2. 拉取请求：向主要分支机构开放PR
3. CI检查：所有测试和安全检查必须通过
4. 合并：合并到主触发器自动释放
5. 版本颠簸：发布请创建版本碰撞PR
6. 发布：合并版本碰撞触发npm发布

约定式提交

对于自动发布，请使用常规提交格式：

feat: add new search functionality
fix: resolve paywall bypass issues
docs: update installation instructions
chore: update dependencies

贡献

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 运行linting和类型检查
6. 提交拉取请求
7. 合并前确保CI检查通过

测试

该项目包括所有功能的Jest测试：

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

错误处理

服务器包括全面的错误处理：

• URL无效：返回用户友好的错误消息
• 网络错误：妥善处理连接问题
• 内容解析：优雅地处理格式错误的HTML
• 速率限制：尊重Medium的费率限制
• 验证：使用Zod模式进行输入验证
• 代理失败：代理服务之间的自动回退
• 支付墙检测：旁路故障时性能下降
• 内容提取：处理缺失或不完整的内容

错误类型

网络错误：

• 连接超时（代理服务为15秒）
• DNS解析失败
• HTTP状态错误（4xx、5xx）

内容错误：

• 缺少文章内容
• 格式错误的HTML结构
• 回答为空或不完整

验证错误：

• URL无效（格式验证）
• 缺少必要参数
• 超出范围值（例如，限值>50）

支付墙旁路错误：

• 所有代理服务均不可用
• 内容质量验证失败
• 代理服务超时

性能注意事项

• 异步/等待：无阻塞操作，性能更佳
• 连接复用：尽可能重用HTTP连接
• 内存效率高：以增量方式流式传输响应和处理内容
• 速率限制：内置延迟，避免淹没Medium的服务器