KDB。AI MCP服务器
KDB。支持与KDB交互的AI MCP(模型上下文协议)服务器。人工智能通过自然语言实现无缝的矢量数据库操作、矢量相似性搜索、混合搜索操作和高级数据分析。
它建立在具有可配置模板的可扩展框架之上,允许根据您的特定矢量搜索和人工智能数据需求量身定制的自定义集成进行直观扩展。该服务器利用精心策划的资源、智能提示和强大工具的组合,为与KDB交互的AI模型提供适当的指导。人工智能。
目录
支持的环境
下表显示了支持的操作系统的安装选项:
| 主操作系统 | KDB。人工智能 | MCP服务器 | UV/NPX | 克劳德桌面 | 替代MCP客户端 |
|---|---|---|---|---|---|
| 苹果电脑 | ✅ Docker | ✅ 本地 | ✅ 本地 | ✅ 本地(可流式传输http/stdio) | ✅ 其他客户 |
| Linux | ✅ Docker | ✅ 本地 | ✅ 本地 | ❌ 不支持 | ✅ 其他客户 |
| WSL | ✅ Docker | ✅ 本地 | ✅ 本地 | ❌ 不支持 | ✅ 其他客户 |
| 视窗 | ✅ Docker | ✅ 本地 | ✅ 本地 | ✅ 本地(仅限可流式传输的http) | ✅ 其他客户 |
| 视窗 | ✅ Docker | ⚠️ WSL | ✅ 本地 | ✅ 本地(仅限可流式传输的http) | ✅ 其他客户 |
先决条件
在安装和运行KDB之前。AI MCP服务器,确保您拥有:
- 对于Windows用户,我们建议使用WSL2集成安装Docker桌面 如本文所述
- 跟随 服务器设置指南 迅速起身并奔跑。 - 参见支持 KDB。AI文档 获取更多信息
- UV已安装 运行KDB。AI MCP服务器-可在Windows/Mac/Linux/WSL上使用
- 已安装Claude Desktop 或将连接到KDB的另一个MCP兼容客户端。AI MCP服务器-可在Windows/Mac上使用
- 已安装NPX -需要使用
streamable-http使用Claude Desktop进行运输
- npx 如果您使用的是其他MCP客户端,则可能不需要-请参阅您选择的MCP客户端的文档 - npx 与捆绑在一起 节点 安装程序-可在Windows/Mac/Linux/WSL上使用 - 看 具有流式http的示例配置
为了简化入门,我们建议您运行MCP客户端KDB。AI MCP服务器和您的KDB。同一内部网络中的AI数据库。请参阅 安全考虑 了解更多信息。
快速启动
演示KDB的基本用法。AI MCP服务器,使用空的KDB。AI数据库,请按照以下快速入门步骤进行操作。
注意:确保您遵循了必要的 先决条件步骤
- 启动您的KDB。AI服务器-按照以下开始步骤操作 KDB。AI服务器设置指南
- 测试与KDB的连接。AI服务器
如果您已设置KDB。AI服务器执行步骤1后,您的端点将 http://localhost:8082,否则更新到配置的端点。
uv run --with kdbai-client --python=3.12 python -c "import kdbai_client as kx; session = kx.Session(endpoint='http://localhost:8082'); print(session.version())"如果你看到下面这样的回复,你的KDB。AI服务器配置正确-请继续下一步。如果你看到不同的版本号,那也没关系。
{'serverVersion': 'latest', 'clientMinVersion': '1.7.0', 'clientMaxVersion': 'latest'}如果您收到以下错误消息 Error during creating connection...,这通常表示
- KDB。AI服务器未运行 - KDB。AI服务器不接受连接
请参阅 故障排除 更多详细信息
- 配置Claude桌面 您选择的交通工具。
- 配置嵌入 使用您选择的嵌入提供商和模型。
如果您已配置Claude Desktop stdio传输,则不需要此步骤。请转到下一步(Claude Desktop将为您管理启动MCP服务器)。
uv run mcp-server- 启动Claude Desktop并验证中列出的工具和提示 验证Claude桌面配置 部分可见。
- 按照以下步骤创建一些表并添加一些数据 KDB。AI快速入门指南
- 负载 kdbai_操作指南 资源。这将为您的MCP客户端提供一些关于如何与KDB交互的指导。AI数据库。
- 试试
kdbai_table_analysis提示并为其中一个表生成分析提示。
- 用自然语言提问:与您的KDB互动。使用简明英语的AI数据库。您的MCP客户端将使用一个或多个 可用工具 回答你的问题。
特性
- 相似性搜索:基于KDBAI服务器上构建的索引,在矢量数据库中的嵌入式文本上进行相似性搜索
- 混合搜索:在KDBAI服务器上构建稀疏和密集索引的混合搜索
- 可定制的查询和搜索结果优化:可定制的查询和搜索,包括结果截断(仅限查询)、过滤、分组、聚合、排序
- 法学硕士查询指南:全面的LLM就绪MCP资源(file://kdbai_operations_guidance)包含语法示例和最佳实践
- 数据库架构发现:使用附带的MCP资源探索和理解您的数据库表和结构,以获得快速、智能的见解。
- 自动发现系统:从各自的目录中自动发现和注册工具、资源和提示
- 现成的扩展模板:现成的工具、资源和提示模板,包含扩展功能的最佳实践和文档
- 统一智能:提示、工具和MCP资源协同工作:智能提示、专用工具和精心策划的MCP资源的强大组合——所有这些共同作用,提供快速、优化和情境感知的结果。
- HTTP流协议支持:支持最新的MCP流式HTTP协议,以实现高效的数据流,同时自动阻止弃用的SSE协议。
MCP服务器安装
克隆存储库
git clone https://github.com/KxSystems/kdbai-mcp-server.git
cd kdbai-mcp-server运行MCP服务器
安装依赖项
uv sync此步骤是可选的,但在首次启动MCP服务器或添加新的依赖关系后可能很有用。
如果你不跑 uv sync 首先,MCP客户端可以超时等待安装依赖项。
这可能是由以下包引起的 sentence-transformers 具有很大的依赖性。
运行服务器
uv run mcp-server运输选项
有关支持的传输的更多信息,请参阅官方文档
注意:我们不支持 sse 传输(服务器发送的事件),因为自2024-11-05协议版本以来,它已被弃用。
安全考虑
为了简化入门,我们建议您运行MCP客户端KDB。AI MCP服务器和您的KDB。同一内部网络上的AI数据库。
加密数据库连接
如果您需要KDB之间的加密连接。AI MCP服务器和您的KDB。AI数据库,您可以启用以下选项:
- 带TLS的QIPC:使用标志
--db.qipc-tls=true - 使用HTTPS的REST:使用标志
--db.rest-protocol=https
两者都需要设置TLS/HTTPS代理(使者, 引擎X)在KDB前面。AI作为先决条件:
- 由于代理将终止TLS连接,我们建议代理在与KDB相同的主机上运行。AI服务器
- 代理需要自己的证书-如果您没有自己的证书,可以创建自签名证书供内部使用。看a 创建自签名证书的示例 可以与您的代理一起使用
- 对于使用自签名证书的QIPC连接:
- 您需要指定自签名CA证书的位置 - 集 KX_SSL_CA_CERT_FILE 环境变量指向代理正在使用的CA证书文件 - 或者,您可以通过设置绕过证书验证 KX_SSL_VERIFY_SERVER=NO 用于开发和测试
- 对于Kubernetes:考虑使用类似的服务网格 istio 简化证书管理
加密MCP客户端连接
如果您需要MCP客户端和KDB之间的加密连接。AI MCP服务器:
- KDB。AI MCP服务器使用
streamable-http默认情况下进行传输,并在以下位置启动localhost服务器127.0.0.1:7000。我们不建议将其暴露在外部。 - 您可以选择在KDB前面设置HTTPS代理。AI MCP服务器,如 使者 或 引擎X 用于HTTPS终止
- FastMCP v2的身份验证功能已经过评估,但将暂时保留在v1上,以保持广泛的模型兼容性,直到客户端/模型赶上,届时我们将进行过渡。
- 使用时
stdio传输,这不是必需的,因为通信是通过同一主机上的标准输入/输出流进行的
命令行工具
KDB。AI MCP服务器提供详细的帮助文本,解释所有配置选项。
uv run mcp-server -h
usage: mcp-server [-h] [--mcp.server-name str] [--mcp.log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
[--mcp.transport {stdio,streamable-http}] [--mcp.port int] [--mcp.host str] [--db.host str]
[--db.port int] [--db.username str] [--db.password SecretStr] [--db.mode {rest,qipc}]
[--db.rest-protocol {http,https}] [--db.qipc-tls bool] [--db.database-name str] [--db.retry int]
[--db.k int] [--db.vector-weight float] [--db.sparse-weight float] [--db.embedding-csv-path str]
KDB.AI MCP Server that enables interaction with KDB.AI
options:
-h, --help show this help message and exit
mcp options:
MCP server configuration and transport settings
--mcp.server-name str
Name identifier for the MCP server instance [env: KDBAI_MCP_SERVER_NAME] (default:
KDBAI_MCP_Server)
--mcp.log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Logging verbosity level [env: KDBAI_MCP_LOG_LEVEL] (default: INFO)
--mcp.transport {stdio,streamable-http}
Communication protocol: 'stdio' (pipes) or 'streamable-http' (HTTP server) [env:
KDBAI_MCP_TRANSPORT] (default: streamable-http)
--mcp.port int HTTP server port - ignored when using stdio transport [env: KDBAI_MCP_PORT] (default: 7000)
--mcp.host str HTTP server bind address - ignored when using stdio transport [env: KDBAI_MCP_HOST] (default:
127.0.0.1)
db options:
KDB.AI database connection and search configuration
--db.host str KDB.AI server hostname or IP address [env: KDBAI_DB_HOST] (default: 127.0.0.1)
--db.port int KDB.AI server port number [env: KDBAI_DB_PORT] (default: 8082)
--db.username str Username for KDB.AI authentication [env: KDBAI_DB_USERNAME] (default: )
--db.password SecretStr
Password for KDB.AI authentication [env: KDBAI_DB_PASSWORD] (default: )
--db.mode {rest,qipc}
API mode: 'qipc' (fast binary protocol) or 'rest' (HTTP API) [env: KDBAI_DB_MODE] (default:
qipc)
--db.rest-protocol {http,https}
Select protocol for REST mode, not considered for QIPC mode [env: KDBAI_DB_REST_PROTOCOL]
(default: http)
--db.qipc-tls bool Enable TLS for QIPC mode, not considered for REST mode. When using TLS with QIPC you will need
to set the environment variable `KX_SSL_CA_CERT_FILE` that points to the certificate on your
local filesystem that your TLS proxy is using. For local development and testing you can set
`KX_SSL_VERIFY_SERVER=NO` to bypass this requirement [env: KDBAI_DB_QIPC_TLS] (default: False)
--db.database-name str
Default database name to use for operations [env: KDBAI_DB_DATABASE_NAME] (default: default)
--db.retry int Number of connection retry attempts on failure [env: KDBAI_DB_RETRY] (default: 2)
--db.k int Default number of results to return from vector searches [env: KDBAI_DB_K] (default: 5)
--db.vector-weight float
Weight for vector similarity in hybrid search (0.0-1.0) [env: KDBAI_DB_VECTOR_WEIGHT]
(default: 0.7)
--db.sparse-weight float
Weight for text similarity in hybrid search (0.0-1.0) [env: KDBAI_DB_SPARSE_WEIGHT] (default:
0.3)
--db.embedding-csv-path str
Path to embeddings csv [env: KDBAI_DB_EMBEDDING_CSV_PATH] (default:
src/mcp_server/utils/embeddings.csv)CLI配置选项
命令行选项分为两大类:
- MCP选项-控制MCP服务器行为和传输设置
- 数据库选项-配置KDB。AI数据库连接和搜索行为
有关每个选项的详细信息,请参阅 帮助文本
配置方法
配置值按以下优先级顺序解析:
- 命令行参数 -最高优先级
- 环境变量 -第二优先
- .env文件 -第三优先
- 默认值 -中定义的默认值
settings.py
环境变量
每个命令行选项都有一个相应的环境变量。例如:
--mcp.port 8000↔KDBAI_MCP_PORT=8000--db.host localhost↔KDBAI_DB_HOST=localhost
示例用法
# Using defaults
uv run mcp-server
# Using a .env file
echo "KDBAI_MCP_PORT=8080" >> .env
echo "KDBAI_DB_RETRY=4" >> .env
uv run mcp-server
# Using environment variables
export KDBAI_MCP_PORT=8080
export KDBAI_DB_RETRY=4
uv run mcp-server
# Using command line arguments
uv run mcp-server \
--mcp.port 8080 \
--db.retry 4配置嵌入
在启动KDB之前。如果要使用相似性搜索,则必须为表配置嵌入模型。 该存储库包括两个即用型嵌入提供程序:OpenAI和SentenceTransformers。 您可以根据需要自定义这些实现,也可以按照下面概述的步骤添加自己的提供者。
- 更新依赖关系-将所需的嵌入提供程序添加到
pyproject.toml依赖关系部分。
- 设置环境变量-如果需要,为所选嵌入提供程序配置所需的API密钥(例如,设置环境变量
OPENAI_API_KEY使用OpenAI的API)
- 添加新提供程序-文件
src/mcp_server/utils/embeddings.py定义基类EmbeddingProvider对于所有嵌入提供商。
要添加新的提供程序,请在同一文件中创建一个类,该类扩展了此基类并实现了所有必需的抽象方法。 您可以在同一个文件中使用OpenAI和SentenceTransformers的现有实现作为模板——只需复制和修改它们以满足您的需求。要注册您的提供商,请使用 @register_provider 装饰器位于类定义之上。注册的提供者名称不必跟在提供者的Python包名称后面。
- 配置表嵌入-更新嵌入配置文件
src/mcp_server/utils/embeddings.csv使用您的实际数据库和表名,嵌入提供者和模型。您在以下网址提供的名称embeddings.csv应与文件中指定的注册提供程序名称匹配embeddings.py.
使用Claude Desktop
配置Claude桌面
Claude Desktop需要 claude_desktop_config.json 文件可用。
将以下示例配置之一添加到操作系统的默认配置文件位置。
| 平台 | 默认配置文件位置 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| 窗户 | %APPDATA%\Claude\claude_desktop_config.json |
具有流式http的示例配置
使用KDB配置Claude Desktop。AI MCP服务器使用 streamable-http,将以下配置复制到空 claude_desktop_config.json 文件。
如果您有预先存在的MCP服务器,请参阅 具有多个mcp服务器的示例配置.
{
"mcpServers": {
"KDB.AI MCP streamable": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:7000/mcp"
]
}
}
}备注
- 使用
streamable-http使用Claude Desktop,您必须拥有npx已安装并可在您的路径上使用-您可以通过以下方式安装 - 您需要将MCP服务器作为一个独立的python进程启动。见第节 运行服务器
- 确保你有正确的端点——在这个例子中是我们的KDB。AI MCP服务器正在端口上运行
7000. - 这意味着您将负责启动和停止MCP服务器,Claude Desktop只能通过以下方式访问它
npx - MCP日志将从您的终端可见
stdio配置示例
使用KDB配置Claude Desktop。AI MCP服务器使用 stdio,将以下配置复制到空 claude_desktop_config.json 文件。
如果您有预先存在的MCP服务器,请参阅 具有多个mcp服务器的示例配置.
{
"mcpServers": {
"KDB.AI MCP stdio": {
"command": "/Users//.local/bin/uv",
"args": [
"--directory",
"/path/to/this/repo/",
"run",
"mcp-server",
"--mcp.transport",
"stdio"
]
}
}
}备注
- 更新您的 `
指向uv可执行文件的绝对路径-仅在以下情况下需要uv` 不在你的路上 - 更新
--directory此repo的绝对路径 - Claude Desktop负责在使用时启动/停止MCP服务器
stdio - 使用时
stdioMCP日志将在 Claude Desktop的MCP日志位置
具有多个MCP服务器的示例配置
您可以包括多个MCP服务器,如下所示:
{
"mcpServers": {
"KDB.AI MCP streamable": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:7000/mcp"
]
},
"Another MCP Server": {...}
}
}有关详细的设置说明,请参阅 克劳德桌面官方文档.
验证Claude桌面配置
- 如果您正在使用
streamable-http您需要在单独的终端窗口中启动MCP服务器,并确保其保持运行。如果您正在使用stdio跳到步骤2。
- 一旦
claude_desktop_config.json已添加您选择的传输配置,请重新启动Claude Desktop。然后导航到File>Settings>Developer你应该看看你的KDB。AI MCP服务器正在运行。
- Windows用户:请确保在重新启动之前通过系统托盘退出Claude Desktop。
- 在聊天窗口中单击
search and tools左侧消息框正下方的图标。您将看到您的MCP服务器列为KDB.AI MCP streamable。单击它以访问所有工具。
- 点击聊天窗口中的“+”,然后选择
Add from KDB.AI MCP streamable查看可用提示/资源列表。
启用Claude桌面开发人员模式
可以启用开发人员模式,以便快速访问:
- MCP服务器重新加载-无需每次重启MCP服务器都退出Claude Desktop
- MCP配置-您的快捷方式
claude_desktop_config.json - MCP日志-克劳德桌面MCP日志的快捷方式-使用传输时
streamable-http您还需要从终端查看mcp日志
要启用开发人员模式,请执行以下操作:
- 启动Claude Desktop,单击左上角的菜单>
Help>Troubleshooting>Enable Developer Mode(确认任何弹出窗口) - 重新启动Claude Desktop,单击左上角的菜单>
Developer>现在应该填充开发人员设置
提示/资源/工具
提示
| 名称 | 目的 | 参数 | 返回 |
|---|---|---|---|
| kdbai_table_analysis | 为特定表生成详细的分析提示 | table_name:KDB的名称。要分析的AI表 |
analysis_type:分析类型(概述、内容、质量、搜索) sample_size:要检查的记录数|生成的表分析提示|
资源
| 名称 | URI | 目的 | 参数 |
|---|---|---|---|
| kdbai_操作指南 | file://kdbai_operations_guidance | 在使用查询、搜索和混合搜索等KDBAI操作时提供指导 | 无 |
工具
| 名称 | 目的 | 参数 | 返回 |
|---|---|---|---|
| kdbai_query_data | 从kdbai表中查询数据,支持过滤、排序、分组、限制和聚合。 | table_name:要查询的表的名称 |
database_name:包含表的数据库的名称(可选) filters:筛选条件列表,如q/kdb+解析树 sort_columns:要排序的列名列表 group_by:要分组的列名列表 aggs:聚合规则词典 limit:要返回的最大行数|包含查询结果或错误消息的字典| |kdbai_similarity_search |在KDB上执行向量相似性搜索。AI表。 | table_name:要搜索的表的名称 query:文本查询转换为矢量和搜索 vector_index_name:要搜索的矢量索引的名称 database_name:数据库名称(可选) n:要返回的结果数(可选) filters:过滤条件列表 sort_columns:要排序的列名列表 group_by:要分组的列名列表 aggs:聚合规则词典|包含搜索结果的词典| |kdbai_hybrid_search |在KDB上执行结合向量和文本(稀疏)搜索的混合搜索。AI表。 | table_name:要搜索的表的名称 query:用于矢量和文本搜索的文本查询 vector_index_name:矢量索引的名称 sparse_index_name:稀疏索引的名称 database_name:数据库名称(可选) n:要返回的结果数(可选) filters:过滤条件列表 sort_columns:要排序的列名列表 group_by:要分组的列名列表 aggs:聚合规则词典|包含混合搜索结果的词典| |kdbai_list_databases|列出KDB中的所有数据库名称。AI数据库。|无|带状态和数据库名称列表的词典| |kdbai_database_info |获取KDB。AI数据库信息,包括表信息。 | database:数据库名称(可选,默认为“默认”)|包含状态和数据库信息的字典| |kdbai_all_databases_info |获取KDB中所有数据库的信息。AI包括每个数据库的表信息。|无|包含所有数据库状态和信息的词典| |kdbai_session_info |从KDB获取会话信息。AI.|无|包含会话信息和元数据的字符串| |kdbai_system_info |从KDB获取系统信息。AI.|无|包含系统信息和元数据的字符串| |kdbai_process_info |从KDB获取进程信息。AI.|无|包含流程信息和元数据的字符串| |kdbai_list_tables|列出给定数据库中的所有表。 | database_name:数据库名称(可选,默认为已配置的数据库)|包含数据库名称和表列表的字典| |kdbai_table_info |获取有关表的全面信息,包括模式和统计信息。 | table_name:表的名称 database_name:数据库名称(可选,默认为已配置的数据库)|包含表信息的字典,包括名称、数据库、磁盘使用情况、行数、架构和索引|
发展
要添加新工具,请执行以下操作:
- 在src/mcp_server/tools/中创建一个新的Python文件。
- 使用_template.py作为参考来实现您的工具。
- 服务器启动时,该工具将被自动发现并注册。
- 重新启动Claude Desktop以访问新工具。
要添加新资源,请执行以下操作:
- 在src/mcp_server/resources/中创建一个新的Python文件。
- 使用_template.py作为引用来实现您的资源。
- 服务器启动时,将自动发现并注册资源。
- 重新启动Claude Desktop以访问新资源。
要添加新提示,请执行以下操作:
- 在src/mcp_server/promises/中创建一个新的Python文件。
- 使用_template.py作为引用来实现您的提示。
- 服务器启动时,将自动发现并注册提示。
- 重新启动Claude Desktop以访问新提示。
测试
以下工具可以帮助开发、测试和调试新的MCP工具、资源和提示。
故障排除
使用stdio传输时MCP服务器无法启动
当首次使用stdio传输运行MCP服务器时,可能会出现这种情况。建议跑步 uv sync 如第节所述 运行MCP服务器
KDB。AI MCP端口可用性检查失败
如果MCP服务器端口正被另一个进程使用,您需要指定一个不同的端口或停止使用该端口的服务。
KDB。AI数据库连接检查失败
这意味着你的KDB。AI服务器未运行或不接受连接。 请参阅 快速入门 上面的部分。
MCP服务器传输无效
有效运输方式为 streamable-http 和 stdio.
MCP服务器缺少工具/资源/提示
查看服务器日志中的注册错误。日志包括工具、资源和提示的注册摘要。您可以识别失败和跳过的模块,以帮助调试问题。
当存在打开的连接时,MCP服务器无法关闭
这似乎是 FastMCP的问题。它引用了 sse 特别是运输方式,但我们观察到与 streamable-http。您需要关闭所有打开的连接,或者终止mcp进程。
Claude Desktop中禁用MCP服务器
如果您在查询后看到MCP服务器被禁用,请重新启动/退出claude(如上所述)并重试。
UV默认路径
| 平台 | 默认UV路径 |
|---|---|
| macOS | ~/.local/bin/uv |
| Linux | ~/.local/bin/uv |
| 视窗 | %APPDATA%\Python\Scripts\uv.exe |
克劳德日志位置
| 平台 | 路径 | 监视器命令 |
|---|---|---|
| macOS | ~/Library/Logs/Claude/mcp*.log | tail -f ~/Library/Logs/Claude/mcp*.log |
| 视窗 | %APPDATA%\Claude\Logs\mcp*.log | Get-Content -Path "$env:APPDATA\Claude\Logs\mcp*.log" -Wait |
克劳德官方故障排除文档
有关详细的故障排除,请参阅 Claude MCP官方文档.
克劳德极限
您可能需要升级到付费计划,以避免像这样的Claude使用错误:
克劳德达到了这次谈话的最大长度。请开始新的对话,继续和克劳德聊天。
