轻量研究MCP

Name: 轻量研究MCP
Author: Code-Hex

作者：Code-Hex7 星标更新：2025-06-16

安装使用来源：spider==github.com

项目介绍

LLM 研究员

一个轻量级的MCP（模型上下文协议）服务器，用于LLM编排，提供高效的网络内容搜索和提取功能。此命令行工具使LLM能够搜索DuckDuckGo并从网页中提取干净、适合LLM的内容。

使用TypeScript、tsup和vitest进行现代开发体验构建。

功能

MCP服务器支持：提供模型上下文协议服务器以集成LLM
免费操作：使用DuckDuckGo HTML端点（无API费用）
GitHub代码搜索：搜索GitHub存储库中的代码示例和实现模式
智能内容提取：Playwright + @mozilla/readability用于提取干净内容
优化LLM输出：清理后的Markdown（仅包含h1-h3、粗体、斜体和链接）
速率限制：尊重DuckDuckGo的每秒1次请求限制
跨平台：适用于macOS、Linux和WSL
多种模式：CLI、MCP服务器、搜索、直接URL和交互模式
类型安全：完整的TypeScript实现，严格类型检查
现代工具：使用tsup打包器和vitest测试构建

安装

预备条件

Node.js 20.0.0或更高版本
不需要本地安装Chrome（使用Playwright捆绑的Chromium）

设置

# 克隆或下载项目
cd light-research-mcp

# 安装依赖项（使用pnpm）
pnpm install

# 构建项目
pnpm build

# 安装Playwright浏览器
pnpm install-browsers

# 可选：全局链接以供系统范围访问
pnpm link --global

使用

MCP服务器模式

作为模型上下文协议服务器，为LLM提供搜索和内容提取工具：

# 启动MCP服务器（标准I/O传输）
llmresearcher --mcp

# 该服务器向MCP客户端提供以下工具：
# - github_code_search: 搜索GitHub存储库中的代码
# - duckduckgo_web_search: 使用DuckDuckGo搜索网络
# - extract_content: 从URL中提取详细内容

与Claude Code配合设置

# 将其添加为Claude Code的MCP服务器
claude mcp add light-research-mcp /path/to/light-research-mcp/dist/bin/llmresearcher.js --mcp

# 或者使用项目范围以便团队共享
claude mcp add light-research-mcp -s project /path/to/light-research-mcp/dist/bin/llmresearcher.js --mcp

# 列出已配置的服务器
claude mcp list

# 检查服务器状态
claude mcp get light-research-mcp

MCP工具使用示例

一旦配置好，您可以在Claude中使用这些工具：

> 在GitHub上搜索React钩子示例
工具：github_code_search
查询："useState useEffect hooks language:javascript"

> 搜索TypeScript最佳实践
工具：duckduckgo_web_search
查询："TypeScript最佳实践2024"
地区：us-en（或wt-wt表示无区域）

> 从搜索结果中提取内容
工具：extract_content
URL：https://example.com/article-from-search-results

命令行界面

# 搜索模式 - 搜索DuckDuckGo并交互式浏览结果
llmresearcher "机器学习转换器"

# GitHub代码搜索模式 - 搜索GitHub上的代码
llmresearcher -g "useState hooks language:typescript"

# 直接URL模式 - 从特定URL提取内容
llmresearcher -u https://example.com/article

# 交互模式 - 进入交互式搜索会话
llmresearcher

# 详细日志 - 查看详细的运行日志
llmresearcher -v "搜索查询"

# MCP服务器模式 - 作为模型上下文协议服务器启动
llmresearcher --mcp

开发

脚本

# 构建项目
pnpm build

# 监控模式构建（用于开发）
pnpm dev

# 运行测试
pnpm test

# CI模式运行测试（单次运行）
pnpm test:run

# 类型检查
pnpm type-check

# 清理构建产物
pnpm clean

# 安装Playwright浏览器
pnpm install-browsers

交互式命令

在搜索结果视图时：

1-10：按数字选择结果
b 或 back：返回到搜索结果
open <n>：在外部浏览器中打开结果#n
q 或 quit：退出程序

在查看内容时：

b 或 back：返回到搜索结果
/<term>：在提取的内容中搜索术语
open：在外部浏览器中打开当前页面
q或quit：退出程序

配置

环境变量

在项目根目录创建一个.env文件：

USER_AGENT=Mozilla/5.0 (compatible; LLMResearcher/1.0)
TIMEOUT=30000
MAX_RETRIES=3
RATE_LIMIT_DELAY=1000
CACHE_ENABLED=true
MAX_RESULTS=10

配置文件

在您的主目录中创建~/.llmresearcherrc：

{
  "userAgent": "Mozilla/5.0 (compatible; LLMResearcher/1.0)",
  "timeout": 30000,
  "maxRetries": 3,
  "rateLimitDelay": 1000,
  "cacheEnabled": true,
  "maxResults": 10
}

