paperqa-mcp-server 0.1.0__tar.gz

paperqa_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+*.egg-info/
+dist/
+build/
+uv.lock

paperqa_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Menyoung Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paperqa_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: paperqa-mcp-server
+Version: 0.1.0
+Summary: MCP server exposing PaperQA2 for deep synthesis across scientific papers
+Project-URL: Repository, https://github.com/menyoung/paperqa-mcp-server
+Project-URL: Issues, https://github.com/menyoung/paperqa-mcp-server/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: llm,mcp,paperqa,rag,research,scientific-literature
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: paper-qa<2026.3,>=2026.2
+Requires-Dist: pillow
+Description-Content-Type: text/markdown
+
+# paperqa-mcp-server
+
+Give Claude the ability to read, search, and synthesize across your
+entire PDF library. Built on [PaperQA2](https://github.com/Future-House/paper-qa).
+
+Point it at your Zotero storage folder (or any folder of PDFs) and ask
+Claude questions that require deep reading across multiple papers.
+
+## Quick start
+
+### 1. Install uv
+
+[uv](https://docs.astral.sh/uv/) is a Python package manager. If you don't
+have it yet:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+After installing, **restart your terminal** so `uv` is on your PATH.
+
+Verify it works:
+
+```bash
+uv --version
+```
+
+### 2. Get an OpenAI API key
+
+PaperQA2 uses OpenAI for embeddings and internal reasoning. Get a key at
+https://platform.openai.com/api-keys
+
+### 3. Test that it runs
+
+This downloads ~90 Python packages the first time — that's normal:
+
+```bash
+uvx paperqa-mcp-server --help 2>/dev/null; echo "OK if no Python errors above"
+```
+
+### 4. Add to Claude Desktop
+
+1. Open Claude Desktop
+2. Go to **Settings → Developer → Edit Config**
+3. This opens `claude_desktop_config.json`. Add a `paperqa` entry inside
+   `mcpServers` (create `mcpServers` if it doesn't exist):
+
+First, find your full path to `uvx`:
+
+```bash
+which uvx           # e.g. /Users/yourname/.local/bin/uvx
+```
+
+Then use that path in the config:
+
+```json
+{
+  "mcpServers": {
+    "paperqa": {
+      "command": "/FULL/PATH/TO/uvx",
+      "args": ["paperqa-mcp-server"],
+      "env": {
+        "OPENAI_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
+```
+
+Replace the two placeholders:
+- `/FULL/PATH/TO/uvx` — paste the output of `which uvx`
+- `sk-your-key-here` — your OpenAI API key from step 2
+
+If your PDFs are somewhere other than `~/Zotero/storage`, add a
+`PAPER_DIRECTORY` entry to `env`:
+
+```json
+"env": {
+  "OPENAI_API_KEY": "sk-your-key-here",
+  "PAPER_DIRECTORY": "/full/path/to/your/pdfs"
+}
+```
+
+4. **Quit Claude Desktop completely** (Cmd+Q, not just close the window)
+   and reopen it
+5. You should see a hammer icon — click it and `paper_qa` should be listed
+
+### 5. Pre-build the index
+
+Before Claude can search your papers, the server needs to build a search
+index. This reads each PDF, splits it into chunks, and sends the chunks
+to OpenAI's embedding API. With hundreds of papers this takes a while
+and costs a few dollars in API calls.
+
+If you have more than 10 unindexed papers, the server will refuse to
+answer queries and tell you to run this step first. A few new papers
+will be indexed automatically when you query.
+
+```bash
+OPENAI_API_KEY=sk-your-key-here uvx paperqa-mcp-server index
+```
+
+**If this crashes** with a rate limit error, just re-run the same command.
+It picks up where it left off — each run indexes more files. With a large
+library (500+ papers) you may need to run it a few times.
+
+After that, the index is cached at `~/.pqa/indexes/`. Only new or changed
+files get re-processed on subsequent runs.
+
+## Troubleshooting
+
+**"Server disconnected" in Claude Desktop**
+
+Claude Desktop has a short startup timeout. If `uv` needs to download
+packages on first launch, it will time out. Fix: run `uvx paperqa-mcp-server`
+once from the terminal first so packages are cached.
+
+**"Index incomplete" when querying**
+
+The server checks the index before each query. If too many papers are
+unindexed, it returns a diagnostic message instead of trying (and
+failing) to index them all on the fly. Fix: run the index command in
+step 5.
+
+**Hammer icon doesn't appear**
+
+Make sure you quit Claude Desktop completely (Cmd+Q) and reopened it.
+Check for JSON syntax errors in `claude_desktop_config.json` — a
+missing comma is the most common mistake.
+
+## Use a different LLM
+
+By default, PaperQA2 uses `gpt-4o-mini` for its internal reasoning.
+This is separate from Claude — Claude calls the tool, PaperQA2 does
+its own LLM calls internally to gather and synthesize evidence.
+
+To use a different model, add env vars to your Claude Desktop config:
+
+```json
+"env": {
+  "OPENAI_API_KEY": "sk-your-key-here",
+  "PQA_LLM": "gpt-4o",
+  "PQA_SUMMARY_LLM": "gpt-4o-mini"
+}
+```
+
+## All environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PAPER_DIRECTORY` | `~/Zotero/storage` | Folder containing your PDFs |
+| `OPENAI_API_KEY` | — | **Required** for default embeddings |
+| `PQA_LLM` | `gpt-4o-mini` | LLM for internal reasoning |
+| `PQA_SUMMARY_LLM` | `gpt-4o-mini` | LLM for summarizing chunks |
+| `PQA_EMBEDDING` | `text-embedding-3-small` | Embedding model |
+| `ANTHROPIC_API_KEY` | — | Only if using Claude as internal LLM |
+
+## Works with zotero-mcp
+
+This pairs well with [zotero-mcp](https://github.com/54yyyu/zotero-mcp):
+
+- **paperqa-mcp-server** — deep reading and synthesis across full paper text
+- **zotero-mcp** — browse your library, search metadata, read annotations
+
+Claude can cross-reference between them — for example, finding papers
+with PaperQA and then pulling up their Zotero metadata and annotations.
+PaperQA2's citations include Zotero storage keys (e.g. `ABC123DE` from
+`storage/ABC123DE/paper.pdf`) that Claude can use to look up items via
+zotero-mcp.
+
+## Index implementation notes
+
+`paperqa-mcp-server index` uses the same `_settings()` function as the MCP
+server, so the index it builds is exactly the one the server will look
+for. The PaperQA2 index directory name is a hash of the settings
+(embedding model, chunk size, paper directory path, etc.). The settings
+include:
+
+- **Multimodal OFF** — skip image extraction from PDFs (avoids a crash on
+  PDFs with CMYK images)
+- **Doc details OFF** — skip Crossref/Semantic Scholar metadata lookups
+  (avoids rate limits; Claude can get metadata from Zotero directly via
+  zotero-mcp)
+- **Concurrency 1** — index one file at a time to stay under OpenAI's
+  embedding rate limit
+
+> **Why not `pqa index`?** The `pqa` CLI constructs settings via pydantic's
+> `CliSettingsSource`, which produces different defaults than constructing
+> `Settings()` directly in Python (e.g. `chunk_chars` of 7000 vs 5000).
+> Different settings = different index hash = server can't find the index.
+> Always use `paperqa-mcp-server index` to build the index.
+
+## Install from GitHub (latest)
+
+To use the latest version from the main branch instead of PyPI:
+
+```json
+{
+  "mcpServers": {
+    "paperqa": {
+      "command": "/FULL/PATH/TO/uvx",
+      "args": ["--from", "git+https://github.com/menyoung/paperqa-mcp-server", "paperqa-mcp-server"],
+      "env": {
+        "OPENAI_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
+```
+
+To build the index from the latest main branch:
+
+```bash
+OPENAI_API_KEY=sk-your-key-here uvx --from git+https://github.com/menyoung/paperqa-mcp-server paperqa-mcp-server index
+```
+
+## Development
+
+If you want to contribute or modify the server locally:
+
+```bash
+git clone https://github.com/menyoung/paperqa-mcp-server.git
+cd paperqa-mcp-server
+uv sync
+uv run paperqa-mcp-server        # run the server
+uv run paperqa-mcp-server index  # build the index
+```

paperqa_mcp_server-0.1.0/README.md

@@ -0,0 +1,227 @@
+# paperqa-mcp-server
+
+Give Claude the ability to read, search, and synthesize across your
+entire PDF library. Built on [PaperQA2](https://github.com/Future-House/paper-qa).
+
+Point it at your Zotero storage folder (or any folder of PDFs) and ask
+Claude questions that require deep reading across multiple papers.
+
+## Quick start
+
+### 1. Install uv
+
+[uv](https://docs.astral.sh/uv/) is a Python package manager. If you don't
+have it yet:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+After installing, **restart your terminal** so `uv` is on your PATH.
+
+Verify it works:
+
+```bash
+uv --version
+```
+
+### 2. Get an OpenAI API key
+
+PaperQA2 uses OpenAI for embeddings and internal reasoning. Get a key at
+https://platform.openai.com/api-keys
+
+### 3. Test that it runs
+
+This downloads ~90 Python packages the first time — that's normal:
+
+```bash
+uvx paperqa-mcp-server --help 2>/dev/null; echo "OK if no Python errors above"
+```
+
+### 4. Add to Claude Desktop
+
+1. Open Claude Desktop
+2. Go to **Settings → Developer → Edit Config**
+3. This opens `claude_desktop_config.json`. Add a `paperqa` entry inside
+   `mcpServers` (create `mcpServers` if it doesn't exist):
+
+First, find your full path to `uvx`:
+
+```bash
+which uvx           # e.g. /Users/yourname/.local/bin/uvx
+```
+
+Then use that path in the config:
+
+```json
+{
+  "mcpServers": {
+    "paperqa": {
+      "command": "/FULL/PATH/TO/uvx",
+      "args": ["paperqa-mcp-server"],
+      "env": {
+        "OPENAI_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
+```
+
+Replace the two placeholders:
+- `/FULL/PATH/TO/uvx` — paste the output of `which uvx`
+- `sk-your-key-here` — your OpenAI API key from step 2
+
+If your PDFs are somewhere other than `~/Zotero/storage`, add a
+`PAPER_DIRECTORY` entry to `env`:
+
+```json
+"env": {
+  "OPENAI_API_KEY": "sk-your-key-here",
+  "PAPER_DIRECTORY": "/full/path/to/your/pdfs"
+}
+```
+
+4. **Quit Claude Desktop completely** (Cmd+Q, not just close the window)
+   and reopen it
+5. You should see a hammer icon — click it and `paper_qa` should be listed
+
+### 5. Pre-build the index
+
+Before Claude can search your papers, the server needs to build a search
+index. This reads each PDF, splits it into chunks, and sends the chunks
+to OpenAI's embedding API. With hundreds of papers this takes a while
+and costs a few dollars in API calls.
+
+If you have more than 10 unindexed papers, the server will refuse to
+answer queries and tell you to run this step first. A few new papers
+will be indexed automatically when you query.
+
+```bash
+OPENAI_API_KEY=sk-your-key-here uvx paperqa-mcp-server index
+```
+
+**If this crashes** with a rate limit error, just re-run the same command.
+It picks up where it left off — each run indexes more files. With a large
+library (500+ papers) you may need to run it a few times.
+
+After that, the index is cached at `~/.pqa/indexes/`. Only new or changed
+files get re-processed on subsequent runs.
+
+## Troubleshooting
+
+**"Server disconnected" in Claude Desktop**
+
+Claude Desktop has a short startup timeout. If `uv` needs to download
+packages on first launch, it will time out. Fix: run `uvx paperqa-mcp-server`
+once from the terminal first so packages are cached.
+
+**"Index incomplete" when querying**
+
+The server checks the index before each query. If too many papers are
+unindexed, it returns a diagnostic message instead of trying (and
+failing) to index them all on the fly. Fix: run the index command in
+step 5.
+
+**Hammer icon doesn't appear**
+
+Make sure you quit Claude Desktop completely (Cmd+Q) and reopened it.
+Check for JSON syntax errors in `claude_desktop_config.json` — a
+missing comma is the most common mistake.
+
+## Use a different LLM
+
+By default, PaperQA2 uses `gpt-4o-mini` for its internal reasoning.
+This is separate from Claude — Claude calls the tool, PaperQA2 does
+its own LLM calls internally to gather and synthesize evidence.
+
+To use a different model, add env vars to your Claude Desktop config:
+
+```json
+"env": {
+  "OPENAI_API_KEY": "sk-your-key-here",
+  "PQA_LLM": "gpt-4o",
+  "PQA_SUMMARY_LLM": "gpt-4o-mini"
+}
+```
+
+## All environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PAPER_DIRECTORY` | `~/Zotero/storage` | Folder containing your PDFs |
+| `OPENAI_API_KEY` | — | **Required** for default embeddings |
+| `PQA_LLM` | `gpt-4o-mini` | LLM for internal reasoning |
+| `PQA_SUMMARY_LLM` | `gpt-4o-mini` | LLM for summarizing chunks |
+| `PQA_EMBEDDING` | `text-embedding-3-small` | Embedding model |
+| `ANTHROPIC_API_KEY` | — | Only if using Claude as internal LLM |
+
+## Works with zotero-mcp
+
+This pairs well with [zotero-mcp](https://github.com/54yyyu/zotero-mcp):
+
+- **paperqa-mcp-server** — deep reading and synthesis across full paper text
+- **zotero-mcp** — browse your library, search metadata, read annotations
+
+Claude can cross-reference between them — for example, finding papers
+with PaperQA and then pulling up their Zotero metadata and annotations.
+PaperQA2's citations include Zotero storage keys (e.g. `ABC123DE` from
+`storage/ABC123DE/paper.pdf`) that Claude can use to look up items via
+zotero-mcp.
+
+## Index implementation notes
+
+`paperqa-mcp-server index` uses the same `_settings()` function as the MCP
+server, so the index it builds is exactly the one the server will look
+for. The PaperQA2 index directory name is a hash of the settings
+(embedding model, chunk size, paper directory path, etc.). The settings
+include:
+
+- **Multimodal OFF** — skip image extraction from PDFs (avoids a crash on
+  PDFs with CMYK images)
+- **Doc details OFF** — skip Crossref/Semantic Scholar metadata lookups
+  (avoids rate limits; Claude can get metadata from Zotero directly via
+  zotero-mcp)
+- **Concurrency 1** — index one file at a time to stay under OpenAI's
+  embedding rate limit
+
+> **Why not `pqa index`?** The `pqa` CLI constructs settings via pydantic's
+> `CliSettingsSource`, which produces different defaults than constructing
+> `Settings()` directly in Python (e.g. `chunk_chars` of 7000 vs 5000).
+> Different settings = different index hash = server can't find the index.
+> Always use `paperqa-mcp-server index` to build the index.
+
+## Install from GitHub (latest)
+
+To use the latest version from the main branch instead of PyPI:
+
+```json
+{
+  "mcpServers": {
+    "paperqa": {
+      "command": "/FULL/PATH/TO/uvx",
+      "args": ["--from", "git+https://github.com/menyoung/paperqa-mcp-server", "paperqa-mcp-server"],
+      "env": {
+        "OPENAI_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
+```
+
+To build the index from the latest main branch:
+
+```bash
+OPENAI_API_KEY=sk-your-key-here uvx --from git+https://github.com/menyoung/paperqa-mcp-server paperqa-mcp-server index
+```
+
+## Development
+
+If you want to contribute or modify the server locally:
+
+```bash
+git clone https://github.com/menyoung/paperqa-mcp-server.git
+cd paperqa-mcp-server
+uv sync
+uv run paperqa-mcp-server        # run the server
+uv run paperqa-mcp-server index  # build the index
+```

paperqa_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "paperqa-mcp-server"
+version = "0.1.0"
+description = "MCP server exposing PaperQA2 for deep synthesis across scientific papers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["mcp", "paperqa", "scientific-literature", "research", "llm", "rag"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "paper-qa>=2026.2,<2026.3",
+    "mcp[cli]>=1.2.0",
+    "pillow",
+]
+
+[project.scripts]
+paperqa-mcp-server = "paperqa_mcp_server:main"
+
+[project.urls]
+Repository = "https://github.com/menyoung/paperqa-mcp-server"
+Issues = "https://github.com/menyoung/paperqa-mcp-server/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/paperqa_mcp_server"]

paperqa_mcp_server-0.1.0/src/paperqa_mcp_server/__init__.py

@@ -0,0 +1,180 @@
+"""MCP server exposing PaperQA2 for deep synthesis across scientific papers."""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import pickle
+import zlib
+
+from mcp.server.fastmcp import FastMCP
+from paperqa import Settings, agent_query
+
+mcp = FastMCP("paperqa")
+
+
+def _settings() -> Settings:
+    return Settings(
+        llm=os.environ.get("PQA_LLM", "gpt-4o-mini"),
+        summary_llm=os.environ.get("PQA_SUMMARY_LLM", "gpt-4o-mini"),
+        embedding=os.environ.get("PQA_EMBEDDING", "text-embedding-3-small"),
+        temperature=0.1,
+        parsing={"multimodal": "OFF", "use_doc_details": False},
+        answer={"evidence_k": 15, "answer_max_sources": 10},
+        agent={
+            "index": {
+                "paper_directory": os.environ.get(
+                    "PAPER_DIRECTORY",
+                    os.path.expanduser("~/Zotero/storage"),
+                ),
+                "concurrency": 1,
+            }
+        },
+    )
+
+
+_UNINDEXED_THRESHOLD = 10
+
+
+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 5."
+        )
+    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 5."
+            )
+
+    return {
+        "indexed": indexed,
+        "errored": errored,
+        "unindexed": unindexed,
+        "total": total,
+        "ready": ready,
+        "message": message,
+    }
+
+
+@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)
+
+
+@mcp.tool()
+async def paper_qa(query: str) -> str:
+    """Search and synthesize across all papers in the library.
+
+    Use this for questions that require deep reading and synthesis
+    across multiple scientific papers — e.g. "What methods have been
+    used to recycle lithium from spent batteries?" or "Compare the
+    thermal stability of PEEK vs PTFE in the literature."
+
+    Returns a detailed answer with inline citations. Each citation
+    includes a file path containing an 8-character Zotero storage key
+    (e.g. ABC123DE from storage/ABC123DE/paper.pdf). You can use these
+    keys with zotero-mcp tools to look up the full bibliographic record,
+    read annotations, or find related items.
+
+    Not for quick metadata lookups or library browsing — use Zotero
+    tools for that.
+
+    If this tool returns "Index incomplete", the paper index has not
+    been fully built yet. Tell the user to run the index build command
+    from the terminal (see the paperqa-mcp-server README, step 5).
+    Do not retry the query — it will give the same result until the
+    index is built.
+
+    This tool can take 30–90 seconds to respond when working normally.
+    """
+    settings = _settings()
+    status = _index_status(settings)
+    if not status["ready"]:
+        return f"Index incomplete: {status['message']}"
+
+    try:
+        response = await agent_query(query=query, settings=settings)
+    except Exception as e:
+        return f"PaperQA error: {e}"
+    if not response.session.formatted_answer:
+        return f"PaperQA could not answer (status: {response.status})."
+    return response.session.formatted_answer
+
+
+def _build_index() -> None:
+    """Build the search index using the same settings as the MCP server."""
+    import asyncio
+
+    from paperqa.agents.search import get_directory_index
+
+    settings = _settings()
+    print(f"Building index: {settings.get_index_name()}")
+    print(f"Paper directory: {settings.agent.index.paper_directory}")
+    asyncio.run(get_directory_index(settings=settings))
+    print("Done.")
+
+
+def main():
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == "index":
+        _build_index()
+    else:
+        mcp.run(transport="stdio")