Paperlib MCP

Instructions

Implementation Reference

• src/paperlib_mcp/tools/search.py:527-569 (handler)

  The handler function for 'search_fts_only' tool. It performs pure full-text search using PostgreSQL FTS, formats results, and handles errors. Registered via @mcp.tool() decorator.

  def search_fts_only(
      query: str,
      k: int = 10,
  ) -> dict[str, Any]:
      """纯全文搜索
      
      仅使用 PostgreSQL 全文搜索，适合精确关键词匹配的场景。
      
      Args:
          query: 搜索查询字符串（支持布尔运算符）
          k: 返回结果数量，默认 10
          
      Returns:
          搜索结果列表
      """
      try:
          results = search_fts(query, k)
          
          formatted_results = []
          for r in results:
              text = r["text"]
              snippet = text[:200] + "..." if len(text) > 200 else text
              formatted_results.append({
                  "chunk_id": r["chunk_id"],
                  "doc_id": r["doc_id"],
                  "page_start": r["page_start"],
                  "page_end": r["page_end"],
                  "snippet": snippet,
                  "rank": r["rank"],
              })
          
          return {
              "query": query,
              "k": k,
              "results": formatted_results,
          }
      except Exception as e:
          return {
              "error": str(e),
              "query": query,
              "k": k,
              "results": [],
          }

• src/paperlib_mcp/tools/search.py:53-76 (helper)

  Helper function 'search_fts' that executes the raw SQL query for full-text search, called by the search_fts_only handler.

  def search_fts(query: str, limit: int = 50) -> list[dict[str, Any]]:
      """全文搜索
      
      Args:
          query: 搜索查询
          limit: 返回结果数量
          
      Returns:
          搜索结果列表，包含 chunk_id, doc_id, page_start, page_end, text, rank
      """
      sql = """
      SELECT 
          c.chunk_id,
          c.doc_id,
          c.page_start,
          c.page_end,
          c.text,
          ts_rank(c.tsv, websearch_to_tsquery('english', %s)) as rank
      FROM chunks c
      WHERE c.tsv @@ websearch_to_tsquery('english', %s)
      ORDER BY rank DESC
      LIMIT %s
      """
      return query_all(sql, (query, query, limit))

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

  Call to register_search_tools(mcp) which defines and registers the search_fts_only tool among others in the main MCP server.

  register_search_tools(mcp)