Get Notes MCP Server

A Model Context Protocol (MCP) server that provides integration with the Get Notes API for knowledge base search and retrieval.

English | 中文

English

Features

• Knowledge Search: AI-powered search with intelligent answers and references
• Knowledge Recall: Raw knowledge base retrieval without AI processing
• Multiple Transport Modes: Support for stdio, SSE, and HTTP transports
• Streaming Support: Real-time streaming responses for better user experience
• Multiple Search Modes: Both AI-processed and raw recall modes
• Conversation History: Support for follow-up questions with context
• Reference Tracking: Optional inclusion of source material references

Quick Start

Option 1: Using npx (Recommended - No Local Installation Required)

Advantages:

• ✅ No local installation needed
• ✅ Always uses the latest version
• ✅ Quick and easy setup
• ✅ Perfect for one-time or occasional use

# Set your API key and optional topic ID
export GET_NOTE_API_KEY="your-api-key-here"
export GET_NOTE_TOPIC_ID="your-topic-id"  # Optional but recommended

# Start the server directly with npx
npx get-biji-mcp

# Or with specific transport mode
npx get-biji-mcp --transport stdio
npx get-biji-mcp --transport sse --port 3000
npx get-biji-mcp --transport http --port 8080

Option 2: Local Installation (For Development/Customization)

Advantages:

• ✅ Full source code access for customization
• ✅ Works offline after installation
• ✅ Better for development and debugging
• ✅ Can modify and extend functionality

# Clone or download the project
git clone https://github.com/PancrePal-xiaoyibao/get_biji_mcp.git
cd get_biji_mcp

# Install dependencies
npm install

# For HTTP/SSE transport modes, also install express
npm install express

2. Configuration

Set the required environment variables (same for both npx and local usage):

# Required: Set your Get Notes API key
export GET_NOTE_API_KEY="your-api-key-here"

# Optional: Set default knowledge base topic ID
export GET_NOTE_TOPIC_ID="your-topic-id"

# Optional: Configure other settings
export GET_NOTE_API_BASE_URL="https://open-api.biji.com/getnote/openapi"
export GET_NOTE_API_TIMEOUT="30000"
export GET_NOTE_API_RETRIES="3"
export LOG_LEVEL="info"

3. Start the Server

For npx users (Recommended):

# STDIO mode (default)
npx get-biji-mcp
# or
npx get-biji-mcp --transport stdio

# SSE mode
npx get-biji-mcp --transport sse --port 3000

# HTTP mode
npx get-biji-mcp --transport http --port 8080 --host 0.0.0.0

For local installation:

# STDIO mode (default)
npm start
# or
node src/index.js

# SSE mode
npm start -- --transport sse --port 3000
# or
node src/index.js --transport sse --port 3000

# HTTP mode
npm start -- --transport http --port 8080 --host 0.0.0.0
# or
node src/index.js --transport http --port 8080 --host 0.0.0.0

Available Tools

search_knowledge

Search knowledge base with AI processing to get intelligent answers with references.

Parameters:

• question (string, required): The question to search for
• topic_ids (array, required): Knowledge base topic IDs (supports one ID)
• deep_seek (boolean, optional): Enable deep thinking mode (default: true)
• refs (boolean, optional): Include references (default: false)
• history (array, optional): Conversation history for follow-up questions

search_knowledge_stream

Search knowledge base with streaming response for real-time answers.

Parameters: Same as search_knowledge

recall_knowledge

Recall raw knowledge base entries without AI processing.

Parameters:

• question (string, required): The question to search for
• topic_id (string, optional): Single topic ID (alternative to topic_ids)
• topic_ids (array, optional): Knowledge base topic IDs
• top_k (number, optional): Number of results (default: 10)
• intent_rewrite (boolean, optional): Enable intent rewriting (default: false)
• select_matrix (boolean, optional): Enable result reselection (default: false)

recall_knowledge_detailed

Recall knowledge base entries with full content and metadata in structured format.

Parameters: Same as recall_knowledge with default top_k: 5

Testing with MCP Inspector

Use the official MCP inspector to test the server:

Option 1: Test with npx (No Installation Required)

# Test STDIO mode
npx @modelcontextprotocol/inspector
# Then enter: npx get-biji-mcp

# Test SSE mode
npx @modelcontextprotocol/inspector --transport sse --url http://localhost:3000

# Test HTTP mode
npx @modelcontextprotocol/inspector --transport http --url http://localhost:8080

Option 2: Test with Local Installation

# Install MCP inspector globally
npm install -g @modelcontextprotocol/inspector

# Test STDIO mode
mcp-inspector
# Then enter: node src/index.js

# Test SSE mode
mcp-inspector --transport sse --url http://localhost:3000

# Test HTTP mode
mcp-inspector --transport http --url http://localhost:8080

Transport Mode Details

STDIO Mode

• Use case: Local development, Claude Desktop integration
• Endpoint: Standard input/output
• Command: npm start

SSE Mode

