paper_research_helper/
├── main.py                    # CLI entry point (serve / ingest / ask)
├── requirements.txt
├── .env.example
├── docs/
│   ├── architecture.md        # System design & data flow
│   └── getting_started.md    # Step-by-step setup guide
└── src/
    ├── adapters/              # External service connectors
    │   ├── arxiv.py           #   arXiv API
    │   ├── semantic_scholar.py #  Semantic Scholar API
    │   └── pdf.py             #   PDF text extraction
    ├── tools/                 # LangChain tools used by agents
    │   ├── search.py          #   Paper search tool
    │   ├── retrieval.py       #   Vector store retrieval tool
    │   └── summarize.py       #   LLM summarization tool
    ├── agents/                # LangGraph agent nodes
    │   ├── research_agent.py  #   Discovers & summarises papers
    │   └── qa_agent.py        #   RAG question-answering agent
    ├── graphs/                # LangGraph state graphs
    │   └── research_graph.py  #   Full research pipeline graph
    ├── pipeline/              # Ingestion orchestration
    │   └── ingestion.py       #   Fetch → chunk → embed → index
    └── mcp/                   # MCP server
        └── server.py          #   FastMCP server with 3 tools

uv sync           # creates .venv and installs all dependencies

cp .env.example .env
# edit .env and set OPENAI_API_KEY at minimum

python main.py ingest --arxiv-id 2301.07041   # Attention Is All You Need (example)

python main.py ask "What problem does the transformer architecture solve?"

python main.py serve

{
  "mcpServers": {
    "paper-research-helper": {
      "command": "python",
      "args": ["main.py", "serve"],
      "cwd": "/path/to/paper_research_helper"
    }
  }
}