配置选项

选项	默认值	描述
`userAgent`	`Mozilla/5.0 (compatible; LLMResearcher/1.0)`	HTTP请求的用户代理
`timeout`	`30000`	请求超时时间（毫秒）
`maxRetries`	`3`	失败请求的最大重试次数
`rateLimitDelay`	`1000`	请求之间的延迟时间（毫秒）
`cacheEnabled`	`true`	启用/禁用本地缓存
`maxResults`	`10`	显示的最大搜索结果数

架构

核心组件

MCPResearchServer (src/mcp-server.ts)
- 模型上下文协议服务器实现
- 三个主要工具：github_code_search、duckduckgo_web_search、extract_content
- 用于LLM消费的JSON响应
DuckDuckGoSearcher (src/search.ts)
- 支持地区的DuckDuckGo搜索结果HTML抓取
- 解码/l/?uddg=格式链接
- 速率限制和重试逻辑
GitHubCodeSearcher (src/github-code-search.ts)
- 通过gh CLI集成GitHub代码搜索API
- 支持语言、仓库和文件过滤的高级查询
- 认证和速率限制
ContentExtractor (src/extractor.ts)
- 使用Playwright进行页面渲染并阻止资源加载
- 使用@mozilla/readability提取主要内容
- 使用DOMPurify进行清理和Markdown转换
CLIInterface (src/cli.ts)
- 交互式命令行界面
- 搜索结果导航
- 内容查看和文本搜索
Configuration (src/config.ts)
- 加载环境变量和RC文件配置
- 支持详细日志记录

内容处理流程

MCP服务器模式

搜索：
- DuckDuckGo：HTML端点 → 解析结果 → 分页的JSON响应
- GitHub：代码搜索API → 格式化结果 → 包含代码片段的JSON响应
提取：从搜索结果中的URL → Playwright导航 → 提取内容
处理：@mozilla/readability → DOMPurify清理 → 清洁的JSON输出
输出：结构化的JSON供LLM消费

CLI模式

搜索：DuckDuckGo HTML端点 → 解析结果 → 显示编号列表
提取：Playwright导航 → 阻止资源加载 → JS渲染
处理：@mozilla/readability → DOMPurify清理 → 转换为Turndown Markdown
输出：仅包含h1-h3、粗体、斜体和链接的清洁Markdown

安全特性

资源阻塞：防止加载图片、CSS和字体以提高速度和安全性
内容清理：DOMPurify移除脚本、iframe和其他危险元素
有限的Markdown：仅允许安全的格式化元素（h1-h3、strong、em、a）
速率限制：遵守DuckDuckGo的速率限制，并采用指数退避策略

示例

使用Claude Code的MCP服务器

1. GitHub代码搜索

你："查找用于状态管理的React钩子示例"

Claude使用github_code_search工具：
{
  "query": "useState useReducer状态管理language:javascript",
  "results": [
    {
      "title": "facebook/react/packages/react/src/ReactHooks.js",
      "url": "https://raw.githubusercontent.com/facebook/react/main/packages/react/src/ReactHooks.js",
      "snippet": "function useState(initialState) {\n  return dispatcher.useState(initialState);\n}"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "hasNextPage": true,
    "nextPageToken": "2"
  }
}

2. 带有地区的网络搜索

你："搜索日语的Vue.js教程"

Claude使用duckduckgo_web_search工具：
{
  "query": "Vue.js チュートリアル 入门",
  "locale": "jp-jp",
  "results": [
    {
      "title": "Vue.js入门指南",
      "url": "https://example.com/vue-tutorial",
      "snippet": "Vue.js的基本使用方法教程..."
    }
  ]
}

3. 内容提取

你："从那个Vue.js教程中提取全部内容"

Claude使用extract_content工具：
{
  "url": "https://example.com/vue-tutorial",
  "title": "Vue.js入门指南",
  "extractedAt": "2024-01-15T10:30:00.000Z",
  "content": "# Vue.js入门指南\n\nVue.js是...\n\n## 安装\n\n..."
}

CLI示例

基础搜索

$ llmresearcher "python网络爬虫"

🔍 搜索结果：
══════════════════════════════════════════════════

1. Python网络爬虫教程
   URL: https://realpython.com/python-web-scraping-practical-introduction/
   完整的Python网络爬虫教程，使用requests和Beautiful Soup...

2. 使用Python进行网络爬虫 - BeautifulSoup和requests
   URL: https://www.dataquest.io/blog/web-scraping-python-tutorial/
   学习如何使用Python、Beautiful Soup和requests进行网站爬虫...

══════════════════════════════════════════════════
命令：[1-10] 选择结果 | b) 返回 | q) 退出 | open <n>) 在浏览器中打开

> 1

📥 正在从“Python网络爬虫教程”中提取内容

📄 内容：
══════════════════════════════════════════════════

