LLM Agent <--MCP--> PubMed MCP Server <--API--> PubMed / PMC / Unpaywall

# npm 全局安装
npm install -g mcp-pubmed-llm-server

# 或从源码构建
git clone git@github.com:PancrePal-xiaoyibao/mcp-pubmed-server-pancrpal.git
cd mcp-pubmed-server-pancrpal
npm install && npm run build

cp .env.example .env

PUBMED_API_KEY=你的NCBI_API密钥    # 可选，https://www.ncbi.nlm.nih.gov/account/settings/
PUBMED_EMAIL=你的邮箱               # 可选（建议填写）
ABSTRACT_MODE=quick                 # quick(1500字符) | deep(6000字符)
FULLTEXT_MODE=disabled              # disabled | enabled | auto

# npm 包
mcp-pubmed-llm-server
# 或
npx mcp-pubmed-llm-server

# 源码开发
npm run dev

# 源码生产
npm run build && npm start

npm start
# 或
node dist/index.js --mode=stdio

npm run start:http
# 或
node dist/index.js --mode=streamableHttp

cd docker
cp .env.example .env   # 编辑填入配置
docker compose up -d --build

curl http://localhost:8745/health
# {"status":"ok","mode":"streamableHttp","sessions":0}

{
  "mcpServers": {
    "pubmed": {
      "command": "npx",
      "args": ["-y", "mcp-pubmed-llm-server"],
      "env": {
        "PUBMED_API_KEY": "你的API密钥（可选）",
        "PUBMED_EMAIL": "你的邮箱（可选）",
        "ABSTRACT_MODE": "deep",
        "FULLTEXT_MODE": "enabled"
      }
    }
  }
}

{
  "status": "success",
  "data": { ... },
  "metadata": {
    "tool": "pubmed_search",
    "executionMs": 1234,
    "timestamp": "2025-01-01T00:00:00.000Z",
    "pagination": { "total": 500, "returned": 20, "hasMore": true }
  },
  "suggestions": [
    {
      "tool": "pubmed_get_details",
      "reason": "Get full metadata for specific articles of interest.",
      "parameters": { "pmids": ["12345678"] }
    }
  ]
}

{
  "keys": [
    { "api_key": "KEY_1", "email": "user1@example.com" },
    { "api_key": "KEY_2", "email": "user2@example.com" }
  ],
  "strategy": "round-robin"
}

src/
├── index.ts                  # 入口点
├── config.ts                 # 配置常量 + 环境变量
├── server.ts                 # MCP Server 编排器
├── types/                    # TypeScript 类型定义
│   ├── article.ts            # Article, SearchResult, OAInfo
│   ├── responses.ts          # AgentResponse<T>, makeResponse/makeError
│   └── index.ts
├── api/
│   ├── pubmed-client.ts      # PubMed EUtilities 客户端
│   └── key-pool.ts           # API Key 号池（轮询/主备/随机）
├── cache/
│   ├── memory-cache.ts       # 内存 LRU 缓存（5 分钟，100 条上限）
│   └── file-cache.ts         # 文件持久化缓存（30 天过期）
├── services/
│   ├── fulltext.ts           # OA 检测 + PDF 下载
│   └── system.ts             # 系统环境检测
├── tools/
│   ├── definitions.ts        # MCP 工具 Schema（8 个工具）
│   └── handlers.ts           # 工具路由 + 处理逻辑
├── transport/
│   ├── stdio.ts              # stdio 传输
│   └── streamable-http.ts    # HTTP 传输（Express）
└── utils/
    └── formatter.ts          # 文章格式化（compact/standard/detailed）