paperqa-mcp-server

Instructions

Implementation Reference

• src/paperqa_mcp_server/__init__.py:102-118 (handler)

  The tool registration and entry point for 'index_status'.

  @mcp.tool()
  async def index_status() -> str:
      """Check the health of the paper index.
  
      Returns a summary of how many papers are indexed, how many have
      errors, and how many are unindexed. Use this to diagnose why
      paper_qa queries might be failing or timing out.
      """
      status = _index_status()
      lines = [
          f"Index status: {status['message']}",
          f"  Indexed: {status['indexed']}",
          f"  Errors:  {status['errored']}",
          f"  Unindexed: {status['unindexed']}",
          f"  Total files: {status['total']}",
      ]
      return "\n".join(lines)

• src/paperqa_mcp_server/__init__.py:39-99 (helper)

  The helper function containing the actual logic for checking the index status.

  def _index_status(settings: Settings | None = None) -> dict:
      """Read the index manifest and compare against files in the paper directory.
  
      Returns a dict with keys: indexed, errored, unindexed, total, ready, message.
      """
      if settings is None:
          settings = _settings()
      index_name = settings.get_index_name()
      index_dir = pathlib.Path(settings.agent.index.index_directory) / index_name
      paper_dir = pathlib.Path(settings.agent.index.paper_directory)
      files_filter = settings.agent.index.files_filter
  
      # Discover files PaperQA would try to index (same filter as paperqa)
      total = 0
      if paper_dir.is_dir():
          total = sum(1 for f in paper_dir.rglob("*") if files_filter(f))
  
      # Read the manifest
      manifest_path = index_dir / "files.zip"
      manifest: dict[str, str] = {}
      manifest_error = False
      if manifest_path.exists():
          try:
              manifest = pickle.loads(zlib.decompress(manifest_path.read_bytes()))
          except Exception:
              manifest_error = True
  
      errored = sum(1 for v in manifest.values() if v == "ERROR")
      indexed = len(manifest) - errored
      unindexed = max(0, total - len(manifest))
  
      ready = unindexed <= _UNINDEXED_THRESHOLD and not manifest_error
      if manifest_error:
          message = (
              f"Index manifest is corrupt ({total} files on disk)."
              " Rebuild the index from the terminal"
              " — see the paperqa-mcp-server README, step 6."
          )
      else:
          message = f"{indexed}/{total} papers indexed"
          if errored:
              message += f", {errored} errors"
          if unindexed:
              message += f", {unindexed} unindexed"
          if ready:
              message += ". Ready to query."
          else:
              message += (
                  ". Queries will fail or time out."
                  " Please finish building the index from the terminal"
                  " — see the paperqa-mcp-server README, step 6."
              )
  
      return {
          "indexed": indexed,
          "errored": errored,
          "unindexed": unindexed,
          "total": total,
          "ready": ready,
          "message": message,
      }