**Python网络爬虫教程**
来源：https://realpython.com/python-web-scraping-practical-introduction/
提取时间：2024-01-15T10:30:00.000Z

──────────────────────────────────────────────────

# Python网络爬虫：实用介绍

网络爬虫是从网络收集和解析原始数据的过程...

## 什么是网络爬虫？

网络爬虫是一种自动访问和提取大量数据的技术...

══════════════════════════════════════════════════
命令：b) 返回到结果 | /<term>) 在文本中搜索 | q) 退出 | open) 在浏览器中打开

> /beautiful soup

🔍 在文本中找到3个匹配项“beautiful soup”：
──────────────────────────────────────────────────
第15行：Beautiful Soup是一个用于解析HTML和XML文档的Python库。
第42行：from bs4 import BeautifulSoup
第67行：soup = BeautifulSoup(html_content, 'html.parser')

直接URL模式

$ llmresearcher -u https://docs.python.org/3/tutorial/

📄 内容：
══════════════════════════════════════════════════

**Python教程**
来源：https://docs.python.org/3/tutorial/
提取时间：2024-01-15T10:35:00.000Z

──────────────────────────────────────────────────

# Python教程

Python是一种易于学习的强大编程语言...

## 非正式的Python介绍

在下面的例子中，区分输入和输出...

详细模式

$ llmresearcher -v "nodejs教程"

[VERBOSE] 正在搜索：https://duckduckgo.com/html/?q=nodejs%20教程&kl=us-en
[VERBOSE] 响应：200，耗时847ms
[VERBOSE] 解析了10个结果
[VERBOSE] 启动浏览器...
[VERBOSE] 阻止资源：https://example.com/style.css
[VERBOSE] 阻止资源：https://example.com/image.png
[VERBOSE] 导航到页面...
[VERBOSE] 页面加载完成，耗时1243ms
[VERBOSE] 使用Readability处理内容...
[VERBOSE] Readability提取成功
[VERBOSE] 关闭浏览器...

测试

运行测试

# 在监控模式下运行测试
pnpm test

# 单次运行测试（CI模式）
pnpm test:run

# 运行带有覆盖率的测试
pnpm test -- --coverage

测试覆盖率

测试套件包括：

单元测试：单独组件测试
- search.test.ts：DuckDuckGo搜索功能、URL解码、速率限制
- extractor.test.ts：内容提取、Markdown转换、资源管理
- config.test.ts：配置验证和环境处理
集成测试：端到端工作流测试
- integration.test.ts：完整的搜索到提取工作流、错误处理、清理

测试特性

快速：由vitest提供快速反馈
类型安全：测试中全面支持TypeScript
隔离：每个测试清理其资源
全面：涵盖搜索、提取、配置和集成场景

故障排除

常见问题

“未找到浏览器”错误

pnpm install-browsers

速率限制问题

工具自动处理速率限制，延迟1秒
如果遇到429错误，工具将自动重试并采用指数退避策略

内容提取失败

一些站点可能会阻止自动化访问
工具包括回退提取方法（主→正文内容）
使用详细模式（-v）查看详细的错误信息

权限被拒绝（Unix/Linux）

chmod +x bin/llmresearcher.js

性能优化

该工具针对速度进行了优化：

资源阻塞：自动阻止图片、CSS和字体
网络空闲：等待JavaScript完成渲染
内容缓存：支持本地缓存以避免重复请求
最小依赖：使用轻量级、专注的库

开发

项目结构

light-research-mcp/
├── dist/                      # 构建的JavaScript文件（生成）
│   ├── bin/
│   │   └── llmresearcher.js   # CLI入口点（可执行文件）
│   └── *.js                   # 编译的TypeScript模块
├── src/                       # TypeScript源文件
│   ├── bin.ts                 # CLI入口点
│   ├── index.ts               # 主LLMResearcher类
│   ├── mcp-server.ts          # MCP服务器实现
│   ├── search.ts              # DuckDuckGo搜索实现
│   ├── github-code-search.ts  # GitHub代码搜索实现
│   ├── extractor.ts           # 使用Playwright的内容提取
│   ├── cli.ts                 # 交互式CLI界面
│   ├── config.ts              # 配置管理
│   └── types.ts               # TypeScript类型定义
├── test/                      # 测试文件（vitest）
│   ├── search.test.ts         # 搜索功能测试
│   ├── extractor.test.ts      # 内容提取测试
│   ├── config.test.ts         # 配置测试
│   ├── mcp-locale.test.ts     # MCP区域功能测试
│   ├── mcp-content-extractor.test.ts # MCP内容提取器测试
│   └── integration.test.ts    # 端到端集成测试
├── tsconfig.json              # TypeScript配置
├── tsup.config.ts             # 构建配置
├── vitest.config.ts           # 测试配置
├── package.json
└── README.md

依赖项

运行时依赖项

@modelcontextprotocol/sdk：模型上下文协议服务器实现
@mozilla/readability：从HTML中