ISIS MCP

ISIS MCP

一个开源的MCP（模型上下文协议）服务器，用于具有RAG功能的本地网络抓取。为Apify RAG Web浏览器提供免费、无API密钥的替代方案。

特性

• RAG工具：具有内容提取功能的智能网络搜索（多提供商回退（DuckDuckGo→ SearXNG→ ScraperAPI）+Mozilla可读性+Markdown转换）
• 报废工具：使用可选的CSS选择器从特定URL提取内容
• 屏幕截图工具：捕获网页的视觉快照
• SQLite缓存：持久缓存以避免冗余请求
• 并行处理：高效处理多个页面提取
• 不需要API密钥：自给自足、注重隐私的方法

安装

步骤1：全局安装

npm install -g isis-mcp

第二步：使用Claude Code注册

macOS/Linux

claude mcp add --transport stdio isis-mcp -- npx -y isis-mcp

视窗

claude mcp add --transport stdio isis-mcp -- cmd /c npx -y isis-mcp

这将在用户范围内注册MCP（适用于所有项目）。

重要提示： 安装后重新启动Claude Code。

步骤3：搜索提供程序（自动配置）

ISIS-MCP使用 自动回退链 -无需配置：

选项A:Docker SearXNG（推荐）

只需安装Docker，其余部分由ISIS-MCP处理：

# Verify Docker is installed
docker --version

# That's it! On first RAG request, ISIS-MCP will:
# 1. Create container "isis-searxng"
# 2. Mount custom config (docker/searxng/settings.yml)
# 3. Start on port 8080
# 4. Wait for ready state

手动命令（macOS/Linux）：

# Check status
docker ps | grep isis-searxng

# View logs
docker logs isis-searxng

# Restart
docker restart isis-searxng

# Remove (will auto-recreate on next use)
docker rm -f isis-searxng

手动命令（Windows-PowerShell）：

# Check status
docker ps | Select-String isis-searxng

# View logs
docker logs isis-searxng

# Restart
docker restart isis-searxng

# Remove (will auto-recreate on next use)
docker rm -f isis-searxng

Windows Docker桌面说明：

• 确保在自动启动的首选项中启用了“登录时启动Docker桌面”
• 建议使用WSL 2后端而不是Hyper-V，以获得更好的性能
• 如果Docker需要时间启动，您可能会在第一个RAG请求上看到超时错误——只需在Docker准备就绪后重试

选项B：ScraperAPI（可选-付费回退）

1. 在以下位置创建帐户 刮刀API
2. 设置环境变量：

macOS/Linux（Bash/Zsh）：

export SCRAPER_API_KEY="your-key-here"

使其永久化：

echo 'export SCRAPER_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

Windows（CMD）：

set SCRAPER_API_KEY=your-key-here

Windows（PowerShell）：

$env:SCRAPER_API_KEY="your-key-here"

对于永久Windows配置，请使用“系统属性”→ 环境变量或运行：

setx SCRAPER_API_KEY "your-key-here"

替代方案：通过克劳德代码CLI（传统）

macOS/Linux

如果您更喜欢基于npx的安装：

claude mcp add isis-mcp -- npx -y github:alucardeht/isis-mcp

对于用户级全局安装：

claude mcp add -s user isis-mcp -- npx -y github:alucardeht/isis-mcp

视窗

claude mcp add isis-mcp -- cmd /c npx -y github:alucardeht/isis-mcp

对于用户级全局安装：

claude mcp add -s user isis-mcp -- cmd /c npx -y github:alucardeht/isis-mcp

手动配置

macOS/Linux

将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "isis-mcp": {
      "command": "npx",
      "args": ["-y", "github:alucardeht/isis-mcp"]
    }
  }
}

视窗

将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "isis-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "github:alucardeht/isis-mcp"]
    }
  }
}

安装故障排除

“所有搜索提供程序都失败”

原因： 没有配置或可用的提供程序。

解决方案：

1. 配置SearXNG本地（选项A）或ScraperAPI（选项B）
2. 验证服务是否正在运行：

- macOS/Linux： curl http://localhost:8080/search?q=test&format=json - Windows：使用Postman、curl（如果已安装）或PowerShell：

     Invoke-WebRequest -Uri "http://localhost:8080/search?q=test&format=json"

1. 如果使用ScraperAPI，请确认env var：

- macOS/Linux： echo $SCRAPER_API_KEY - Windows CMD: echo %SCRAPER_API_KEY% - Windows PowerShell： $env:SCRAPER_API_KEY

性能缓慢

全球与npx比较：

如果仍然很慢：

• SearXNG是本地运营的吗？
• 是否配置了ScraperAPI密钥？
• 公共实例是否超载？

克劳德代码未检测到MCP

1. 验证安装： npm list -g isis-mcp
2. 完全重新启动Claude代码
3. 检查MCP状态： claude mcp list （如果可用）
4. 重新运行： claude mcp install isis-mcp -s user

