Paperlib MCP

Instructions

Implementation Reference

• src/paperlib_mcp/tools/review.py:903-997 (handler)

  The primary handler function for the 'lint_review_v1' tool. It validates citations in the full review markdown by checking if cited chunks exist in the database and are from the whitelisted evidence packs provided via pack_ids. Returns pass/fail status, issues list, and statistics.

  @mcp.tool()
  def lint_review_v1(
      pack_ids: list[int],
      markdown: str,
  ) -> dict[str, Any]:
      """验证全文合规
  
      检查完整综述是否符合所有引用规则。
  
      Args:
          pack_ids: 允许的证据包 ID 列表（白名单）
          markdown: 完整的综述 markdown
  
      Returns:
          passed, issues[], stats
      """
      try:
          # 收集所有允许的 chunk_ids
          all_valid_chunk_ids: set[int] = set()
          pack_chunk_counts: dict[int, int] = {}
  
          for pack_id in pack_ids:
              pack_chunks = query_all(
                  "SELECT chunk_id FROM evidence_pack_items WHERE pack_id = %s",
                  (pack_id,),
              )
              chunk_ids = {row["chunk_id"] for row in pack_chunks}
              all_valid_chunk_ids.update(chunk_ids)
              pack_chunk_counts[pack_id] = len(chunk_ids)
  
          if not all_valid_chunk_ids:
              return {"error": "No valid chunks in provided pack_ids"}
  
          # 解析引用
          citation_pattern = r"\[\[chunk:(\d+)\]\]"
          citations = re.findall(citation_pattern, markdown)
          cited_chunk_ids = [int(c) for c in citations]
  
          issues = []
          valid_citations = 0
          invalid_citations = 0
  
          # 检查每个引用
          for chunk_id in cited_chunk_ids:
              # 检查是否存在
              exists = query_one(
                  "SELECT chunk_id FROM chunks WHERE chunk_id = %s",
                  (chunk_id,),
              )
              if not exists:
                  issues.append({
                      "severity": "error",
                      "rule": "CHUNK_NOT_FOUND",
                      "chunk_id": chunk_id,
                      "message": f"Chunk {chunk_id} does not exist",
                  })
                  invalid_citations += 1
                  continue
  
              # 检查是否在白名单内
              if chunk_id not in all_valid_chunk_ids:
                  issues.append({
                      "severity": "error",
                      "rule": "CHUNK_OUT_OF_PACK",
                      "chunk_id": chunk_id,
                      "message": f"Chunk {chunk_id} is not in whitelisted packs",
                  })
                  invalid_citations += 1
                  continue
  
              valid_citations += 1
  
          # 通过判定
          has_errors = any(issue["severity"] == "error" for issue in issues)
  
          return {
              "passed": not has_errors,
              "issues": issues,
              "stats": {
                  "total_citations": len(cited_chunk_ids),
                  "unique_chunks_cited": len(set(cited_chunk_ids)),
                  "valid_citations": valid_citations,
                  "invalid_citations": invalid_citations,
                  "pack_count": len(pack_ids),
                  "total_allowed_chunks": len(all_valid_chunk_ids),
                  "citation_coverage_pct": (
                      len(set(cited_chunk_ids) & all_valid_chunk_ids) / len(all_valid_chunk_ids) * 100
                      if all_valid_chunk_ids else 0
                  ),
              },
          }
  
      except Exception as e:
          return {"error": str(e), "passed": False}

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

  The registration call to register_review_tools(mcp), which defines and registers the lint_review_v1 tool (and other review tools) with the FastMCP instance.

  # 注册 M3 Review 工具
  register_review_tools(mcp)

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

  Import of the register_review_tools function from the review tools module, prerequisite for registering the lint_review_v1 tool.

  from paperlib_mcp.tools.review import register_review_tools

• src/paperlib_mcp/tools/review.py:908-918 (schema)

  Docstring providing the tool description, argument descriptions, and return format, which serves as the schema for input/output in FastMCP.

  """验证全文合规
  
  检查完整综述是否符合所有引用规则。
  
  Args:
      pack_ids: 允许的证据包 ID 列表（白名单）
      markdown: 完整的综述 markdown
  
  Returns:
      passed, issues[], stats
  """