文档问答服务器

flowchart TD
    subgraph ingestion ["Ingestion Pipeline (run once via ingest.py)"]
        PDFs["data/pdfs/*.pdf"] --> Parser["parser.py<br/>PyMuPDF"]
        Parser -->|"pages with metadata"| Chunker["chunker.py<br/>sliding window"]
        Chunker -->|"overlapping chunks"| Embedder["embedder.py<br/>all-MiniLM-L6-v2"]
        Embedder --> ChromaDB["data/chroma_db/"]
    end

    subgraph server ["MCP Server (always on via mcp_server.py)"]
        Client["Claude / MCP Client"] -->|"query_documents(question)"| Server["server.py"]
        Client -->|"list_documents()"| Server
        Server --> Retriever["retriever.py<br/>cosine search"]
        Retriever --> ChromaDB2["data/chroma_db/"]
        ChromaDB2 -->|"top-k chunks"| LLM["llm.py<br/>Gemini 2.5 Flash"]
        LLM --> Server
        Server -->|"JSON: answer + sources"| Client
    end

    ChromaDB -.->|"persisted index"| ChromaDB2

# Clone and enter the project
cd nexla-mcp-doc-qa

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set your API key
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# Run ingestion (one-time, indexes all PDFs)
python3 ingest.py

# Start the MCP server
python3 mcp_server.py

nexla-mcp-doc-qa/
├── mcp_server.py                # Entry point: runs the MCP server
├── ingest.py                    # Entry point: runs the ingestion pipeline
├── src/
│   ├── config.py                # All constants: paths, models, chunk params
│   ├── server.py                # FastMCP app + tool handlers
│   ├── ingestion/               # Offline — run once
│   │   ├── parser.py            # PyMuPDF: PDF → [{text, doc_name, page}]
│   │   ├── chunker.py           # Sliding window: pages → overlapping chunks
│   │   ├── embedder.py          # all-MiniLM-L6-v2 → ChromaDB storage
│   │   └── pipeline.py          # Orchestrator: parser → chunker → embedder
│   └── core/                    # Online — used at query time
│       ├── retriever.py         # Embed question → ChromaDB cosine search
│       └── llm.py               # Build prompt → Gemini 2.5 Flash → parse JSON
├── data/
│   ├── pdfs/                    # Input PDFs (5 AI/ML research papers)
│   └── chroma_db/               # Vector index (auto-created, gitignored)
├── requirements.txt
├── .env.example
└── .gitignore

{ "question": "What is the attention mechanism?" }

{
  "answer": "The attention mechanism allows the model to jointly attend to information from different representation subspaces at different positions. The Transformer uses multi-head attention, where queries, keys, and values are linearly projected h times, attention is applied in parallel, and the results are concatenated.",
  "sources": [
    { "doc_name": "attention_is_all_you_need.pdf", "page": 3 },
    { "doc_name": "attention_is_all_you_need.pdf", "page": 5 }
  ],
  "confidence": "high"
}

[
  { "doc_name": "ai_index_report_2024.pdf", "pages": 36, "chunks": 58 },
  { "doc_name": "attention_is_all_you_need.pdf", "pages": 15, "chunks": 20 },
  { "doc_name": "bert_paper.pdf", "pages": 16, "chunks": 31 },
  { "doc_name": "gpt2_paper.pdf", "pages": 24, "chunks": 43 },
  { "doc_name": "rag_paper.pdf", "pages": 19, "chunks": 29 }
]

{
  "answer": "The Transformer is a model architecture that eschews recurrence and instead relies entirely on an attention mechanism to draw global dependencies between input and output. It uses stacked self-attention and point-wise, fully connected layers for both the encoder and decoder.",
  "sources": [
    { "doc_name": "attention_is_all_you_need.pdf", "page": 3 },
    { "doc_name": "attention_is_all_you_need.pdf", "page": 5 }
  ],
  "confidence": "high"
}

{
  "answer": "BERT uses a masked language model (MLM) objective, where random tokens are masked and the model predicts them using bidirectional context. GPT-2 uses a standard left-to-right language model objective, predicting the next token given all previous tokens. BERT is bidirectional while GPT-2 is unidirectional.",
  "sources": [
    { "doc_name": "bert_paper.pdf", "page": 3 },
    { "doc_name": "bert_paper.pdf", "page": 13 },
    { "doc_name": "gpt2_paper.pdf", "page": 3 }
  ],
  "confidence": "high"
}

{
  "answer": "The answer to this question was not found in the indexed documents.",
  "sources": [],
  "confidence": "none"
}

{
  "mcpServers": {
    "document-qa": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/absolute/path/to/nexla-mcp-doc-qa"
    }
  }
}

# Install MCP Inspector
npx @modelcontextprotocol/inspector python3 mcp_server.py

# Delete the vector index and re-ingest from scratch
rm -rf data/chroma_db/
python3 ingest.py
python3 mcp_server.py

models/text-embedding-004 is not found for API version v1beta

npx @modelcontextprotocol/inspector python3 mcp_server.py