可用工具

抹布（主要工具）

具有智能内容提取功能的网络搜索。其工作原理类似于Apify RAG Web浏览器：

1. 通过多提供商回退进行搜索（DuckDuckGo→ SearXNG→ 刮刀API→ 公共实例）
2. 并行从发现的页面中提取内容
3. 使用Mozilla可读性转换为Markdown
4. 返回带缓存的结构化结果

参数：

• query （必填）：搜索词
• maxResults （可选）：要检索的最大页数（1-10，默认值：5）
• outputFormat （可选）： markdown | text | html （默认值： markdown)
• useJavascript （可选）：使用Playwright渲染JavaScript（默认值： false)

例子：

Search for "nodejs best practices" and provide a summary

刮擦

从特定URL提取内容。

参数：

• url （必填）：页面URL
• selector （可选）：特定元素的CSS选择器
• javascript （可选）：在提取之前渲染JavaScript

例子：

Extract the main content from https://nodejs.org/en/learn

截图

捕获网页的屏幕截图。

参数：

• url （必填）：页面URL
• fullPage （可选）：捕获整个页面（默认值： false)
• width （可选）：视口宽度（像素）（默认值： 1920)
• height （可选）：视口高度（像素）（默认值： 1080)

例子：

Take a screenshot of https://example.com

建筑

ISIS MCP v3.0
├── Search (Multi-provider fallback chain)
├── Docker Auto-Start (SearXNG local container)
├── Extraction (Mozilla Readability + Turndown)
├── Caching (SQLite at ~/.isis-mcp-cache.db)
└── Parallel Processing

服务器采用模块化架构，每个组件都可以独立扩展：

• 搜索模块：多提供商回退链（DuckDuckGo→ SearXNG→ 刮刀API→ 公共实例）
• Docker集成：8080港SearXNG集装箱自动管理
• 提取模块：使用Mozilla Readability进行智能内容解析，并使用Turndown进行HTML到Markdown的转换
• 缓存层：基于SQLite的持久缓存，以最大限度地减少冗余请求
• 处理流水线：并行提取多个页面以提高性能

需求

所有平台

• Node.js 18+ -必填项
• 剧作家Chromium -自动安装
• 码头工人 （推荐）-适用于当地SearXNG。首次使用时自动启动。后备提供者在没有Docker的情况下工作。

平台特定的

macOS

• 适用于Mac的Docker桌面（可选，适用于SearXNG Local）

Linux

• Docker引擎（可选，适用于SearXNG Local）

视窗

• Windows版Docker桌面 （可选，适用于SearXNG Local）
• 使用Docker时：启用WSL 2后端以获得最佳兼容性
• 如果您看到Playwright浏览器错误，请运行： npx playwright install

搜索后备链

ISIS-MCP会自动按顺序尝试提供者，直到成功为止：

DuckDuckGo (Primary)
    ↓ if fails
SearXNG Local (Docker container on port 8080)
    ↓ if fails
ScraperAPI (if SCRAPER_API_KEY configured)
    ↓ if fails
Public SearXNG Instances (7 fallback servers)

特征：

• 利率限制的指数级回退
• 用户代理轮换以提高可靠性
• 自动Docker容器管理
• 优雅地降级到公共实例

令牌优化功能

RAG工具已经过渐进式令牌优化的增强，可以有效地处理大量内容。

第一阶段：内容模式

控制每个结果返回多少内容：

// Preview mode - Truncate to ~300 characters (70-80% reduction)
await rag({
  query: "react hooks",
  contentMode: "preview"
})

// Full mode - Complete content (default, backward compatible)
await rag({
  query: "react hooks",
  contentMode: "full"
})

// Summary mode - Intelligent LLM summarization (Phase 3)
await rag({
  query: "react hooks",
  contentMode: "summary"
})

优点：

• preview：快速、紧凑的结果（约6k个代币对约20k个代币）
• full：完整内容（原始行为）
• summary：通过LLM提供150-200字的智能摘要

第二阶段：延迟内容获取

使用内容句柄在预览后获取完整内容：

// Step 1: Get preview with handle
const preview = await rag({
  query: "react hooks",
  contentMode: "preview",
  maxResults: 5
})

// Each result includes contentHandle (BASE64 of URL)
const handle = preview.results[0].contentHandle

// Step 2: Fetch full content when needed
const full = await fetchFullContent({
  contentHandle: handle,
  outputFormat: "markdown"
})
// Returns: Complete content from cache (1-hour TTL)

优点：

• 延迟加载：只获取您需要的内容
• 缓存重用：无需重新抓取
• 确定性句柄：相同的URL=相同的句柄

第三阶段：渐进式总结

使用本地Ollama LLM进行智能内容摘要。

设置（可选-零配置）

1. 安装Ollama（如果尚未安装）：

macOS/Linux：

