# MCP 工具参考手册

本文档提供 Paperlib MCP 所有工具的完整 API 参考。

## 工具目录

| 类别 | 工具数 | 说明 |
|------|--------|------|
| [健康检查](#1-健康检查) | 2 | 系统状态检查 |
| [PDF 导入](#2-pdf-导入) | 2 | 文档导入与状态 |
| [搜索检索](#3-搜索检索) | 4 | 混合/向量/全文搜索 |
| [数据获取](#4-数据获取) | 8 | 文档和 chunk CRUD |
| [综述写作](#5-综述写作) | 5 | 证据包与综述生成 |
| [图谱抽取](#6-图谱抽取) | 4 | 知识图谱抽取 |
| [实体规范化](#7-实体规范化) | 3 | 实体合并与锁定 |
| [社区构建](#8-社区构建) | 2 | Leiden 聚类 |
| [摘要导出](#9-摘要导出) | 3 | 社区摘要与矩阵 |
| [图谱维护](#10-图谱维护) | 3 | 状态与清理 |
| [关系规范化](#11-关系规范化) | 2 | 关系合并 |
| [Claim 分组](#12-claim-分组) | 2 | Claim 聚类 |
| [v1.2 增强](#13-v12-增强工具) | 5 | 词表与特征分配 |
| [Review 工具](#14-review-工具) | 5 | 大纲与章节 |

---

## 1. 健康检查

### `health_check`

验证数据库和存储连接状态。

**参数**: 无

**返回**:
```json
{
  "ok": true,
  "db": {
    "connected": true,
    "extensions": ["vector"],
    "vector_enabled": true
  },
  "s3": {
    "accessible": true,
    "bucket": "papers",
    "endpoint": "http://localhost:9000"
  }
}
```

### `graph_health_check`

检查 GraphRAG 层健康状态。

**参数**:
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `include_counts` | bool | `true` | 是否包含行数统计 |

**返回**:
```json
{
  "ok": true,
  "db_ok": true,
  "tables_ok": true,
  "indexes_ok": true,
  "counts": {
    "entities": 1234,
    "mentions": 5678,
    "relations": 890,
    "claims": 456,
    "communities": 12
  }
}
```

---

## 2. PDF 导入

### `import_pdf`

导入 PDF 文献到知识库。

**参数**:
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `file_path` | str | ✅ | - | PDF 文件路径 |
| `title` | str | ❌ | - | 论文标题 |
| `authors` | str | ❌ | - | 作者 |
| `year` | int | ❌ | - | 年份 |
| `force` | bool | ❌ | `false` | 强制重新导入 |

**返回**:
```json
{
  "success": true,
  "doc_id": "abc123...",
  "job_id": 42,
  "pdf_key": "papers/abc123.pdf",
  "n_pages": 25,
  "n_chunks": 25,
  "embedded_chunks": 25,
  "empty_pages": 0,
  "skipped": false,
  "message": "Successfully imported"
}
```

### `ingest_status`

查看导入状态。

**参数**:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `doc_id` | str | ❌ | 文档 ID |
| `job_id` | int | ❌ | 作业 ID |

---

## 3. 搜索检索

### `search_hybrid`

混合搜索（推荐）。

**参数**:
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | str | - | 搜索查询 |
| `k` | int | `10` | 返回数量 |
| `alpha` | float | `0.6` | 向量权重 (0-1) |
| `per_doc_limit` | int | `3` | 每文档最大 chunk 数 |
| `fts_topn` | int | `50` | FTS 候选数 |
| `vec_topn` | int | `50` | 向量候选数 |

**返回**:
```json
{
  "query": "monetary policy",
  "k": 10,
  "alpha": 0.6,
  "results": [
    {
      "chunk_id": 123,
      "doc_id": "abc123",
      "page_start": 5,
      "page_end": 5,
      "snippet": "The monetary policy transmission...",
      "score_total": 0.85,
      "score_vec": 0.9,
      "score_fts": 0.75
    }
  ],
  "fts_candidates": 50,
  "vec_candidates": 50
}
```

### `search_vector_only`

纯向量搜索。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `query` | str | - |
| `k` | int | `10` |

### `search_fts_only`

纯全文搜索。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `query` | str | - |
| `k` | int | `10` |

### `explain_search`

详细搜索解释（调试用）。

**返回额外字段**:
- `fts_only_hits`: 仅 FTS 命中
- `vec_only_hits`: 仅向量命中
- `intersection_hits`: 两者都命中
- `stats`: 统计信息

---

## 4. 数据获取

### `get_chunk`

获取 chunk 完整内容。

**参数**: `chunk_id: int`

**返回**:
```json
{
  "chunk_id": 123,
  "doc_id": "abc123",
  "chunk_index": 5,
  "page_start": 5,
  "page_end": 5,
  "text": "Full chunk text...",
  "token_count": 500,
  "has_embedding": true
}
```

### `get_document`

获取文档元数据。

**参数**: `doc_id: str`

**返回**:
```json
{
  "doc_id": "abc123",
  "title": "Paper Title",
  "authors": "Author Name",
  "year": 2024,
  "venue": "Journal Name",
  "chunk_count": 25,
  "embedded_chunk_count": 25,
  "total_tokens": 12500
}
```

### `get_document_chunks`

获取文档所有 chunks。

**参数**: `doc_id: str`

### `list_documents`

列出所有文档。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `limit` | int | `50` |
| `offset` | int | `0` |
| `order_by` | str | `"created_at"` |
| `has_embeddings` | bool | `None` |

### `update_document`

更新文档元数据。

**参数**:
| 名称 | 类型 | 必填 |
|------|------|------|
| `doc_id` | str | ✅ |
| `title` | str | ❌ |
| `authors` | str | ❌ |
| `year` | int | ❌ |
| `venue` | str | ❌ |
| `doi` | str | ❌ |
| `url` | str | ❌ |

### `delete_document`

删除文档。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `doc_id` | str | - |
| `also_delete_object` | bool | `false` |

### `reembed_document`

重新生成 embeddings。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `doc_id` | str | - |
| `batch_size` | int | `64` |
| `force` | bool | `false` |

### `rechunk_document`

重新分块文档。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `doc_id` | str | - |
| `strategy` | str | `"page_v1"` |
| `force` | bool | `false` |

### `download_pdf`

根据论文标题下载 PDF 到本地目录。

**参数**:
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | str | - | 论文标题（支持模糊匹配） |
| `output_dir` | str | `"./data"` | 输出目录 |
| `exact_match` | bool | `false` | 是否精确匹配标题 |

**返回**:
```json
{
  "success": true,
  "doc_id": "abc123...",
  "title": "Paper Title",
  "file_path": "/path/to/output/Paper Title.pdf",
  "size": 1234567,
  "size_mb": 1.18
}
```

---

## 5. 综述写作

### `build_evidence_pack`

构建证据包。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `query` | str | - |
| `k` | int | `40` |
| `per_doc_limit` | int | `3` |
| `alpha` | float | `0.6` |

**返回**:
```json
{
  "pack_id": 1,
  "query": "monetary policy effects",
  "items": [...],
  "stats": {
    "total_chunks": 40,
    "unique_docs": 15
  }
}
```

### `get_evidence_pack_info`

获取证据包详情。

**参数**: `pack_id: int`

### `list_evidence_packs`

列出所有证据包。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `limit` | int | `20` |
| `offset` | int | `0` |

### `draft_lit_review_v1`

生成文献综述草稿。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `topic` | str | - |
| `pack_id` | int | `None` |
| `k` | int | `30` |
| `outline_style` | str | `"econ_finance_canonical"` |

**返回**:
```json
{
  "topic": "Central bank digital currency",
  "outline_style": "econ_finance_canonical",
  "pack_id": 5,
  "total_sources": 25,
  "sections": [
    {
      "section_id": "research_question",
      "title": "研究问题与理论框架",
      "content": "...",
      "citations": [...]
    }
  ],
  "all_citations": [...]
}
```

### `draft_section`

生成特定章节。

**参数**:
| 名称 | 类型 |
|------|------|
| `pack_id` | int |
| `section` | str |
| `outline_style` | str |

### `get_outline_templates`

获取可用模板。

**返回**:
```json
{
  "templates": [
    {
      "name": "econ_finance_canonical",
      "display_name": "经济金融学经典结构",
      "sections": [
        {"id": "research_question", "title": "研究问题与理论框架"},
        {"id": "measurement", "title": "度量与代理变量"},
        {"id": "identification", "title": "识别策略"},
        {"id": "findings", "title": "主要发现"},
        {"id": "debates", "title": "争议与不一致发现"},
        {"id": "gaps", "title": "研究空白与未来方向"}
      ]
    }
  ]
}
```

---

## 6. 图谱抽取

### `extract_graph_v1`

抽取结构化图谱要素。

**参数**:
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `doc_id` | str | `None` | 文档 ID |
| `chunk_ids` | list[int] | `None` | 指定 chunk 列表 |
| `mode` | str | `"high_value_only"` | 筛选模式 |
| `max_chunks` | int | `60` | 最大 chunk 数 |
| `llm_model` | str | `None` | LLM 模型 |
| `min_confidence` | float | `0.8` | 最小置信度 |
| `dry_run` | bool | `false` | 仅预览 |
| `concurrency` | int | `60` | 并发数 |

**返回**:
```json
{
  "doc_id": "abc123",
  "stats": {
    "processed_chunks": 25,
    "new_entities": 45,
    "new_mentions": 120,
    "new_relations": 35,
    "new_claims": 18,
    "skipped_low_confidence": 5
  }
}
```

### `select_high_value_chunks`

筛选高价值 chunks。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `doc_id` | str | `None` |
| `pack_id` | int | `None` |
| `max_chunks` | int | `60` |
| `keyword_mode` | str | `"default"` |

### `extract_graph_missing`

批量抽取未处理文档。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `limit_docs` | int | `50` |
| `llm_model` | str | `None` |
| `min_confidence` | float | `0.8` |
| `concurrency` | int | `30` |
| `max_chunks` | int | `60` |

---

## 7. 实体规范化

### `canonicalize_entities_v1`

规范化并合并重复实体。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `types` | list[str] | `["Topic", "MeasureProxy", "IdentificationStrategy", "Method"]` |
| `suggest_only` | bool | `false` |
| `max_groups` | int | `5000` |

**返回**:
```json
{
  "executed": true,
  "merged_groups": 45,
  "merged_entities": 120,
  "suggestions": [...]
}
```

### `merge_entities`

手动合并两个实体。

**参数**:
| 名称 | 类型 |
|------|------|
| `from_entity_id` | int |
| `to_entity_id` | int |
| `reason` | str |

### `lock_entity`

锁定/解锁实体。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `entity_id` | int | - |
| `is_locked` | bool | `true` |

---

## 8. 社区构建

### `build_communities_v1`

构建主题社区。

**参数**:
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `level` | str | `"macro"` | macro/micro |
| `min_df` | int | `3` | 最小文档频率 |
| `resolution` | float | `1.0` | Leiden 分辨率 |
| `max_nodes` | int | `20000` | 最大节点数 |
| `rebuild` | bool | `false` | 清除旧结果 |

**返回**:
```json
{
  "communities": [
    {
      "comm_id": 1,
      "size": 45,
      "top_entities": [
        {"entity_id": 123, "type": "Topic", "canonical_name": "Monetary Policy", "weight": 5.2}
      ]
    }
  ]
}
```

### `build_community_evidence_pack`

为社区构建证据包。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `comm_id` | int | - |
| `max_chunks` | int | `100` |
| `per_doc_limit` | int | `4` |

---

## 9. 摘要导出

### `summarize_community_v1`

生成社区结构化摘要。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `comm_id` | int | - |
| `pack_id` | int | `None` |
| `llm_model` | str | `None` |
| `max_chunks` | int | `100` |
| `style` | str | `"econ_finance"` |

### `summarize_all_communities`

批量生成社区摘要。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `level` | str | `None` |
| `concurrency` | int | `5` |
| `comm_ids` | list[int] | `None` |
| `force` | bool | `false` |

### `export_evidence_matrix_v1`

导出证据矩阵。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `comm_id` | int | `None` |
| `topic` | str | `None` |
| `format` | str | `"json"` |
| `limit_docs` | int | `None` |

---

## 10. 图谱维护

### `graph_status`

查看图谱覆盖状态。

**参数**: `doc_id: str | None`

### `clear_graph`

清理图谱数据。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `doc_id` | str | `None` |
| `clear_all` | bool | `false` |

### `rebuild_communities`

重建社区。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `level` | str | `"macro"` |
| `min_df` | int | `3` |
| `resolution` | float | `1.0` |

---

## 11. 关系规范化

### `canonicalize_relations_v1`

规范化合并关系。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `scope` | str | `"all"` |
| `predicate_whitelist` | list[str] | `None` |
| `qualifier_keys_keep` | list[str] | `["id_family", ...]` |
| `dry_run` | bool | `false` |

### `export_relations_compact_v1`

导出紧凑关系视图。

**参数**:
| 名称 | 类型 |
|------|------|
| `comm_id` | int |
| `pack_id` | int |

---

## 12. Claim 分组

### `build_claim_groups_v1`

构建 claim 分组。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `scope` | str | `"all"` |
| `max_claims_per_doc` | int | `100` |
| `dry_run` | bool | `false` |

### `export_claim_matrix_grouped_v1`

导出分组 claim 矩阵。

**参数**:
| 名称 | 类型 |
|------|------|
| `comm_id` | int |
| `pack_id` | int |

---

## 13. v1.2 增强工具

### `taxonomy_list_terms`

列出词表规则。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `kind` | str | `None` |
| `enabled_only` | bool | `true` |

### `taxonomy_upsert_term`

添加/更新词表规则。

**参数**:
| 名称 | 类型 | 必填 |
|------|------|------|
| `kind` | str | ✅ |
| `family` | str | ✅ |
| `pattern` | str | ✅ |
| `priority` | int | ❌ |
| `enabled` | bool | ❌ |
| `notes` | str | ❌ |

### `compute_topic_df_cache`

计算 Topic 文档频率缓存。

### `assign_claim_features_v1_2`

分配 claim 特征。

**参数**: `scope: str = "all"`

### `build_claim_groups_v1_2`

构建 v1.2 claim 分组。

**参数**: `scope: str = "all"`

### `split_large_claim_groups_v1_2`

拆分大型分组。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `split_threshold` | int | `150` |
| `target_size` | int | `120` |

### `export_claim_matrix_grouped_v1_2`

导出 v1.2 分组矩阵。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `comm_id` | int | `None` |
| `pack_id` | int | `None` |
| `top_k_per_group` | int | `10` |
| `include_subgroups` | bool | `true` |

---

## 14. Review 工具

### `generate_review_outline_data_v1`

生成综述大纲。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `topic` | str | `None` |
| `comm_ids` | list[int] | `None` |
| `outline_style` | str | `"econ_finance_canonical"` |
| `rebuild` | bool | `false` |

### `build_section_evidence_pack_v1`

构建章节证据包。

**参数**:
| 名称 | 类型 | 默认值 |
|------|------|--------|
| `outline_id` | str | - |
| `section_id` | str | - |
| `max_chunks` | int | `60` |
| `per_doc_limit` | int | `4` |
| `rebuild` | bool | `false` |

### `export_section_packet_v1`

导出章节写作输入包。

**参数**: `pack_id: int`

### `lint_section_v1`

验证章节引用合规。

**参数**:
| 名称 | 类型 |
|------|------|
| `pack_id` | int |
| `markdown` | str |
| `require_citations_per_paragraph` | bool |
| `min_citations_per_paragraph` | int |

### `lint_review_v1`

验证全文合规。

**参数**:
| 名称 | 类型 |
|------|------|
| `pack_ids` | list[int] |
| `markdown` | str |

### `compose_full_template_v1`

生成全文结构模板。

**参数**: `outline_id: str`

---

## 使用示例

### 完整导入和检索流程

```python
# 1. 健康检查
health_check()

# 2. 导入 PDF
import_pdf(
    file_path="/path/to/paper.pdf",
    title="Paper Title",
    authors="Author Name",
    year=2024
)

# 3. 搜索
search_hybrid(
    query="monetary policy transmission",
    k=10,
    alpha=0.6
)
```

### 知识图谱构建

```python
# 1. 抽取图谱
extract_graph_missing(limit_docs=50)

# 2. 规范化实体
canonicalize_entities_v1()

# 3. 构建社区
build_communities_v1(level="macro")

# 4. 生成摘要
summarize_all_communities(level="macro")
```

### 文献综述生成

```python
# 1. 构建证据包
result = build_evidence_pack(
    query="central bank digital currency",
    k=40
)
pack_id = result["pack_id"]

# 2. 生成综述
draft_lit_review_v1(
    pack_id=pack_id,
    outline_style="econ_finance_canonical"
)
```
