# pdf-knowledge-mcp

`pdf-knowledge-mcp` 是一个面向 PDF 开发经验沉淀的本地 RAG MCP Server。它可以导入 PDF 解析、生成、渲染、文本提取、表格识别、版式分析、字体处理、OCR、PDF/A、签名、加密、性能优化等经验文档，并通过 MCP 工具提供检索和问答能力。

当前实现不依赖远程模型或外部向量数据库。文档会被切分为 chunk，使用本地 TF-IDF 向量和余弦相似度检索，并把索引持久化为 JSON 文件。后续可以在 `src/knowledge-store.ts` 中替换或扩展 embedding/provider。

## 安装与构建

```powershell
cd C:\src\pdf-knowledge-mcp
npm install
npm run build
```

## 启动

```powershell
npm start
```

该进程通过 stdio 提供 MCP 服务。

默认知识库索引路径为项目内的 `data/pdf-knowledge-index.json`。如需指定其他位置：

```powershell
$env:PDF_KNOWLEDGE_STORE_PATH = "C:\src\pdf-knowledge-mcp\data\pdf-knowledge-index.json"
npm start
```

## MCP 配置

推荐先链接成本地命令：

```powershell
cd C:\src\pdf-knowledge-mcp
npm link
```

然后添加到 Codex：

```powershell
codex mcp add pdf-knowledge -- pdf-knowledge-mcp
```

通用 MCP 客户端配置示例：

```json
{
  "mcpServers": {
    "pdf-knowledge": {
      "command": "node",
      "args": ["C:/src/pdf-knowledge-mcp/dist/index.js"],
      "env": {
        "PDF_KNOWLEDGE_STORE_PATH": "C:/src/pdf-knowledge-mcp/data/pdf-knowledge-index.json"
      }
    }
  }
}
```

## 工具

### `ingest_document`

导入 PDF 开发经验文档。支持直接传入 `content`，也支持传入 UTF-8 文本、Markdown、JSON、HTML 文件路径。

```json
{
  "title": "PDF text extraction notes",
  "source": "notes/text-extraction.md",
  "tags": ["parsing", "text", "font"],
  "content": "When extracting text from PDF content streams, ToUnicode CMaps are essential...",
  "chunkSize": 1800,
  "chunkOverlap": 200,
  "replaceExisting": true
}
```

也可以从文件导入：

```json
{
  "filePath": "C:/docs/pdf-rendering-notes.md",
  "tags": ["rendering", "performance"]
}
```

### `search_knowledge`

基于本地向量索引检索相关经验片段。

```json
{
  "query": "ToUnicode font extraction",
  "limit": 5,
  "tags": ["text"]
}
```

返回内容包括分数、文档标题、来源、标签、chunk id、命中词和 excerpt。

### `ask_pdf_expert`

先检索知识库，再基于检索结果生成带来源的 PDF 开发回答。

```json
{
  "question": "How should I handle fonts when extracting PDF text?",
  "limit": 5,
  "maxContextChars": 8000
}
```

如果没有匹配内容，工具会明确提示需要先导入相关经验文档。

## 验证

```powershell
npm test
```

Smoke test 会验证：

- 文档导入、分块和索引持久化；
- 本地向量检索和标签过滤；
- `ask_pdf_expert` 返回带来源的 RAG 回答；
- MCP Server 可以通过 stdio 响应 `initialize` 请求。

## 说明

这个服务适合作为 PDF 开发经验知识库的基础版本：它先保证本地、可追溯、可运行。未来可以扩展的方向包括真实 embedding 模型、SQLite/向量数据库、PDF/Docx 文档解析器、自动目录同步、以及与 `pdf-debug-mcp`、`pdf-specification-mcp` 的联合查询。