学术研究MCP服务器

graph TD
    Client["MCP Client<br/>(Claude Desktop / Claude Code / IDE)"]
    Server["My Research MCP Server<br/>53 Tools (FastMCP)"]

    Client -->|"MCP Protocol<br/>(stdio / SSE)"| Server

    Server --> Academic["Academic APIs<br/>arXiv, Semantic Scholar,<br/>OpenAlex, CORE, OSF,<br/>Crossref, Unpaywall"]
    Server --> Biomed["Biomedical & Citations<br/>Europe PMC, OpenCitations,<br/>ClinicalTrials.gov,<br/>retraction checks"]
    Server --> Institutional["Institutional Repos<br/>MIT, Harvard,<br/>Cornell, Penn"]
    Server --> Cloud["Cloud Docs<br/>AWS, GCP,<br/>MS Learn"]
    Server --> IAM["IAM Docs<br/>Google PSE / Vertex /<br/>Brave / SerpAPI"]
    Server --> GitHub["GitHub API<br/>Repos, Code,<br/>READMEs"]

graph TD
    subgraph Server["My Research MCP Server"]
        FastMCP["FastMCP Layer<br/>53 @mcp.tool() functions"]

        FastMCP --> HTTP["HTTP Clients<br/>requests + rate limiters<br/>(3s arXiv, 1s S2, 6.5s CORE)"]
        FastMCP --> PaperIndex["Paper Index<br/>SQLite FTS5 + BM25<br/>papers, chunks, chunks_fts"]
        FastMCP --> DuckDB["DuckDB Engine<br/>Analytics SQL over<br/>SQLite + datasets<br/>(Parquet, CSV, JSON)"]
        FastMCP --> Embed["fastembed Embeddings<br/>ONNX model (BAAI/bge-small-en)<br/>HNSW cosine search<br/>in DuckDB"]
    end

    subgraph FS["Filesystem"]
        PDFs["~/arxiv-papers/<br/>(PDFs + SQLite DB)"]
        Datasets["~/research-datasets/<br/>(Parquet/CSV/JSON)"]
    end

    PaperIndex --> PDFs
    DuckDB --> Datasets
    Embed --> PDFs

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant A as External API
    participant F as Filesystem

    C->>S: search_arxiv()
    S->>A: GET /api/query
    A-->>S: Atom XML response
    S-->>C: JSON results

    C->>S: download_paper()
    S->>A: GET /pdf/{id}
    A-->>S: PDF bytes (stream)
    S->>F: Write PDF
    S->>F: PyMuPDF extract
    F-->>S: pages[]
    S->>S: chunk_pages()
    S->>F: SQLite upsert
    S-->>C: JSON (indexed)

    C->>S: query_papers()
    S->>F: FTS5 MATCH query
    F-->>S: BM25-ranked rows
    S-->>C: JSON results

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant E as fastembed
    participant D as DuckDB

    C->>S: embed_chunks()
    S->>D: fetch unembedded
    D-->>S: chunk texts
    S->>E: encode(texts)
    E-->>S: float[][] vectors
    S->>D: INSERT embeddings
    S-->>C: JSON (count)

    C->>S: semantic_search()
    S->>E: encode(query)
    E-->>S: query vector
    S->>D: cosine similarity
    D-->>S: ranked chunks
    S-->>C: JSON results

pip install "mcp<2" requests pymupdf duckdb google-auth fastembed

pip install -e .        # production
pip install -e ".[dev]" # with pytest + ruff

python server.py                              # stdio (Claude Desktop / Claude Code)
python server.py --transport sse --port 8080  # HTTP/SSE

{
  "mcpServers": {
    "my-research": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "ARXIV_DOWNLOAD_DIR": "~/arxiv-papers",
        "UNPAYWALL_EMAIL": "you@example.com",
        "CORE_API_KEY": "your-core-api-key",
        "GOOGLE_DEVKNOWLEDGE_API_KEY": "your-google-api-key",
        "GOOGLE_PSE_CX": "your-pse-cx-id",
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

claude mcp add my-research python /absolute/path/to/server.py

ti:transformer AND cat:cs.CL
au:vaswani AND ti:attention
(cat:cs.AI OR cat:cs.CL) AND all:large language model

gradient descent convergence            # implicit AND
"self-supervised learning"              # exact phrase
self-attention                          # hyphens and punctuation are handled for you
attention AND mechanism                 # explicit AND (operators must be upper-case)
transformer OR attention                # OR
NEAR(policy gradient, 10)              # proximity (within 10 tokens)
reinforc*                               # prefix matching

You: Search for papers on "policy-as-code" across multiple sources
  -> search_arxiv("all:policy-as-code", category="cs.SE")
  -> search_semantic_scholar("policy-as-code", fields_of_study="Computer Science")
  -> search_openalex("policy-as-code")

You: Download the top result and that DOI from the Crossref hit
  -> download_paper("2401.xxxxx")              # arXiv PDF, auto-indexed
  -> download_paper_by_doi("10.1145/3649835")  # OA PDF via Unpaywall

You: What do these papers say about OPA Rego validation?
  -> query_papers("OPA Rego validation")
  Returns: matching text passages with page numbers and headings

You: Search the OPA docs for Rego policy testing
  -> search_iam_docs("Rego policy testing")

You: Check how AWS and Azure handle policy-as-code
  -> search_aws_docs("policy as code CloudFormation Guard")
  -> search_microsoft_docs("Azure Policy definition")

You: Run some analytics on my indexed papers
  -> analytics_sql("SELECT SUBSTR(published,1,4) AS year, COUNT(*) AS n
                     FROM papers_db.papers GROUP BY 1 ORDER BY 1 DESC")

You: Find semantically similar passages to "access control policy evaluation"
  -> embed_chunks()
  -> semantic_search("access control policy evaluation")

python -c "from fastembed import TextEmbedding; TextEmbedding('BAAI/bge-small-en-v1.5')"

pip install --only-binary cryptography "cryptography<46"
pip install -e ".[dev]"

search_arxiv("attention mechanism")  -> download_paper("2301.12345")

make dev      # Install with dev deps
make test     # pytest -v --tb=short
make lint     # ruff check .
make format   # ruff format .