Paperlib MCP

Instructions

Implementation Reference

• src/paperlib_mcp/tools/graph_maintenance.py:469-555 (handler)

  The handler function for the 'clear_graph' tool. It deletes GraphRAG-related data from the database for a specific document (if doc_id provided) or all data (if clear_all=True). Uses ClearGraphOut model for response and handles errors.

  @mcp.tool()
  def clear_graph(doc_id: str | None = None, clear_all: bool = False) -> dict[str, Any]:
      """清理 GraphRAG 数据
      
      清理指定文档或全部的 GraphRAG 数据。
      
      Args:
          doc_id: 文档 ID（清理单个文档）
          clear_all: 是否清理全部（危险操作）
          
      Returns:
          清理结果，包含删除的记录数
      """
      try:
          if not doc_id and not clear_all:
              return ClearGraphOut(
                  ok=False,
                  error=MCPErrorModel(code="VALIDATION_ERROR", message="Must provide doc_id or set clear_all=True"),
              ).model_dump()
          
          deleted_counts = {}
          
          with get_db() as conn:
              with conn.cursor() as cur:
                  if clear_all:
                      # 按顺序清理（先清理依赖表）
                      cur.execute("DELETE FROM community_summaries")
                      deleted_counts["community_summaries"] = cur.rowcount
                      
                      cur.execute("DELETE FROM community_members")
                      deleted_counts["community_members"] = cur.rowcount
                      
                      cur.execute("DELETE FROM communities")
                      deleted_counts["communities"] = cur.rowcount
                      
                      cur.execute("DELETE FROM claims")
                      deleted_counts["claims"] = cur.rowcount
                      
                      cur.execute("DELETE FROM relations")
                      deleted_counts["relations"] = cur.rowcount
                      
                      cur.execute("DELETE FROM mentions")
                      deleted_counts["mentions"] = cur.rowcount
                      
                      cur.execute("DELETE FROM entity_aliases")
                      deleted_counts["entity_aliases"] = cur.rowcount
                      
                      cur.execute("DELETE FROM entities")
                      deleted_counts["entities"] = cur.rowcount
                      
                      cur.execute("DELETE FROM entity_merge_log")
                      deleted_counts["entity_merge_log"] = cur.rowcount
                  else:
                      # 清理单个文档
                      # 删除 claims
                      cur.execute("DELETE FROM claims WHERE doc_id = %s", (doc_id,))
                      deleted_counts["claims"] = cur.rowcount
                      
                      # 删除 mentions
                      cur.execute("DELETE FROM mentions WHERE doc_id = %s", (doc_id,))
                      deleted_counts["mentions"] = cur.rowcount
                      
                      # 删除 relations（通过 evidence）
                      cur.execute(
                          "DELETE FROM relations WHERE evidence->>'doc_id' = %s",
                          (doc_id,)
                      )
                      deleted_counts["relations"] = cur.rowcount
                      
                      # 可选：删除 Paper entity
                      # cur.execute(
                      #     "DELETE FROM entities WHERE type = 'Paper' AND canonical_key = %s",
                      #     (doc_id,)
                      # )
                      # deleted_counts["paper_entity"] = cur.rowcount
          
          return ClearGraphOut(
              ok=True,
              deleted_counts=deleted_counts,
          ).model_dump()
          
      except Exception as e:
          return ClearGraphOut(
              ok=False,
              error=MCPErrorModel(code="DB_CONN_ERROR", message=str(e)),
          ).model_dump()

• src/paperlib_mcp/models_graph.py:379-390 (schema)

  Pydantic schemas for clear_graph tool: ClearGraphIn defines optional doc_id and clear_all parameters; ClearGraphOut defines response with success flag, deleted counts, and optional error.

  class ClearGraphIn(BaseModel):
      """clear_graph 输入"""
      doc_id: Optional[str] = None
      clear_all: bool = False
  
  
  class ClearGraphOut(BaseModel):
      """clear_graph 输出"""
      ok: bool
      deleted_counts: Optional[dict[str, int]] = None
      error: Optional[MCPErrorModel] = None

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

  The registration point where register_graph_maintenance_tools is called on the MCP instance, which in turn defines and registers the clear_graph tool using @mcp.tool() decorator.

  register_graph_maintenance_tools(mcp)

• src/paperlib_mcp/tools/graph_maintenance.py:22-25 (registration)

  The function that defines and registers all graph maintenance tools, including clear_graph, by using @mcp.tool() decorators inside it.

  def register_graph_maintenance_tools(mcp: FastMCP) -> None:
      """注册 GraphRAG 维护工具"""