KnowS MCP Server

English | 中文

中文

概述

一个与KnowS证据和问答API集成的模型上下文协议（MCP）服务器。它使大型语言模型能够使用两个核心工作流程：

• 场景1：患者问答和信息支持

  • 搜索临床证据并检索question_id + evidences
  • 生成针对患者和同伴支持社区定制的临床/研究/科普答案

• 场景2：学术检索和深度研究

  • 获取单篇论文、指南和会议摘要的结构化详细信息
  • 运行自动标记和查询历史记录，以支持基于证据的研究工作流程

特性

• ✅ 使用stdio传输的MCP服务器
• ✅ 带有x-api-key认证的KnowS HTTP客户端
• ✅ 面向患者的问答工具和面向研究的证据工具之间的清晰分离
• ✅ 严格的TypeScript类型
• ✅ 基于Jest的单元/集成测试钩子（待实现）

📖 使用指南

重要提示：为了有效使用这些工具，请参阅prompt.md以获取详细的工具调用策略和工作流程。

提示指南包括：

• 不同场景下的工具调用链（患者问答、学术研究等）
• 如何正确结合knows_ai_search → knows_answer
• 最佳实践和常见陷阱

技术栈

• Node.js (ES Modules)
• TypeScript
• @modelcontextprotocol/sdk
• Axios
• dotenv

安装

选项1：从npm安装（推荐）

npm install knows-mcp-server

选项2：从源代码构建

从项目根目录：

npm install

构建：

npm run build

运行（构建后）：

npm start

开发（监视）：

npm run dev

配置

服务器从环境变量中读取配置。在本地开发期间，可以通过.env文件（由dotenv加载）进行管理，在MCP部署中应在其MCP配置中设置（例如Claude Desktop的env块）。

支持的变量：

• KNOWS_API_KEY（必需）：您的KnowS x-api-key
• KNOWS_API_BASE_URL（必需）：API基础URL，例如https://dev-api.nullht.com或https://api.nullht.com
• LOG_LEVEL（可选）：日志级别，例如info、debug、error（默认为info）
• DEFAULT_DATA_SCOPE（可选）：knows_ai_search的默认证据类型，例如"GUIDE,PAPER"（如果未设置，则默认为所有类型）

示例.env（本地开发）

# Test environment

KNOWS_API_KEY=your_test_api_key_here

KNOWS_API_BASE_URL=https://dev-api.nullht.com

LOG_LEVEL=info



# Default evidence search scope (optional, for speed)

# If not set, defaults to all: PAPER,PAPER_CN,GUIDE,MEETING

# DEFAULT_DATA_SCOPE=GUIDE,PAPER



# Production example (comment out test values and enable these when needed)

# KNOWS_API_KEY=your_prod_api_key_here

# KNOWS_API_BASE_URL=https://api.nullht.com

示例MCP配置（Claude Desktop）

在claude_desktop_config.json（或等效文件）中：

{

  "mcpServers": {

    "knows-mcp": {

      "command": "npx",

      "args": ["-y", "knows-mcp-server"],

      "env": {

        "KNOWS_API_KEY": "your_api_key_here",

        "KNOWS_API_BASE_URL": "https://dev-api.nullht.com",

        "DEFAULT_DATA_SCOPE": "GUIDE,PAPER",

        "LOG_LEVEL": "info"

      }

    }

  }

}

对于生产环境，请相应地更改环境值，例如：

• 将KNOWS_API_BASE_URL设置为https://api.nullht.com
• 使用您的生产KNOWS_API_KEY（不要在生产环境中重用测试密钥）

注意：在本地开发中，.env会自动加载；在部署时，MCP主机应通过其自己的配置传递环境变量。

MCP工具

1. knows_ai_search

目的：问题→证据搜索，返回question_id和证据列表。

• 参数：
  • question（字符串，必需）：用户问题文本
  • data_scope（字符串数组，可选）：证据类型，可以是"PAPER" | "PAPER_CN" | "GUIDE" | "MEETING"中的任意组合。如果未提供，则使用配置中的DEFAULT_DATA_SCOPE或默认为所有类型。
• 后端API：POST /knows/ai_search

2. knows_answer

目的：为给定的question_id生成基于场景的答案。

• 参数：
  • question_id（字符串，必需）
  • answer_type（字符串，必需）："CLINICAL" | "RESEARCH" | "POPULAR_SCIENCE"之一
