Kyma知识MCP服务器
一个MCP服务器，允许AI代理对Kyma文档进行语义搜索访问，不需要凭据或后端服务。索引在首次运行时自动下载并在本地缓存；后续查询完全脱机运行。
______________________________________________________________________
先决条件
此服务器以Python包的形式分发，并由 uvx （部分 紫外线).如果你还没有：
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via Homebrew
brew install uv验证安装：
uvx --version______________________________________________________________________
快速启动
提示： 最快的安装方式是通过 插件市场 在......下面有关Cline或Claude Desktop，请参阅以下部分。
插件市场（推荐）
终端:
claude plugin marketplace add danjiawork/kyma-knowledge-mcp
claude plugin install kyma-knowledge-mcp@kyma-pluginsMCP服务器立即在用户范围内注册。技能 /install-kyma-knowledge-mcp 与插件捆绑在一起-运行它以验证连接、更改范围或查看示例查询。
要确认服务器已连接，请运行 /mcp 内部克劳德代码或 claude mcp list 在你的终端。
克劳德代码
项目级别 （仅此工作区）：
claude mcp add kyma-knowledge-mcp \
-- uvx --from git+https://github.com/danjiawork/kyma-knowledge-mcp kyma-knowledge-mcp全球 （所有Claude Code会话）：
claude mcp add kyma-knowledge-mcp --scope user \
-- uvx --from git+https://github.com/danjiawork/kyma-knowledge-mcp kyma-knowledge-mcp运行后，验证服务器是否已注册并通过以下两种方式之一连接：
claude mcp list # run from the same project folder for project-level installs或者在Claude Code会话中，运行 /mcp 查看和管理所有活动的MCP服务器。
项目级安装：claude mcp list和/mcp仅当您位于运行的项目文件夹内时显示服务器claude mcp add。如果您没有看到它，请检查您的终端/Claude Code会话是否已从该目录打开。
你应该看到 kyma-knowledge-mcp 与状态 连接的。如果显示为断开连接，请启动一个新的Claude Code会话，服务器将在下次启动时自动连接。
第一个查询： 首次运行时，服务器将Kyma文档索引（约60 MB）下载到 ~/.kyma-knowledge-mcp/ 并加载嵌入模型。这需要 1-3分钟 并且只发生一次。此会话和所有未来会话中的后续查询都很快。在假设出了什么问题之前，等待第一个反应。Cline（VS代码）
添加 cline_mcp_settings.json:
{
"mcpServers": {
"kyma-knowledge-mcp": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/danjiawork/kyma-knowledge-mcp",
"kyma-knowledge-mcp"
]
}
}
}______________________________________________________________________
可用工具
注册后，用自然语言描述你需要什么——代理会自动选择合适的工具：
| 你说什么 | 工具调用 |
|---|---|
| _“如何使用OAuth2配置APIRule？”_ | search_kyma_docs |
| _“显示事件管理器文档”_ | search_kyma_docs |
| _“什么是Kyma模块？”_ | search_kyma_docs |
| _“api网关一直崩溃，帮我调试”_ | search_kyma_docs |
| _“我如何为遥测管理器做出贡献？”_ | search_kyma_contributor_docs |
| _“api网关的测试策略是什么？”_ | search_kyma_contributor_docs |
search_kyma_docs 搜索 面向用户的文档 （如何部署、配置和操作Kyma）。 search_kyma_contributor_docs 搜索 贡献者文档 （架构决策、开发设置、测试指南、贡献工作流）。
______________________________________________________________________
配置参考
将这些设置为环境变量或 .env 项目根目录下的文件。看 .env.示例 对于模板。
| 变量 | 默认值 | 描述 |
|---|---|---|
LOCAL_INDEX_PATH | _（空）_ | 索引目录路径或 .tar.gz 档案文件；如果为空，则自动下载 |
LOCAL_EMBED_MODEL_OVERRIDE | _（空）_ | 覆盖嵌入模型（从 meta.json 默认情况下） |
LOG_LEVEL | INFO | 日志记录级别(DEBUG 用于详细输出） |
DEFAULT_TOP_K | 10 | 面向用户的搜索工具的默认结果数 |
RERANKER_MODEL | ms-marco-TinyBERT-L-2-v2 | 交叉编码器重新排序模型。设置为空字符串以禁用。看 查询管道 在......下面 |
RERANKER_FETCH_MULTIPLIER | 3 | 根据最终结果选出的候选人(fetch_n = top_k × multiplier).仅在以下情况下使用 RERANKER_MODEL 已设置。 |
______________________________________________________________________
查询管道
默认情况下，服务器使用 二级流水线:
- 检索 --双编码器矢量搜索（fastembed+ChromaDB）获取
top_k × RERANKER_FETCH_MULTIPLIER候选人。 - 重新排序 一 闪光等级 交叉编码器(
ms-marco-TinyBERT-L-2-v2)根据完整查询对每个候选人进行重新评分，并返回顶部top_k结果。
交叉编码器联合比较查询和文档，捕捉纯向量相似性遗漏的相关性信号。CPU上每次查询的开销约为100-200ms，对于AI代理使用的MCP服务器来说可以忽略不计。重新登录模型（约30 MB，Apache 2.0）在首次启动时下载一次，并缓存在 ~/.kyma-knowledge-mcp/reranker/.
要禁用重新排序（纯矢量搜索，更快）：
RERANKER_MODEL=更高质量的模型 （速度较慢，约4-5倍，约130 MB，Apache 2.0）： ms-marco-MiniLM-L-12-v2
______________________________________________________________________
在本地构建指数
用法
uv sync
# Fetch docs, build index, and package into a distributable archive
uv run kyma-knowledge-mcp-build-index \
--sources kyma_knowledge_mcp/indexing/docs_sources.json \
--data-dir /tmp/kmc-data \
--tmp-dir /tmp/kmc-tmp \
--output-dir /tmp/kmc-index \
--package kyma-docs-index.tar.gz
# Re-index without re-fetching (docs already downloaded)
uv run kyma-knowledge-mcp-build-index \
--skip-fetch \
--data-dir /tmp/kmc-data \
--output-dir /tmp/kmc-index看 docs_sources.json 获取完整的来源列表，或 e2e_docs_sources.json 举个最小的例子。
所有选项
| 选项 | 默认值 | 描述 |
|---|---|---|
--sources | kyma_knowledge_mcp/indexing/docs_sources.json | 源JSON文件的路径 |
--data-dir | ./data/user | 用于存储提取的用户文档标记文件的目录 |
--contributor-data-dir | ./data/contributor | 用于存储提取的贡献者标记文件的目录 |
--tmp-dir | ./tmp | git克隆的临时目录 |
--output-dir | ~/.kyma-knowledge-mcp/index | ChromaDB输出目录（两个集合都写在这里） |
--embed-model | BAAI/bge-small-en-v1.5 | fastembed模型名称 |
--package | _（空）_ | 如果已设置，则创建 .tar.gz 在此路径上存档 |
--skip-fetch | false | 跳过获取并重用现有 --data-dir |
--log-level | INFO | 日志记录级别 |
使用本地索引
构建后，通过设置将服务器指向索引 LOCAL_INDEX_PATH 在你的 .env:
LOCAL_INDEX_PATH=/tmp/kmc-index # directory produced by --output-dir
# or
LOCAL_INDEX_PATH=/tmp/kyma-docs-index.tar.gz # archive produced by --package要返回自动下载的索引，请删除该行。
______________________________________________________________________
发展
git clone https://github.com/danjiawork/kyma-knowledge-mcp
cd kyma-knowledge-mcp
uv sync
uv run pytest # runs all unit and integration tests