🦈 DocShark
DocShark 是一个功能强大的MCP（模型上下文协议）服务器，旨在抓取、索引和搜索任何文档网站。它使用FTS5（全文搜索）和BM25排名从公共文档页面创建了一个本地的、高度可搜索的知识库，使AI助手能够轻松查询最新文档。
______________________________________________________________________
🚀 特性
- 自动爬行：通过以下方式发现页面
sitemap.xml并回退到BFS链路爬行。 - 智能提取：使用Readability和Turndown提取主要内容并将其转换为干净的Markdown，过滤掉导航栏和侧边栏。
- 语义分块：根据标题拆分内容，保留上下文标题以更好地理解AI。
- 高性能搜索：内置SQLite+FTS5索引和BM25排名，可获得准确和闪电般快速的搜索结果。
- JS渲染网站支持：分层获取策略自动检测React/Vue SPA（空壳）并升级到
puppeteer-core如果你已经安装了它（零配置，自动回退）。 - 礼貌爬行：尊重
robots.txt并实施速率限制以防止文档服务器过载。 - 标准MCP工具：通过标准与桌面Claude、VS Code、Cursor和任何其他MCP兼容客户端完美连接
stdio或http/sse运输。
📦 我们做了什么（第一阶段）
第一阶段：核心引擎 已全面实施和测试。
- ✅ 具有FTS5虚拟表和自动同步触发器的自定义SQLite数据库。
- ✅ Web抓取引擎支持标准
fetch()和puppeteer-core. - ✅ Markdown处理器利用可读性+调低。
- ✅ 基于标题的语义分块器（每个分块500-1200个标记）。
- ✅ 异步作业管理器和队列系统。
- ✅ 完成HTTP API（REST端点+SSE事件流）。
- ✅ 4个MCP工具的无缝集成：
manage_library,search_docs,list_libraries，以及get_doc_page. - ✅ 强大的CLI界面(
start,add,rename,search,list).
🏗️ 我们正在做什么
我们正在积极完善核心引擎和外部MCP客户端（如VS Code Agents和Claude Desktop）之间的集成。
🔮 我们计划做什么（第2阶段及以后）
- 网络仪表盘：直观的SvelteKit仪表板，用于管理同步库、实时查看爬网进度（通过SSE）和手动测试搜索。
- 增量爬行：更聪明
refresh比较的工作ETag和Last-Modified标题仅重新抓取更新的页面。 - 矢量搜索（RAG）：将语义相似性搜索的轻量级向量嵌入与现有的FTS5关键字搜索集成在一起。
- 高级报废设置：支持自定义CSS选择器，以准确定义内容在非标准文档网站中的位置。
______________________________________________________________________
🛠️ 用法
快速入门（来自npm）
您可以直接运行DocShark，而无需使用全局安装 bunx:
# Add a documentation library to the index
bunx docshark add https://valibot.dev/guides/ --depth 2
# Search your indexed docs
bunx docshark search "schema validation"安装
要将DocShark作为CLI工具全局安装，请执行以下操作：
DocShark旨在与Bun一起安装和运行。
# Global Bun installation
bun add -g docshark安装后，您可以使用 docshark 命令：
docshark list
# Update the global Bun installation when a new release is published
docshark update
# Script-friendly update check
docshark update --check --quiet交互式CLI运行也会让您知道何时有新版本可用。MCP有意跳过更新通知 stdio 模式，因此它们永远不会干扰协议输出。
对于脚本， docshark update --check 出口 0 当电流， 10 当有新版本可用时，以及 1 当版本检查无法完成时。
🔌 MCP集成
VS代码（GitHub副本/MCP扩展）
将DocShark添加到您的 .vscode/settings.json 或全局MCP配置：
{
"mcpServers": {
"docshark": {
"command": "bunx",
"args": ["-y", "docshark", "start", "--stdio"]
}
}
}光标
- 打开 光标设置 > 模型 > 主控程序.
- 点击 +添加新的MCP服务器.
- 姓名：
docshark - 类型：
command - 命令：
bunx -y docshark start --stdio
克劳德桌面版
编辑您的Claude Desktop配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"docshark": {
"command": "bunx",
"args": ["-y", "docshark", "start", "--stdio"]
}
}
}______________________________________________________________________
🛠️ 发展
本地设置
确保你有 包子 安装。
# Clone the repository
git clone https://github.com/Michael-Obele/docshark.git
cd docshark
# Install dependencies
bun install
# (Optional) Enable auto-detection & scraping of Javascript React/Vue single-page apps
bun add puppeteer-core
# Start the DocShark MCP server in HTTP mode for local testing
bun run src/cli.ts start --port 6380本地CLI调试
# Run CLI directly while developing
bun run src/cli.ts list🔄 版本控制和变更日志
此项目使用 Google发布请 自动化版本控制和变更日志生成。
- 语义化版本：我们的版本会自动碰撞（例如。
0.0.1->0.0.2或0.1.0)基于标准常规承诺(feat:,fix:,chore:等等）。 - 自动化：PR在以下时间自动创建
master当合并标准提交时，生成一个标准CHANGELOG.md.
📜 许可证
该项目是开源的，可在 MIT许可证.
______________________________________________________________________
_旨在为AI代理提供最新知识。_