milvus-knowledge-mcp-server

v1.0.0

Published

2 months ago

MCP server for Milvus knowledge base integration with semantic search capabilities

0High
0Medium
0Low

liuxianling

mcp model-context-protocol milvus vector-database knowledge-base semantic-search ai llm claude

Milvus Knowledge MCP Server

基于 Model Context Protocol (MCP) 的 Milvus 知识库服务器，为 AI 助手提供语义搜索能力。

功能特性

语义搜索: 在 Milvus 向量数据库中进行语义搜索
多集合支持: 同时搜索多个知识集合
灵活输出: 支持 Markdown 和 JSON 输出格式
双传输模式: 支持 stdio 和 HTTP 两种传输方式
类型安全: 使用 TypeScript 和 Zod 进行完整类型检查
完善的测试: 36 个单元测试和集成测试全部通过

安装

方式一：使用 npx (推荐)

无需安装，直接使用 npx 运行：

npx -y milvus-knowledge-mcp-server

方式二：全局安装

npm install -g milvus-knowledge-mcp-server
milvus-knowledge-mcp-server

方式三：从源码安装

# 克隆仓库
git clone https://gitee.com/xywdy/knowage_mcp.git
cd knowage_mcp

# 安装依赖并构建
npm install
npm run build

# 运行
npm start

配置

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | MILVUS_HOST | 127.0.0.1 | Milvus 服务器地址 | | MILVUS_PORT | 19530 | Milvus 服务器端口 | | TRANSPORT | stdio | 传输模式 (stdio/http) | | PORT | 3000 | HTTP 模式端口 |

默认集合

项目默认搜索以下集合：

components - 组件文档和代码
asserts - 断言模式和测试用例
chunks_v1 - 通用知识块

与 Claude Desktop 集成

编辑 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

使用 npx (推荐)

{
  "mcpServers": {
    "milvus-knowledge": {
      "command": "npx",
      "args": ["-y", "milvus-knowledge-mcp-server"],
      "env": {
        "MILVUS_HOST": "127.0.0.1",
        "MILVUS_PORT": "19530"
      }
    }
  }
}

使用全局安装

{
  "mcpServers": {
    "milvus-knowledge": {
      "command": "milvus-knowledge-mcp-server",
      "env": {
        "MILVUS_HOST": "127.0.0.1",
        "MILVUS_PORT": "19530"
      }
    }
  }
}

使用本地路径

{
  "mcpServers": {
    "milvus-knowledge": {
      "command": "node",
      "args": ["/path/to/knowage_mcp/dist/index.js"],
      "env": {
        "MILVUS_HOST": "127.0.0.1",
        "MILVUS_PORT": "19530"
      }
    }
  }
}

使用方法

stdio 模式 (默认)

npx -y milvus-knowledge-mcp-server

HTTP 模式

MILVUS_HOST=127.0.0.1 MILVUS_PORT=19530 TRANSPORT=http PORT=3000 npx -y milvus-knowledge-mcp-server

服务将在 http://localhost:3000/mcp 启动，健康检查端点为 http://localhost:3000/health。

MCP 工具

knowledge_search

搜索知识库获取相关信息。

参数: | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | query | string | 必填 | 搜索查询 | | collections | string[] | ["components", "asserts", "chunks_v1"] | 要搜索的集合 | | top_k | number | 5 | 每个集合返回的结果数 (1-20) | | output_format | "markdown" | "json" | "markdown" | 输出格式 | | min_score | number | 0.5 | 最小相似度阈值 (0-1) |

示例:

{
  "query": "如何实现用户认证",
  "collections": ["components", "chunks_v1"],
  "top_k": 5,
  "min_score": 0.5
}

knowledge_list_collections

列出所有可用的知识集合。

knowledge_get_collection_info

获取指定集合的详细信息，包括 schema。

触发方式

当用户消息包含 @知识库 前缀时，AI 助手应自动调用 knowledge_search 工具进行知识检索。

示例：

@知识库如何实现用户认证？
@知识库 API 文档

开发

项目结构

knowage_mcp/
├── src/
│   ├── index.ts              # 主入口
│   ├── milvus-client.ts      # Milvus 客户端
│   ├── schemas.ts            # Zod 验证模式
│   ├── formatters.ts         # 输出格式化
│   └── tools/
│       └── knowledge-tools.ts # MCP 工具定义
│   └── tests/                # 测试文件
├── dist/                     # 编译输出
├── docs/                     # 文档
├── package.json
├── tsconfig.json
└── vitest.config.ts

命令

# 开发模式 (热重载)
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 测试覆盖率
npm run test:coverage

# 使用 MCP Inspector 调试
npm run inspector

测试

npm test

测试结果：

测试文件: 3
测试用例: 36
通过率: 100%

详细报告见测试报告。

文档

技术栈

TypeScript - 类型安全
MCP SDK - Model Context Protocol
Milvus SDK - 向量数据库
Zod - Schema 验证
Vitest - 测试框架
Express - HTTP 服务器