curl -fsSL https://ollama.ai/install.sh | sh
# Or download from https://ollama.ai

窗户：

• 从下载安装程序https://ollama.ai
• 运行安装程序（Ollama.exe）
• Ollama将自动启动并继续收听http://localhost:11434

1. 拉一个模型（推荐）：

ollama pull llama3.2:1b  # Fast, good quality (1.3GB)
# or
ollama pull mistral:7b   # Premium quality, slower (4GB)

1. 启动Ollama（如果未运行）：

macOS/Linux：

ollama serve

窗户：

• Ollama在安装后作为后台服务运行
• 要验证它是否正在运行，请打开http://localhost:11434/api/tags在浏览器中
• 如果需要，请从Windows服务重新启动（在“开始”菜单中搜索“服务”）

用法

基本概述（自动检测）：

const result = await rag({
  query: "react hooks best practices",
  contentMode: "summary"
})
// Auto-detects Ollama, uses llama3.2:1b by default
// Falls back to truncation if Ollama unavailable

自定义型号：

const result = await rag({
  query: "python async patterns",
  contentMode: "summary",
  summaryModel: "mistral:7b"
})

通过环境变量进行配置：

export OLLAMA_ENDPOINT=http://localhost:11434  # Default
export OLLAMA_MODEL=llama3.2:1b               # Default
export OLLAMA_TIMEOUT=30000                    # Default 30s

回退行为

• ✅ Ollama不可用→ 自动回退到截断
• ✅ 模型不存在→ 尝试默认设置，然后截断
• ✅ 超时→ 回退到截断
• ✅ 无需配置-开箱即用

推荐型号

性能比较

\*与Ollama。回落到 preview 性能（如果不可用）。

第四阶段：资源管理

控制浏览器池和内存使用以防止系统过载：

环境变量

根据您的系统配置资源限制：

export MAX_BROWSERS=3          # Max concurrent browsers (default: 3)
export MAX_IDLE_TIME=30000     # Browser idle timeout in ms (default: 30s)
export MODEL_IDLE_TTL=300000   # Unload model after idle time in ms (default: 5min)

使配置永久化

macOS/Linux：

echo 'export MAX_BROWSERS=3' >> ~/.zshrc
echo 'export MAX_IDLE_TIME=30000' >> ~/.zshrc
echo 'export MODEL_IDLE_TTL=300000' >> ~/.zshrc
source ~/.zshrc

Windows（CMD）：

setx MAX_BROWSERS 3
setx MAX_IDLE_TIME 30000
setx MODEL_IDLE_TTL 300000

Windows（PowerShell）：

[Environment]::SetEnvironmentVariable("MAX_BROWSERS", "3", "User")
[Environment]::SetEnvironmentVariable("MAX_IDLE_TIME", "30000", "User")
[Environment]::SetEnvironmentVariable("MODEL_IDLE_TTL", "300000", "User")

系统推荐值

运作原理

• 浏览器池： 重用浏览器实例，而不是按请求创建/销毁
• 空闲清理： 之后自动关闭空闲浏览器 MAX_IDLE_TIME
• LLM卸载： 卸载模型后释放~1-2GB RAM MODEL_IDLE_TTL 不活动

例子

研究工作流程：

// 1. Quick scan with previews
const preview = await rag({
  query: "Next.js 14 features",
  contentMode: "preview",
  maxResults: 10
})

// 2. Get intelligent summary of top result
const summary = await rag({
  query: "Next.js 14 features",
  contentMode: "summary",
  maxResults: 1
})

// 3. Fetch full content for deep dive
const full = await fetchFullContent({
  contentHandle: preview.results[0].contentHandle
})

故障排除：

Q： 总结似乎很慢？

# Use faster model
ollama pull qwen2.5:0.5b
export OLLAMA_MODEL=qwen2.5:0.5b

Q： 得到截断的结果而不是摘要？

# Check if Ollama is running
curl http://localhost:11434/api/tags

# If not running, start it
ollama serve

本地开发

克隆和设置

macOS/Linux：

git clone https://github.com/alucardeht/isis-mcp.git
cd isis-mcp
npm install
npx playwright install chromium
npm run build

Windows（PowerShell）：

git clone https://github.com/alucardeht/isis-mcp.git
cd isis-mcp
npm install
npx playwright install chromium
npm run build

测试

macOS/Linux：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js

Windows（PowerShell）：

@'
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
'@ | node build/index.js

Windows（CMD）：

echo {"jsonrpc":"2.0","id":1,"method":"tools/list"} | node build/index.js

构建输出

编译后的代码输出到 build/ 目录。一定要跑 npm run build 在对源代码进行更改后。

许可证

根据Apache许可证2.0版授权。有关完整详细信息，请参阅LICENSE文件。

您可以在以下网址获得许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”分发，不附带任何明示或暗示的保证或条件。有关许可证下管理权限和限制的具体语言，请参阅许可证。