Light Research MCP

法学硕士研究员

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

内置于 TypeScript, tsup，以及 速度 现代发展经验。

特性

• MCP服务器支持：为LLM集成提供模型上下文协议服务器
• 自由操作：使用DuckDuckGo HTML端点（无API成本）
• GitHub代码搜索：在GitHub存储库中搜索代码示例和实现模式
• 智能内容提取：剧作家+@mozilla/内容清晰可读
• LLM优化输出：山宁泰Markdown（h1-h3，粗体，斜体，仅链接）
• 速率限制：尊重DuckDuckGo，每秒限制1个请求
• 交叉平台的：适用于macOS、Linux和WSL
• 多种模式：CLI、MCP服务器、搜索、直接URL和交互模式
• 类型安全：具有严格类型的完整TypeScript实现
• 现代工具：采用tsup bundler和vitest测试构建

安装

先决条件

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

设置

# Clone or download the project
cd light-research-mcp

# Install dependencies (using pnpm)
pnpm install

# Build the project
pnpm build

# Install Playwright browsers
pnpm install-browsers

# Optional: Link globally for system-wide access
pnpm link --global

用法

MCP服务器模式

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

# Start MCP server (stdio transport)
llmresearcher --mcp

# The server provides these tools to MCP clients:
# - github_code_search: Search GitHub repositories for code
# - duckduckgo_web_search: Search the web with DuckDuckGo
# - extract_content: Extract detailed content from URLs

使用Claude Code进行设置

# Add as an MCP server to Claude Code
claude mcp add light-research-mcp /path/to/light-research-mcp/dist/bin/llmresearcher.js --mcp

# Or with project scope for team sharing
claude mcp add light-research-mcp -s project /path/to/light-research-mcp/dist/bin/llmresearcher.js --mcp

# List configured servers
claude mcp list

# Check server status
claude mcp get light-research-mcp

MCP工具使用示例

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

> Search for React hooks examples on GitHub
Tool: github_code_search
Query: "useState useEffect hooks language:javascript"

> Search for TypeScript best practices
Tool: duckduckgo_web_search  
Query: "TypeScript best practices 2024"
Locale: us-en (or wt-wt for no region)

> Extract content from a search result
Tool: extract_content
URL: https://example.com/article-from-search-results

命令行接口

# Search mode - Search DuckDuckGo and interactively browse results
llmresearcher "machine learning transformers"

# GitHub Code Search mode - Search GitHub for code
llmresearcher -g "useState hooks language:typescript"

# Direct URL mode - Extract content from specific URL
llmresearcher -u https://example.com/article

# Interactive mode - Enter interactive search session
llmresearcher

# Verbose logging - See detailed operation logs
llmresearcher -v "search query"

# MCP Server mode - Start as Model Context Protocol server
llmresearcher --mcp

发展

脚本

# Build the project
pnpm build

# Build in watch mode (for development)
pnpm dev

# Run tests
pnpm test

# Run tests in CI mode (single run)
pnpm test:run

# Type checking
pnpm type-check

# Clean build artifacts
pnpm clean

# Install Playwright browsers
pnpm install-browsers

交互式命令

在搜索结果视图中：

• 1-10：按数字选择结果
• b 或 \：在外部浏览器中打开结果#n
• q 或 退出：退出程序

查看内容时：

• b 或 \：在提取的内容中搜索术语
• 打开：在外部浏览器中打开当前页面
• q 或 退出：退出程序

配置

环境变量

创建一个 .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
}

配置选项

建筑

核心组件

1. MCPResearch服务器 (src/mcp-server.ts)

- 模型上下文协议服务器实现 - 三个主要工具：github代码搜索、duckduckgo_web_search、extract_content - LLM消费的基于JSON的响应

1. DuckDuckGoSearcher (src/search.ts)

- 支持区域设置的DuckDuckGo搜索结果的HTML抓取 - URL解码 /l/?uddg= 格式化链接 - 速率限制和重试逻辑

