Paperlib MCP

Instructions

Implementation Reference

• src/paperlib_mcp/tools/graph_v12.py:424-516 (handler)

  The primary handler function implementing the logic for the 'export_claim_matrix_grouped_v1_2' tool. It queries claim groups, filters by comm_id or pack_id, retrieves top-k claims per group sorted by sign and confidence, and returns structured results.

  @mcp.tool()
  def export_claim_matrix_grouped_v1_2(
      comm_id: int | None = None,
      pack_id: int | None = None,
      top_k_per_group: int = 10,
      include_subgroups: bool = True,
  ) -> dict[str, Any]:
      """导出分组 claim 矩阵，每组返回 top-k 代表 claims (按 confidence 排序，sign 分层)"""
      try:
          # 构建过滤条件
          where_clauses = []
          params = []
          
          if comm_id:
              where_clauses.append("""
                  EXISTS (
                      SELECT 1 FROM claim_group_members cgm
                      JOIN claims c ON c.claim_id = cgm.claim_id
                      JOIN mentions m ON m.doc_id = c.doc_id
                      JOIN community_members cm ON cm.entity_id = m.entity_id
                      WHERE cm.comm_id = %s AND cgm.group_id = g.group_id
                  )
              """)
              params.append(comm_id)
          elif pack_id:
              where_clauses.append("""
                  EXISTS (
                      SELECT 1 FROM claim_group_members cgm
                      JOIN claims c ON c.claim_id = cgm.claim_id
                      JOIN evidence_pack_items epi ON epi.chunk_id = c.chunk_id
                      WHERE epi.pack_id = %s AND cgm.group_id = g.group_id
                  )
              """)
              params.append(pack_id)
          
          # 是否包含子组
          if not include_subgroups:
              where_clauses.append("g.parent_group_id IS NULL")
          
          where_sql = " WHERE " + " AND ".join(where_clauses) if where_clauses else ""
          
          # 获取分组
          groups = query_all(f"""
              SELECT 
                  g.group_id, g.group_key, g.parent_group_id, g.subgroup_key,
                  g.sign, g.id_family, g.setting,
                  e.canonical_name as topic_name,
                  (SELECT COUNT(*) FROM claim_group_members cgm WHERE cgm.group_id = g.group_id) as member_count
              FROM claim_groups g
              LEFT JOIN entities e ON e.entity_id = g.topic_entity_id
              {where_sql}
              ORDER BY member_count DESC
          """, tuple(params))
          
          # 为每个 group 获取 top-k claims（按 sign 分层 + confidence 排序）
          result_groups = []
          for g in groups:
              # 获取该组的 claims，按 sign 和 confidence 排序
              claims = query_all("""
                  SELECT c.claim_id, c.doc_id, c.claim_text, c.sign, c.confidence,
                         cf.outcome_family, cf.treatment_family
                  FROM claim_group_members cgm
                  JOIN claims c ON c.claim_id = cgm.claim_id
                  LEFT JOIN claim_features cf ON cf.claim_id = c.claim_id
                  WHERE cgm.group_id = %s
                  ORDER BY 
                      CASE c.sign 
                          WHEN 'positive' THEN 1 
                          WHEN 'negative' THEN 2 
                          WHEN 'mixed' THEN 3 
                          ELSE 4 
                      END,
                      c.confidence DESC
                  LIMIT %s
              """, (g["group_id"], top_k_per_group))
              
              result_groups.append({
                  "group_id": g["group_id"],
                  "group_key": g["group_key"],
                  "parent_group_id": g["parent_group_id"],
                  "subgroup_key": g["subgroup_key"],
                  "topic_name": g["topic_name"],
                  "sign": g["sign"],
                  "member_count": g["member_count"],
                  "top_claims": claims,
              })
          
          return {
              "total_groups": len(result_groups),
              "groups": result_groups
          }
      except Exception as e:
          return {"error": str(e)}

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

  The call to register_graph_v12_tools(mcp) in the main server file, which defines and registers the tool among other v1.2 GraphRAG tools.

  register_graph_v12_tools(mcp)

• src/paperlib_mcp/tools/graph_v12.py:17-26 (helper)

  Configuration constants for v1.2 tools, defining grouping fields used in claim grouping which this export tool relies on.

  V1_2_PARAMS = {
      "version": "1.2",
      "normalization": {
          "text_norm": "lower+punct+ws",
          "json_dumps": "sort_keys=True,separators=(',',':')",
          "sep": "\\u001f"
      },
      "grouping_fields": ["primary_topic_key", "outcome_family", "treatment_family", "sign", "id_family", "setting_bin"],
  }