使用说明

Sibyl MCP服务器

通过模型上下文协议（MCP）实现人工智能驱动的PDF处理和笔记管理

Sibyl提供两个专用的MCP服务器，使LLM主机（Claude Desktop、VS Code等）能够智能处理PDF并管理带有OCR、智能合并和基于模板的创建等高级功能的标记笔记。

⚖️ 重要提示：许可通知

在开始之前： Sibyl使用MuPDF（通过go-fitz）进行PDF处理，这是根据AGPL v3许可的。这意味着：

✅ 开源项目：在AGPL v3下免费使用
⚠️ 商业/专有用途：需要Artifex Software的商业许可
📋 网络部署：必须在AGPL v3下向用户提供源代码

请参阅下面的详细许可信息在投入生产之前。

🚀 快速开始

先决条件

转到1.21+ - 安装Go
谷歌云帐户 -对于Google Drive API访问
Mathpix帐户 -用于OCR处理(注册)
MCP兼容主机 -Claude Desktop、带有MCP扩展的VS Code等。

1.克隆和构建

git clone https://github.com/your-username/sibyl.git
cd sibyl
make all

这将创建：

./bin/pdf-server -PDF处理MCP服务器
./bin/notes-server -票据管理MCP服务器

2.设置凭据

Google Drive API设置

首选谷歌云控制台
创建新项目或选择现有项目
启用Google Drive API
创建服务帐户凭据
下载JSON凭据文件
使用服务帐户电子邮件共享您的Google Drive文件夹

Mathpix OCR设置

注册地址： Mathpix
在仪表板中创建新应用程序
记下你的应用ID和应用密钥

3.配置环境

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

# Google Drive Configuration
GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/google-credentials.json
GCP_FOLDER_ID=your-google-drive-folder-id

# Mathpix OCR Configuration  
MATHPIX_APP_ID=your-mathpix-app-id
MATHPIX_APP_KEY=your-mathpix-app-key

4.配置您的MCP主机

将服务器添加到MCP主机配置中：