• Use case: Web applications, real-time updates
• Endpoints:
  • GET /health - Health check
  • GET /tools - List available tools
  • GET /sse - SSE endpoint
  • POST /message - Message endpoint
• Command: npm start -- --transport sse --port 3000

HTTP Mode

• Use case: REST API integration, microservices
• Endpoints:
  • GET /health - Health check
  • GET /tools - List available tools
  • POST /tools/call - Direct tool calls
  • POST /mcp - MCP protocol endpoint
• Command: npm start -- --transport http --port 8080

Configuration Parameters

| Parameter | Environment Variable | Default | Description | |-----------|---------------------|---------|-------------| | API Key | GET_NOTE_API_KEY | - | Required: Your Get Notes API key | | Base URL | GET_NOTE_API_BASE_URL | https://open-api.biji.com/getnote/openapi | API endpoint URL | | Timeout | GET_NOTE_API_TIMEOUT | 30000 | Request timeout in milliseconds | | Retries | GET_NOTE_API_RETRIES | 3 | Number of retry attempts | | Log Level | LOG_LEVEL | info | Logging level (debug/info/warn/error) | | Transport | --transport | stdio | Transport mode (stdio/sse/http) | | Port | --port | 3000 | Port for HTTP/SSE modes | | Host | --host | localhost | Host for HTTP/SSE modes |

Quick Examples

Test with npx (No Installation Required)

# Set your API key
export GET_NOTE_API_KEY="your-api-key-here"

# List available tools
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx get-biji-mcp

# Search knowledge base
echo '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"search_knowledge","arguments":{"question":"What are the key insights?","topic_ids":["your-topic-id"],"deep_seek":true}}}' | npx get-biji-mcp

MCP Client Configuration Examples

1. Claude Desktop Configuration (npx version - Recommended)

{
  "mcpServers": {
    "get-notes": {
      "command": "npx",
      "args": ["get-biji-mcp"],
      "env": {
        "GET_NOTE_API_KEY": "your-api-key-here",
        "GET_NOTE_TOPIC_ID": "your-topic-id"
      }
    }
  }
}

2. Claude Desktop Configuration (Local Installation)