• 后端API：POST /knows/answer
• 使用提示：使用设计文档中描述的路由策略（关键词：科普/研究/临床）自动选择answer_type。

3. knows_evidence_summary

目的：获取单个证据项的AI生成摘要。

• 参数：
  • evidence_id（字符串，必需）- 后端 API: POST /knows/evidence/summary

4. knows_evidence_highlight

目的: 获取给定证据的高亮原始文本片段（用于引用/上下文）。

• 参数:
  • evidence_id (字符串, 必填)
• 后端 API: POST /knows/evidence/highlight

5. knows_get_paper_en

目的: 获取英文论文的结构化详细信息。

• 参数:
  • evidence_id (字符串, 必填)
  • translate_to_chinese (布尔值, 可选): 是否翻译标题/摘要
• 后端 API: POST /knows/evidence/get_paper_en

6. knows_get_paper_cn

目的: 获取中文论文的结构化详细信息。

• 参数:
  • evidence_id (字符串, 必填)
• 后端 API: POST /knows/evidence/get_paper_cn

7. knows_get_guide

目的: 获取指南的详细信息。

• 参数:
  • evidence_id (字符串, 必填)
  • translate_to_chinese (布尔值, 可选)
• 后端 API: POST /knows/evidence/get_guide

8. knows_get_meeting

目的: 获取会议摘要的详细信息。

• 参数:
  • evidence_id (字符串, 必填)
  • translate_to_chinese (布尔值, 可选)
• 后端 API: POST /knows/evidence/get_meeting

9. knows_auto_tagging

目的: 对研究元数据进行自动标记（疾病、人群、结果等）。

• 参数:
  • content (字符串, 可选): 原始文本
  • evidence_id (字符串, 可选): 证据ID（用于全文）
  • tagging_type (字符串, 必填): 在KnowS文档中定义的类型之一
• 后端 API: POST /knows/auto_tagging

10. knows_list_question

目的: 获取用户问题的历史记录。

• 参数:
  • from_time (数字, 可选): 时间戳 (毫秒)
  • to_time (数字, 可选): 时间戳 (毫秒)
  • page (数字, 可选)
  • page_size (数字, 可选)
• 后端 API: POST /knows/list_question

11. knows_list_interpretation

目的: 获取单个证据解释的历史记录。

• 参数:
  • from_time (数字, 可选)
  • to_time (数字, 可选)
  • page (数字, 可选)
  • page_size (数字, 可选)
• 后端 API: POST /knows/list_interpretion

测试

建议的npm脚本（已在package.json中）:

• npm test: 运行Jest单元/集成测试（待实现）
• 单元测试应关注：
  • config (环境处理)
  • knowsClient (HTTP错误处理、响应映射)
  • MCP工具 (参数验证与映射)
• 集成测试应模拟ai_search → evidence_summary → answer流程。

中文

项目概述

这是一个用于对接 KnowS 问答与证据 API 的 Model Context Protocol (MCP) 服务器，使大模型能够调用 KnowS 的两大类核心服务场景：

• 场景 1：患者问答和信息求助

  • 检索临床证据，获取 question_id + evidences
  • 生成面向患者 / 专业病友的场景化答案（临床 / 学术 / 科普）

• 场景 2：学术检索和深度研究

  • 查询单篇文献、指南、会议等的结构化详情
  • 进行自动标签、历史记录查询等学术研究工作流

功能特性

• ✅ 基于 stdio 传输的 MCP 服务器
• ✅ 使用 x-api-key 认证的 KnowS HTTP 客户端
• ✅ 清晰区分 问答/场景工具 和 文献/证据工具
• ✅ TypeScript 强类型
• ✅ 预留 Jest 测试脚本

📖 使用指南

重要提示：为了正确使用这些工具，请参考 prompt.md 了解详细的工具调用策略和工作流。

该指南包含：

• 不同场景下的工具调用链路（患者问答、学术研究等）
• 如何正确组合 knows_ai_search → knows_answer
• 最佳实践与常见陷阱

环境变量与 .env

本项目通过环境变量管理配置：

• 本地开发：
  • 使用 .env 文件（由 dotenv 自动加载）
• 部署到 MCP 客户端：- 在 MCP 配置（如 Claude Desktop 的 mcpServers.*.env）里设置相同的环境变量

支持的变量：

