list_evidence_packs

Retrieve and browse saved evidence packs for academic literature management. View organized collections of research materials with pagination controls.

Instructions

列出所有证据包

查看已保存的证据包列表。

Args: limit: 返回数量限制，默认 20 offset: 分页偏移量，默认 0

Returns: 证据包列表

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`offset`	No

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]

Paperlib MCP