Paperlib MCP

Instructions

Implementation Reference

• src/paperlib_mcp/tools/graph_v12.py:237-320 (handler)

  The main handler function for the 'build_claim_groups_v1_2' tool, decorated with @mcp.tool(). It queries precomputed claim features, groups claims by a composite key (topic, outcome_family, etc.), deletes old groups, and inserts new groups and members into the database.

  @mcp.tool()
  def build_claim_groups_v1_2(
      scope: str = "all",
  ) -> dict[str, Any]:
      """基于 claim_features 构建 v1.2 claim groups"""
      try:
          # 从 claim_features 读取，按 group_key 分组
          features = query_all("""
              SELECT claim_id, primary_topic_key, outcome_family, treatment_family, 
                     sign, id_family, setting_bin
              FROM claim_features
          """)
          
          if not features:
              return {"error": "No claim features found. Run assign_claim_features_v1_2 first."}
  
          groups: dict[str, list[int]] = defaultdict(list)
          group_meta: dict[str, dict] = {}
          
          for f in features:
              # v1.2 group_key 使用预计算的 features
              group_key = "|".join([
                  f["primary_topic_key"] or "unknown",
                  f["outcome_family"],
                  f["treatment_family"],
                  f["sign"] or "null",
                  f["id_family"] or "general",
                  f["setting_bin"],
              ])
              groups[group_key].append(f["claim_id"])
              
              if group_key not in group_meta:
                  # 查找 topic entity id
                  topic_ent = query_one(
                      "SELECT entity_id FROM entities WHERE canonical_key = %s",
                      (f["primary_topic_key"],)
                  )
                  group_meta[group_key] = {
                      "topic_entity_id": topic_ent["entity_id"] if topic_ent else None,
                      "sign": f["sign"],
                      "setting": f["setting_bin"],
                      "id_family": f["id_family"],
                  }
  
          # 写入 claim_groups (清空旧组后重建)
          params_json = json.dumps(V1_2_PARAMS, sort_keys=True)
          total_members = 0
          
          with get_db() as conn:
              with conn.cursor() as cur:
                  # 清空旧的 v1 组
                  cur.execute("DELETE FROM claim_group_members")
                  cur.execute("DELETE FROM claim_groups")
              
              for key, claim_ids in groups.items():
                  meta = group_meta[key]
                  try:
                      with conn.cursor() as cur:
                          with conn.transaction():
                              cur.execute("""
                                  INSERT INTO claim_groups 
                                  (group_key, topic_entity_id, sign, setting, id_family, params_json)
                                  VALUES (%s, %s, %s, %s, %s, %s::jsonb)
                                  RETURNING group_id
                              """, (key, meta["topic_entity_id"], meta["sign"], 
                                    meta["setting"], meta["id_family"], params_json))
                              group_id = cur.fetchone()["group_id"]
                              
                              for cid in claim_ids:
                                  cur.execute("""
                                      INSERT INTO claim_group_members (group_id, claim_id)
                                      VALUES (%s, %s)
                                  """, (group_id, cid))
                                  total_members += 1
                  except Exception as e:
                      print(f"Error creating group {key}: {e}")
  
              with conn.cursor() as cur:
                  cur.execute("SELECT COUNT(*) as n FROM claim_groups")
                  group_count = cur.fetchone()["n"]
  
          return {"groups_created": group_count, "total_members": total_members}
      except Exception as e:
          return {"error": str(e)}

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

  The call to register_graph_v12_tools(mcp) which registers the build_claim_groups_v1_2 tool (among others) to the FastMCP instance.

  register_graph_v12_tools(mcp)

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

  Configuration parameters used in the tool for v1.2 grouping rules, including normalization settings and grouping fields. Referenced as params_json in the handler.

  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"],
  }