• KNOWS_API_KEY：KnowS 提供的 x-api-key（必填）
• KNOWS_API_BASE_URL：KnowS API 基础地址，如 https://dev-api.nullht.com 或 https://api.nullht.com（必填）
• LOG_LEVEL：日志级别，可选，默认 info
• DEFAULT_DATA_SCOPE：knows_ai_search 的默认证据类型，如 "GUIDE,PAPER"（可选，不设置则默认全部类型）

示例 .env：

plaintext

# 测试环境（本地开发）
KNOWS_API_KEY=你的测试环境_api_key
KNOWS_API_BASE_URL=https://dev-api.nullht.com
LOG_LEVEL=info

# 默认证据搜索范围（可选，提升速度）
# 不设置则默认全开：PAPER,PAPER_CN,GUIDE,MEETING
# DEFAULT_DATA_SCOPE=GUIDE,PAPER

# 如切换生产环境，可改为：
# KNOWS_API_KEY=你的生产环境_api_key
# KNOWS_API_BASE_URL=https://api.nullht.com

示例 MCP 配置（Claude Desktop）：

plaintext

{
  "mcpServers": {
    "knows-mcp": {
      "command": "npx",
      "args": ["-y", "knows-mcp-server"],
      "env": {
        "KNOWS_API_KEY": "你的_api_key",
        "KNOWS_API_BASE_URL": "https://dev-api.nullht.com",
        "DEFAULT_DATA_SCOPE": "GUIDE,PAPER",
        "LOG_LEVEL": "info"
      }
    }
  }
}

生产环境：请将环境变量值替换为生产环境对应的值，例如：

• 将 KNOWS_API_BASE_URL 改为 https://api.nullht.com
• 使用你的生产环境 KNOWS_API_KEY（请勿复用测试环境的 key）

注意：本地开发使用 .env；正式部署时，由 MCP 宿主（例如 Claude Desktop）通过 env 字段注入同名环境变量即可，无需再使用 .env。

MCP 工具一览（按场景）

一、问答 / 场景类工具（面向患者 & 专业病友）

• knows_ai_search：提问 → 检索证据列表

  • 参数：question、data_scope[]（可选，PAPER / PAPER_CN / GUIDE / MEETING）
  • 作用：返回 question_id + evidences，后续可用于 knows_answer 或文献工具。
  • 优先级：运行时参数 > 环境变量 DEFAULT_DATA_SCOPE > 默认全开

• knows_answer：基于 question_id 生成场景化答案

  • 参数：question_id，answer_type（单个值：CLINICAL / RESEARCH / POPULAR_SCIENCE）
  • 场景：
    • 普通患者：多用 POPULAR_SCIENCE
    • 专业病友-研究向：多用 RESEARCH
    • 专业病友-临床决策向：多用 CLINICAL + RESEARCH
  • LLM 可根据中文关键词（“科普”“研究”“临床”等）和提问风格自动选择 answer_type。

二、文献 / 证据类工具（面向专业使用者）

• knows_evidence_summary：单篇证据 AI 概要
• knows_evidence_highlight：原文高亮片段（用于引用和溯源）
• knows_get_paper_en / knows_get_paper_cn：英/中文文献详情
• knows_get_guide：指南详情
• knows_get_meeting：会议摘要详情
• knows_auto_tagging：自动标签与结构化要素抽取
• knows_list_question：历史提问列表
• knows_list_interpretation：历史单篇解读列表

典型学术工作流示例：

1. 通过 knows_ai_search 找到相关 evidences，并选出若干 evidence_id
2. 用 knows_evidence_summary + knows_evidence_highlight 理解核心结论与原文段落
3. 用 knows_get_paper_en/cn / knows_get_guide / knows_get_meeting 获取详细结构化信息
4. 若需结构化要素（如研究类型、样本量、终点），用 knows_auto_tagging
5. 最后如需要面向患者/病友的总结，可用 knows_answer 生成相应风格的答案

许可证

MIT

贡献

欢迎贡献！请提交 issue 或 pull request。

特别感谢小胰宝和 小x宝社区的❤️贡献与付出，用爱心与人工智能为癌症/罕见病患者及其家庭提供支持！

如你后续决定固定包名、补充更多 MCP 工具或测试用例，可以在本 README 的基础上增量更新。当前版本已经覆盖了：环境变量 → MCP 部署配置 → 工具参数 → 典型使用场景的完整链路。