Paperlib MCP

Instructions

Implementation Reference

• src/paperlib_mcp/tools/writing.py:377-431 (handler)

  The core handler function for the 'list_evidence_packs' tool. It uses a SQL query to fetch paginated list of evidence packs from the database, including counts of items and documents per pack, and returns structured JSON with total count and pack summaries.

  @mcp.tool()
  def list_evidence_packs(limit: int = 20, offset: int = 0) -> dict[str, Any]:
      """列出所有证据包
      
      查看已保存的证据包列表。
      
      Args:
          limit: 返回数量限制，默认 20
          offset: 分页偏移量，默认 0
          
      Returns:
          证据包列表
      """
      try:
          packs = query_all(
              """
              SELECT 
                  ep.pack_id,
                  ep.query,
                  ep.created_at::text,
                  COUNT(epi.id) as item_count,
                  COUNT(DISTINCT epi.doc_id) as doc_count
              FROM evidence_packs ep
              LEFT JOIN evidence_pack_items epi ON ep.pack_id = epi.pack_id
              GROUP BY ep.pack_id
              ORDER BY ep.created_at DESC
              LIMIT %s OFFSET %s
              """,
              (limit, offset)
          )
          
          total = query_one("SELECT COUNT(*) as count FROM evidence_packs")
          
          return {
              "total": total["count"] if total else 0,
              "limit": limit,
              "offset": offset,
              "packs": [
                  {
                      "pack_id": p["pack_id"],
                      "query": p["query"],
                      "created_at": p["created_at"],
                      "item_count": p["item_count"],
                      "doc_count": p["doc_count"],
                  }
                  for p in packs
              ],
          }
          
      except Exception as e:
          return {
              "error": str(e),
              "total": 0,
              "packs": [],
          }

• src/paperlib_mcp/server.py:16-37 (registration)

  The registration of writing tools (including list_evidence_packs) via import and call to register_writing_tools(mcp) on the FastMCP server instance.

  from paperlib_mcp.tools.writing import register_writing_tools
  
  # M2 GraphRAG 工具
  from paperlib_mcp.tools.graph_extract import register_graph_extract_tools
  from paperlib_mcp.tools.graph_canonicalize import register_graph_canonicalize_tools
  from paperlib_mcp.tools.graph_community import register_graph_community_tools
  from paperlib_mcp.tools.graph_summarize import register_graph_summarize_tools
  from paperlib_mcp.tools.graph_maintenance import register_graph_maintenance_tools
  
  # M3 Review 工具
  from paperlib_mcp.tools.review import register_review_tools
  
  # M4 Canonicalization & Grouping 工具
  from paperlib_mcp.tools.graph_relation_canonicalize import register_graph_relation_canonicalize_tools
  from paperlib_mcp.tools.graph_claim_grouping import register_graph_claim_grouping_tools
  from paperlib_mcp.tools.graph_v12 import register_graph_v12_tools
  
  register_health_tools(mcp)
  register_import_tools(mcp)
  register_search_tools(mcp)
  register_fetch_tools(mcp)
  register_writing_tools(mcp)

• src/paperlib_mcp/tools/writing.py:134-198 (helper)

  Supporting helper function get_evidence_pack used in other writing tools, but referenced in the context of evidence packs.

  def get_evidence_pack(pack_id: int) -> EvidencePack | None:
      """获取证据包内容
      
      Args:
          pack_id: 证据包 ID
          
      Returns:
          证据包对象，如果不存在返回 None
      """
      # 获取证据包元数据
      pack = query_one(
          """
          SELECT pack_id, query, params_json, created_at::text
          FROM evidence_packs
          WHERE pack_id = %s
          """,
          (pack_id,)
      )
      
      if not pack:
          return None
      
      # 获取证据包条目
      items = query_all(
          """
          SELECT 
              epi.doc_id,
              epi.chunk_id,
              epi.rank,
              c.page_start,
              c.page_end,
              c.text
          FROM evidence_pack_items epi
          JOIN chunks c ON epi.chunk_id = c.chunk_id
          WHERE epi.pack_id = %s
          ORDER BY epi.rank
          """,
          (pack_id,)
      )
      
      # 统计
      unique_docs = len(set(item["doc_id"] for item in items))
      
      return EvidencePack(
          pack_id=pack["pack_id"],
          query=pack["query"],
          params=pack["params_json"] or {},
          items=[
              EvidencePackItem(
                  doc_id=item["doc_id"],
                  chunk_id=item["chunk_id"],
                  page_start=item["page_start"],
                  page_end=item["page_end"],
                  text=item["text"],
                  score=1.0 / (item["rank"] + 1) if item["rank"] is not None else 0.5,  # 基于排名的伪分数
              )
              for item in items
          ],
          stats={
              "total_chunks": len(items),
              "unique_docs": unique_docs,
          }
      )

• src/paperlib_mcp/tools/writing.py:125-132 (schema)

  Pydantic model for EvidencePack structure, used in related tools for type safety and serialization.

  class EvidencePack(BaseModel):
      """证据包"""
      pack_id: int
      query: str
      params: dict[str, Any]
      items: list[EvidencePackItem]
      stats: dict[str, Any]