克劳德桌面(~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上：

{
  "mcpServers": {
    "pdf-server": {
      "command": "/full/path/to/sibyl/bin/pdf-server",
      "args": [
        "--credentials", "/path/to/google-credentials.json",
        "--folder-id", "your-google-drive-folder-id",
        "--mathpix-app-id", "your-mathpix-app-id",
        "--mathpix-app-key", "your-mathpix-app-key",
        "--ocr-languages", "en,fr,de",
        "--log-level", "INFO"
      ]
    },
    "notes-server": {
      "command": "/full/path/to/sibyl/bin/notes-server",
      "args": [
        "--notesFolder", "/path/to/your/notes",
        "--logLevel", "INFO",
        "--logFile", "notes-server.log"
      ]
    }
  }
}

5.测试设置

重新启动MCP主机（Claude Desktop、VS Code等）
试着问： “我有哪些可用的PDF文档？”
试着问： “在项目文件夹中显示我的笔记”

📖 核心概念

PDF服务器功能

PDF服务器连接到您的Google云端硬盘，并提供：

🔍 文档搜索：按名称、内容或元数据查找PDF
📄 PDF到Markdown转换：使用Mathpix OCR+视觉分析进行高质量转换
🖼️ 图像处理：将PDF转换为150 DPI PNG图像以进行视觉分析
🌍 多语言OCR：通过Mathpix支持40多种语言
📊 MCP资源：对文档库的结构化访问

它是如何工作的：

PDF → PNG：使用MuPDF将PDF页面转换为高质量图像
PDF → OCR：使用Mathpix OCR提取文本（处理公式、表格、手写）
PNG+OCR→ LLM：您的LLM分析视觉和文本数据以实现最佳转换

Notes服务器功能

笔记服务器通过以下方式管理您的markdown保管库：

📝 智能读写：对markdown文件执行完整的CRUD操作
🔄 智能合并：5种合并策略（追加、前置、日期分段、主题合并、替换）
👀 合并预览：在应用更改之前，请准确查看更改内容
📋 模板系统：每日笔记、会议、研究、项目的预构建模板
🔍 内容搜索：在整个保管库中进行全文搜索
📊 MCP资源：对您的笔记集进行结构化探索

🛠️ 可用工具

PDF服务器工具

工具	说明	参数
`search_pdfs`	在谷歌云端硬盘中搜索PDF文件	`query` （字符串）， `max_files` （编号）
`convert_pdf_to_markdown`	使用OCR+视觉分析将PDF转换为Markdown	`file_id` （字符串）

Notes服务器工具

工具	说明	参数
`read_note`	阅读笔记内容	`path` （字符串）
`write_note`	创建或覆盖笔记	`path` （字符串）， `content` （字符串）
`merge_note`	将内容与现有注释合并	`path`, `content`, `strategy`, `title?`
`preview_merge`	预览合并操作	`path`, `content`, `strategy?`
`list_notes`	在目录中列出注释	`path?`, `recursive?` （布尔值）
`search_notes`	搜索笔记内容	`query` （字符串）， `path?`
`get_note_templates`	获取可用模板	`template_type?` （字符串）
`create_note_from_template`	从模板创建注释	`path`, `template_type`, `variables?`

合并策略

append -将内容添加到文件末尾
prepend -在文件开头添加内容
date_section -添加带有时间戳的新日期部分
topic_merge -基于内容主题的智能合并
replace -替换整个文件内容

注释模板

daily -每日记录重点领域、任务和反思
meeting -会议记录，包括议程、与会者和行动项目
research -带有引文、分析和结论的研究笔记
project -带有目标、里程碑和进度的项目规划模板

🎯 使用示例

示例1:PDF研究工作流程

你: “我的Drive中有一篇关于机器学习的研究论文。你能把它转换成笔记并添加到我的研究收藏中吗？”

助手我会帮你找到并转换那篇研究论文。让我先搜索你的谷歌云端硬盘。

→ Calls search_pdfs(query: "machine learning")

我找到了3个关于机器学习的PDF文件：

“深度学习基础.pdf”（2.1MB，昨天修改）
“ML算法调查.pdf”（896KB，上周修改）
“神经网络简介.pdf”（1.5MB，上个月修改）

你想让我皈依哪一种？

你: “第一个”

助手：我将使用我们的OCR和视觉分析过程将“深度学习基础.pdf”转换为Markdown。

→ Calls convert_pdf_to_markdown(file_id: "1BxYz...")

太好了！PDF已使用Mathpix OCR处理并转换为高质量图像。我已经提取了文本，可以看到包括方程式、图表和表格在内的视觉元素。

这是转换后的内容。..[显示转换后的降价]

您是否希望我将此保存为新的研究笔记？

你: 是的，请将其另存为“深度学习基础概述”

助手: → Calls write_note(path: "research/Deep Learning Fundamentals Summary.md", content: converted_content)

完成！我已将转换后的论文保存在您的研究文件夹中，名为“深度学习基础概述.md”。转换包括原始PDF中的所有数学公式、图表和结构化内容。

示例2：智能笔记合并

你: “我刚刚做了一些会议笔记。你能把它们和我的日常笔记合并在一起，但要保持条理吗？”

助手：我可以帮你合并会议笔记。让我预览一下，通过基于主题的合并来保持一切有序，这会是什么样子。

→ Calls preview_merge(path: "daily.md", content: meeting_notes, strategy: "topic_merge")

以下是合并的外观：

您现有的“任务”部分将与新的行动项相结合
将在新的“会议”一节下添加会议说明
不会创建重复内容

我应该继续进行合并吗？

你: “太好了，去吧”

助手: → Calls merge_note(path: "daily.md", content: meeting_notes, strategy: "topic_merge")

完成！您的会议笔记已智能地合并到您的日常笔记中，组织得当，没有重复。

示例3：基于模板的笔记创建

你: “为明天的冲刺计划会议创建会议记录”

助手：我将使用我们的会议模板创建会议笔记。

→ Calls create_note_from_template(path: "meetings/sprint-planning-2025-08-10.md", template_type: "meeting", variables: {"TITLE": "Sprint Planning", "DATE": "2025-08-10", "ATTENDEES": "TBD"})

我创建了“sprint-planning-2025-08-10.md”，其中包含一个结构化的会议模板，包括：

议程部分
与会者名单（您可以填写）
讨论要点
行动项目跟踪
下一步行动

该说明已准备就绪，您可以在会议前添加具体的议程项目。

📊 MCP资源

这两台服务器都提供MCP资源，可以在不知道特定文件路径的情况下对您的内容进行智能探索。

PDF服务器资源

pdf://documents/ -包含元数据的PDF库完整目录
示例：列出所有PDF文件，包括文件大小、修改日期和直接链接

Notes服务器资源

notes://files/ -带有预览和标签的完整笔记集
notes://templates/ -带有描述的可用注释模板
notes://collections/ -按文件夹和标签组织的笔记

资源优势：

🔍 发现：LLM可以在不知道文件路径的情况下进行探索
⚡ 效率：批量元数据检索与单个查询
🧠 上下文：丰富的元数据有助于LLM做出更明智的决策
🗺️ 导航：内容层次结构的结构化浏览

⚙️ 配置选项

PDF服务器参数

./bin/pdf-server --help

参数	必需	描述	环境变量
`--credentials`	是	谷歌云凭据JSON路径	`GOOGLE_APPLICATION_CREDENTIALS`
`--folder-id`	是	要搜索的Google Drive文件夹ID	`GCP_FOLDER_ID`
`--mathpix-app-id`	是	Mathpix API应用程序ID	`MATHPIX_APP_ID`
`--mathpix-app-key`	是	Mathpix API应用程序密钥	`MATHPIX_APP_KEY`
`--ocr-languages`	否	逗号分隔的语言代码（默认值：“en”）	-
`--log-level`	否	日志级别：调试、信息、警告、错误（默认值：信息）	-
`--log-file`	否	日志文件路径（默认：stderr）	-

Notes服务器参数

./bin/notes-server --help

参数	必填	描述
`--notesFolder`	是	笔记目录的路径
`--logLevel`	否	日志级别：调试、信息、警告、错误（默认值：信息）
`--logFile`	否	日志文件路径（默认：stderr）

🧪 开发与测试

运行测试

# Run all tests
go test ./...

# Run tests with coverage
go test -race -coverprofile=coverage.out -covermode=atomic ./pkg/...
go tool cover -html=coverage.out -o coverage.html

# Run specific package tests
go test ./pkg/pdfmcp
go test ./pkg/notes

# Run integration tests
go test ./tests/integration/...

代码质量

# Static analysis
go vet ./...
staticcheck ./...

# Security scanning  
gosec ./...

# Comprehensive linting
golangci-lint run --timeout=5m

项目结构

sibyl/
├── cmd/                    # Main applications
│   ├── pdfserver/          # PDF MCP server entry point
│   └── noteserver/         # Notes MCP server entry point
├── pkg/                    # Reusable packages
│   ├── pdfmcp/             # PDF server implementation 
│   ├── notes/              # Notes server implementation
│   ├── dto/                # Data transfer objects
│   └── utils/              # Shared utilities
├── tests/                  # Testing infrastructure
│   ├── integration/        # End-to-end tests
│   └── testutils/          # Test helpers
├── examples/               # Usage examples and configs
└── bin/                    # Built binaries

🔧 故障排除

常见问题

PDF服务器无法启动：

✅ 检查Google Cloud凭据文件是否存在且有效
✅ 验证Google Drive API是否已在GCP项目中启用
✅ 确保服务帐户可以访问您的驱动器文件夹
✅ 确认Mathpix凭据正确

Notes服务器找不到笔记：

✅ 验证笔记文件夹路径是否存在且可读
✅ 检查笔记是否为Markdown格式（.md扩展名）
✅ 确保文件权限正确

MCP主机无法连接：

✅ 在MCP配置中使用绝对路径
✅ 配置更改后重新启动MCP主机
✅ 检查服务器日志中的启动错误

日志文件

启用调试日志以进行故障排除：

# PDF Server
./bin/pdf-server --log-level DEBUG --log-file pdf-server.log [other args...]

# Notes Server  
./bin/notes-server --logLevel DEBUG --logFile notes-server.log [other args...]

📚 高级用法

自定义OCR语言

Mathpix支持40多种语言。指定多种语言：

--ocr-languages "en,fr,de,es,zh,ja,ko"

批处理

高效处理多个PDF：

使用 pdf://documents/ 获取完整文件列表的资源
按日期、大小或名称模式筛选
处理每一个 convert_pdf_to_markdown
使用 merge_note 随着 topic_merge 智能整合策略

自定义模板

通过检查内置模板来创建自己的笔记模板：

# Get template structure
curl -X POST http://localhost/mcp \
  -d '{"method": "tools/call", "params": {"name": "get_note_templates"}}'

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
进行更改并添加测试
确保所有测试通过： make test
提交您的更改： git commit -m 'Add amazing feature'
推到分支： git push origin feature/amazing-feature
打开拉取请求

代码的风格

遵循围棋惯例并使用 gofmt
添加新功能的测试
更新面向用户的更改文档
使用结构化日志记录 slog

⚖️ 许可和法律声明

主要许可证

该项目根据 Apache许可证2.0 -看看许可证文件以获取详细信息。

🚨 重要提示：第三方许可依赖关系

Sibyl使用MuPDF进行PDF处理，这有特定的许可要求：

多PDF许可（AGPL v3）

图书馆: github.com/gen2brain/go-fitz （MuPDF的Go包装器）
基础图书馆：MuPDF（根据AGPL v3许可）
许可方：Artifex软件，股份有限公司。

AGPL v3要求

⚠️ 如果您以以下任何一种方式使用Sibyl，您的整个应用程序必须在AGPL v3下获得许可：

网络服务 -将Sibyl作为web服务、API或SaaS运行
修改分发 -分发Sibyl的修改版本
整合 -将Sibyl整合到其他软件中
内部使用 -通过网络在组织内使用Sibyl

AGPL v3义务

当AGPL适用时，您必须：

✅ 在AGPL v3或兼容版本下许可您的整个应用程序
✅ 为所有用户提供完整的源代码
✅ 包括许可声明和版权信息
✅ 确保用户可以从源代码重建应用程序

商业许可替代方案

如果您无法遵守AGPL v3要求：

🏢 联系Artifex Software获取商业MuPDF许可证：

网站：https://mupdf.com/licensing/
取消AGPL义务
支持专有/商业部署
闭源应用程序需要

其他依赖关系（许可）

所有其他依赖项都使用许可证：

github.com/mark3labs/mcp-go -MIT许可证
github.com/joho/godotenv -MIT许可证
google.golang.org/api -Apache许可证2.0
Go标准库-BSD风格许可证

许可证兼容性摘要

用例	需要许可证	需要商业许可证
开源项目（AGPL v3）	✅ 免费	❌ 没有
公司内部工具	⚠️ AGPL v3	❌ 否*
SaaS/Web服务	⚠️ AGPL v3	❌ 否*
专有软件	❌ 不可能	✅ 是的
商业分销	❌ 不可能	✅ 是的

*只要您符合AGPL v3源代码分发要求

用户建议

开源项目：在AGPL v3下自由使用Sibyl
商业项目：评估AGPL v3合规性是否可行
专利产品：联系Artifex获取商业许可
咨询：考虑对复杂的许可情况进行法律审查

有关许可合规性的问题，请咨询合格的法律专业人士。

🙏 致谢

MCP Go SDK -MCP服务器实现
Mathpix -OCR处理服务
MuPDF -PDF处理和渲染
Google Drive API -文件存储和访问