1. GitHubCodeSearcher (src/github-code-search.ts)

- 通过gh CLI集成GitHub代码搜索API - 具有语言、存储库和文件过滤器的高级查询支持 - 身份验证和速率限制

1. 内容提取器 (src/extractor.ts)

- 基于剧作家的资源阻塞页面渲染 - @mozilla/主要内容提取的可读性 - DOMPurify净化和Markdown转换

1. CLIInterface (src/cli.ts)

- 交互式命令行界面 - 搜索结果导航 - 内容查看和文本搜索

1. 配置 (src/config.ts)

- 环境和RC文件配置加载 - 详细日志记录支持

内容处理管道

MCP服务器模式

1. 搜索:

- DuckDuckGo：HTML端点→ 解析结果→ 带分页的JSON响应 - GitHub:代码搜索API→ 格式化结果→ 带有代码片段的JSON响应

1. 提取：搜索结果中的URL→ 剧作家导航→ 内容提取
2. 过程：@mozilla/可读性→ DOMPurify消毒→ 干净的JSON输出
3. 输出：用于LLM消费的结构化JSON

命令行接口命令模式

1. 搜索：DuckDuckGo HTML端点→ 解析结果→ 显示编号列表
2. 提取：剧作家导航→ 资源阻塞→ JS渲染
3. 过程：@mozilla/可读性→ DOMPurify消毒→ 关闭Markdown
4. 输出：用h1-h3清除Markdown， 粗体, *斜体*, 链接 仅

安全功能

• 资源阻塞：防止加载图像、CSS、字体以提高速度和安全性
• 内容消毒：DOMPurify删除脚本、iframe和危险元素
• 有限Markdown：只允许安全格式化元素（h1-h3、strong、em、a）
• 速率限制：尊重DuckDuckGo的速率限制，指数回退

例子

使用Claude代码使用MCP服务器

1.GitHub代码搜索

You: "Find React hook examples for state management"

Claude uses github_code_search tool:
{
  "query": "useState useReducer state management 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.使用区域设置进行网络搜索

You: "Search for Vue.js tutorials in Japanese"

Claude uses duckduckgo_web_search tool:
{
  "query": "Vue.js チュートリアル 入門",
  "locale": "jp-jp",
  "results": [
    {
      "title": "Vue.js入門ガイド",
      "url": "https://example.com/vue-tutorial",
      "snippet": "Vue.jsの基本的な使い方を学ぶチュートリアル..."
    }
  ]
}

3.内容提取

You: "Extract the full content from that Vue.js tutorial"

Claude uses extract_content tool:
{
  "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 web scraping"

🔍 Search Results:
══════════════════════════════════════════════════

1. Python Web Scraping Tutorial
   URL: https://realpython.com/python-web-scraping-practical-introduction/
   Complete guide to web scraping with Python using requests and Beautiful Soup...

2. Web Scraping with Python - BeautifulSoup and requests
   URL: https://www.dataquest.io/blog/web-scraping-python-tutorial/
   Learn how to scrape websites with Python, Beautiful Soup, and requests...

══════════════════════════════════════════════════
Commands: [1-10] select result | b) back | q) quit | open ) open in browser

> 1

📥 Extracting content from: Python Web Scraping Tutorial

📄 Content:
══════════════════════════════════════════════════

**Python Web Scraping Tutorial**
Source: https://realpython.com/python-web-scraping-practical-introduction/
Extracted: 2024-01-15T10:30:00.000Z

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

# Python Web Scraping: A Practical Introduction

Web scraping is the process of collecting and parsing raw data from the web...

## What Is Web Scraping?

Web scraping is a technique to automatically access and extract large amounts...

══════════════════════════════════════════════════
Commands: b) back to results | /) search in text | q) quit | open) open in browser

> /beautiful soup