{
  "mcpServers": {
    "get-notes": {
      "command": "node",
      "args": ["/path/to/get_biji_mcp/src/index.js"],
      "env": {
        "GET_NOTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

2. VS Code MCP Extension

{
  "mcp.servers": {
    "get-notes": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-get-notes/src/index.js"],
      "env": {
        "GET_NOTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Custom MCP Client (HTTP Mode)

const response = await fetch('http://localhost:8080/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'search_knowledge',
    arguments: {
      question: 'What is machine learning?',
      topic_ids: ['your-topic-id']
    }
  })
});

Development

Running Tests

npm test

Code Formatting

npm run format

Linting

npm run lint

Validation

npm run validate

中文

功能特点

• 知识搜索: AI驱动的智能搜索，提供带参考的答案
• 知识召回: 无AI处理的原始知识库检索
• 多传输模式: 支持stdio、SSE和HTTP传输
• 流式支持: 实时流式响应，提升用户体验
• 多种搜索模式: AI处理和原始召回两种模式
• 会话历史: 支持上下文追问
• 参考追踪: 可选的源材料引用

快速开始

1. 安装

# 克隆或下载项目
cd mcp-get-notes

# 安装依赖
npm install

# HTTP/SSE模式需要额外安装express
npm install express

2. 配置

设置必需的环境变量：

# 必需：设置Get笔记API密钥
export GET_NOTE_API_KEY="your-api-key-here"

# 可选：设置默认知识库主题ID
export GET_NOTE_TOPIC_ID="your-topic-id"

# 可选：其他配置
export GET_NOTE_API_BASE_URL="https://open-api.biji.com/getnote/openapi"
export GET_NOTE_API_TIMEOUT="30000"
export GET_NOTE_API_RETRIES="3"
export LOG_LEVEL="info"

3. 启动服务器

STDIO模式（默认）：

npm start
# 或
node src/index.js

SSE模式：

npm start -- --transport sse --port 3000
# 或
node src/index.js --transport sse --port 3000

HTTP模式：

npm start -- --transport http --port 8080 --host 0.0.0.0
# 或
node src/index.js --transport http --port 8080 --host 0.0.0.0

可用工具

search_knowledge

使用AI处理搜索知识库，获取智能答案和参考。

参数：

• question (字符串, 必需): 搜索问题
• topic_ids (数组, 必需): 知识库主题ID（支持一个ID）
• deep_seek (布尔值, 可选): 启用深度思考模式（默认: true）
• refs (布尔值, 可选): 包含参考（默认: false）
• history (数组, 可选): 会话历史，用于追问

search_knowledge_stream

流式搜索知识库，实时获取答案。

参数： 同 search_knowledge

recall_knowledge

无AI处理地召回原始知识库条目。

参数：

• question (字符串, 必需): 搜索问题
• topic_id (字符串, 可选): 单个主题ID（替代topic_ids）
• topic_ids (数组, 可选): 知识库主题ID
• top_k (数字, 可选): 结果数量（默认: 10）
• intent_rewrite (布尔值, 可选): 启用意图重写（默认: false）
• select_matrix (布尔值, 可选): 启用结果重选（默认: false）

recall_knowledge_detailed

以结构化格式召回知识库条目的完整内容和元数据。

参数： 同 recall_knowledge，默认 top_k: 5

使用MCP Inspector测试

使用官方MCP Inspector测试服务器：

# 全局安装MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 测试STDIO模式
mcp-inspector
# 然后输入: node src/index.js

# 测试SSE模式
mcp-inspector --transport sse --url http://localhost:3000

# 测试HTTP模式
mcp-inspector --transport http --url http://localhost:8080

传输模式详情

STDIO模式

• 用例: 本地开发、Claude Desktop集成
• 端点: 标准输入/输出
• 命令: npm start

SSE模式

• 用例: Web应用、实时更新
• 端点:
  • GET /health - 健康检查
  • GET /tools - 工具列表
  • GET /sse - SSE端点
  • POST /message - 消息端点
• 命令: npm start -- --transport sse --port 3000

HTTP模式

• 用例: REST API集成、微服务
• 端点:
  • GET /health - 健康检查
  • GET /tools - 工具列表
  • POST /tools/call - 直接工具调用
  • POST /mcp - MCP协议端点
• 命令: npm start -- --transport http --port 8080

配置参数

| 参数 | 环境变量 | 默认值 | 描述 | |-----------|---------------------|---------|-------------| | API密钥 | GET_NOTE_API_KEY | - | 必需: Get笔记API密钥 | | 主题ID | GET_NOTE_TOPIC_ID | - | 默认知识库主题ID | | 基础URL | GET_NOTE_API_BASE_URL | https://open-api.biji.com/getnote/openapi | API端点URL | | 超时时间 | GET_NOTE_API_TIMEOUT | 30000 | 请求超时时间（毫秒） | | 重试次数 | GET_NOTE_API_RETRIES | 3 | 重试次数 | | 日志级别 | LOG_LEVEL | info | 日志级别（debug/info/warn/error） | | 传输模式 | --transport | stdio | 传输模式（stdio/sse/http） | | 端口 | --port | 3000 | HTTP/SSE模式端口 | | 主机 | --host | localhost | HTTP/SSE模式主机 |

MCP客户端配置示例

1. Claude Desktop配置

{
  "mcpServers": {
    "get-notes": {
      "command": "node",
      "args": ["/path/to/mcp-get-notes/src/index.js"],
      "env": {
        "GET_NOTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

2. VS Code MCP扩展

{
  "mcp.servers": {
    "get-notes": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-get-notes/src/index.js"],
      "env": {
        "GET_NOTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 自定义MCP客户端（HTTP模式）

const response = await fetch('http://localhost:8080/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'search_knowledge',
    arguments: {
      question: '什么是机器学习？',
      topic_ids: ['your-topic-id']
    }
  })
});

开发

运行测试

npm test

代码格式化

npm run format

代码检查

npm run lint

配置验证

npm run validate

日志

日志文件位置：

• logs/error.log: 仅错误级别消息
• logs/combined.log: 所有日志消息
• 控制台: 带颜色的实时输出

许可证

MIT

❤️ Acknowledgments

This project is contributed by the 小x宝社区 (Xiao-X-Bao Community) - an AI open-source public welfare community focused on improving healthcare information access for cancer/rare disease patients and their families throughout their entire lifecycle.

About 小x宝社区 (Xiao-X-Bao Community)

We are an AI open-source public welfare community dedicated to building a high-quality, high-density patient knowledge ecosystem using AI technology to improve medical information barriers. Our community brings together diverse groups including open-source contributors, AI technology experts, cancer patients, family members, healthcare professionals, and public welfare volunteers, all working together to improve the information access challenges faced by patients.

Community Website: https://info.xiao-x-bao.com.cn

Our Mission: Using AI technology to break down medical information barriers and build a comprehensive knowledge ecosystem for patients.

Community Name Origin: All our AI assistants are named with "小x宝" (Xiao-X-Bao), such as "小胰宝" (Little Pancreas Treasure), "小粉宝" (Little Pink Treasure), etc., hence our community is named "小x宝社区" (Xiao-X-Bao Community).

Community Development: In 2024, the project was donated to the "天工开物基金会" (Tiangong Kaiwu Foundation), which provides funding and guidance to promote public welfare initiatives.

Progress Updates: Released through WeChat Official Account "小胰宝助手" (Little Pancreas Treasure Assistant).

Community Contacts

Detailed Community Introduction: View Presentation

Community Contacts:

• WeChat ID: qinxiaoqiang2002
• WeChat ID: hhxdeweixinxin
• WeChat ID: zhuangbiaowei

We welcome all contributors, developers, healthcare professionals, and volunteers to join our community in using technology to improve healthcare information accessibility! 🌟