🔍 Found 3 matches for "beautiful soup":
──────────────────────────────────────────────────
Line 15: Beautiful Soup is a Python library for parsing HTML and XML documents.
Line 42: from bs4 import BeautifulSoup
Line 67: soup = BeautifulSoup(html_content, 'html.parser')

直接URL模式

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

📄 Content:
══════════════════════════════════════════════════

**The Python Tutorial**
Source: https://docs.python.org/3/tutorial/
Extracted: 2024-01-15T10:35:00.000Z

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

# The Python Tutorial

Python is an easy to learn, powerful programming language...

## An Informal Introduction to Python

In the following examples, input and output are distinguished...

详细模式

$ llmresearcher -v "nodejs tutorial"

[VERBOSE] Searching: https://duckduckgo.com/html/?q=nodejs%20tutorial&kl=us-en
[VERBOSE] Response: 200 in 847ms
[VERBOSE] Parsed 10 results
[VERBOSE] Launching browser...
[VERBOSE] Blocking resource: https://example.com/style.css
[VERBOSE] Blocking resource: 
[VERBOSE] Navigating to page...
[VERBOSE] Page loaded in 1243ms
[VERBOSE] Processing content with Readability...
[VERBOSE] Readability extraction successful
[VERBOSE] Closing browser...

测试

运行测试

# Run tests in watch mode
pnpm test

# Run tests once (CI mode)
pnpm test:run

# Run tests with coverage
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/                      # Built JavaScript files (generated)
│   ├── bin/
│   │   └── llmresearcher.js   # CLI entry point (executable)
│   └── *.js                   # Compiled TypeScript modules
├── src/                       # TypeScript source files
│   ├── bin.ts                 # CLI entry point
│   ├── index.ts               # Main LLMResearcher class
│   ├── mcp-server.ts          # MCP server implementation
│   ├── search.ts              # DuckDuckGo search implementation
│   ├── github-code-search.ts  # GitHub Code Search implementation
│   ├── extractor.ts           # Content extraction with Playwright
│   ├── cli.ts                 # Interactive CLI interface
│   ├── config.ts              # Configuration management
│   └── types.ts               # TypeScript type definitions
├── test/                      # Test files (vitest)
│   ├── search.test.ts         # Search functionality tests
│   ├── extractor.test.ts      # Content extraction tests
│   ├── config.test.ts         # Configuration tests
│   ├── mcp-locale.test.ts     # MCP locale functionality tests
│   ├── mcp-content-extractor.test.ts # MCP content extractor tests
│   └── integration.test.ts    # End-to-end integration tests
├── tsconfig.json              # TypeScript configuration
├── tsup.config.ts             # Build configuration
├── vitest.config.ts           # Test configuration
├── package.json
└── README.md

依赖项

运行时依赖关系

• @模型上下文协议/sdk：模型上下文协议服务器实现
• @mozilla/可读性：从HTML中提取内容
• 再见：搜索结果的HTML解析
• 指挥官：CLI参数解析
• DOM净化：HTML净化
• dotenv：环境变量加载
• jsdom：用于服务器端处理的DOM操作
• 剧作家：JS渲染的浏览器自动化
• 拒绝：HTML到Markdown的转换

发展依赖性

• 打字稿：TypeScript编译器
• tsup：快速TypeScript打包器
• 速度：快速单元测试框架
• @类型/\*：TypeScript类型定义

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

路线图

计划的功能

• 增强型MCP工具：用于文档、API等的其他专门搜索工具。
• 缓存层：基于SQLite的URL→ 带24小时TTL的Markdown缓存
• 搜索引擎摘要：支持Brave搜索、Bing和其他引擎
• 内容概述：可选的人工智能内容摘要
• 导出格式：JSON、纯文本和其他输出格式
• 批处理：处理来自文件输入的多个URL
• SSE 运输：支持服务器发送事件MCP传输

性能改进

• 并行处理：多个结果的并发内容提取
• 智能缓存：基于内容新鲜度的智能缓存失效
• 内存优化：大型文档的流式内容处理