企业官网建设流程全解析

Klavis CLI 深度解析：用 klavis 命令在 Google Gemini CLI 中管理 Klavis MCP 服务器

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本文围绕 examples/google_gemini_cli-klavis/README.md 讲解 Klavis 官方提供的klavis命令行工具：它能把 Klavis AI 托管的 MCP（Model Context Protocol）服务器一键注册、移除、列出或清空 Google Gemini CLI 的配置（~/.gemini/settings.json），并自动备份配置。读完本文，你将掌握该工具的全部命令用法、写入配置的 JSON 结构，以及 index.js 源码中参数解析、域名校验、备份与容错读取等关键实现细节。

工具定位：为什么需要 klavis CLI

Gemini CLI 通过~/.gemini/settings.json中的mcpServers字段加载 MCP 服务器。手工编辑该文件容易引入 JSON 语法错误，且无法批量管理多个 Klavis 集成（Gmail、Slack、Notion 等）。klavisCLI 解决的就是这个问题：

• 自动定位并创建~/.gemini/settings.json配置目录；
• 修改前先自动备份，只保留最近一份备份文件；
• 只管理域名包含klavis.ai的条目，避免误删用户手工配置的其他 MCP 服务器；
• 对既有配置中的尾部逗号、未加引号键名等常见 JSON 瑕疵做了容错处理，保留其余全部用户偏好与认证信息。

README 的 "What It Does" 部分概括了四步工作流：定位配置 → 备份 → 增删列清 → 保留既有偏好。下文先给出完整用法，再结合源码逐层拆解。

安装

工具通过 npm 全局安装（发布包名为klavis）：

npm install -g klavis

package.json 中声明了入口与运行环境约束：

{ "name": "klavis", "version": "1.0.0", "bin": { "klavis": "./index.js" }, "engines": { "node": ">=14.0.0" }, "files": ["index.js", "README.md"] }

从 package.json#L8-L13 可见：bin字段把klavis命令映射到 index.js（该文件首行带有#!/usr/bin/env nodeshebang，因此无需额外的构建或打包步骤）；engines要求 Node.js 14.0.0 及以上；files字段说明发布产物只有入口脚本和 README 两个文件，是一个零第三方依赖的单文件 CLI。

命令总览与帮助

klavis gemini --help

源码中的 showHelp() 会输出完整帮助信息，命令面固定为四种子命令（加--help）：

main() 的入参校验 对每个子命令都做了防御：

• 第一个位置参数必须是gemini，第二个必须是add/remove/list/clear/help之一，否则打印用法并以退出码 1 终止；
• add与remove缺少第三个参数（URL 或名称）时直接报错；
• clear未带--force时拒绝执行，这是刻意的安全设计，防止一次手滑清空所有集成。

添加 MCP 服务器：add 子命令

用法

klavis gemini add <INSTANCE_URL>

<INSTANCE_URL>是你在 Klavis 控制台中获得的 MCP 实例 URL。README 中给出的典型示例：

# 添加 Gmail MCP Server klavis gemini add https://gmail-mcp-server.klavis.ai/mcp/?instance_id=your-id # 添加 Slack MCP Server klavis gemini add https://slack-mcp-server.klavis.ai/mcp/?instance_id=your-id # 添加 Notion MCP Server klavis gemini add https://notion-mcp-server.klavis.ai/mcp/?instance_id=your-id

参数约束（源码印证）

add 分支的参数处理 施加了三道校验：

1. 协议前缀：URL 必须以http开头，否则提示Invalid URL format；
2. 域名格式：用正则https?:\/\/([^.]+)\.klavis\.ai提取子域名，例如gmail-mcp-server.klavis.ai提取出gmail-mcp-server并转小写作为mcpServers下的键名。不匹配该模式的 URL 会直接报错Expected pattern: https://SERVICE-mcp-server.klavis.ai/；
3. 归属校验：URL 必须包含klavis.ai，该工具只接受 Klavis AI 的 MCP 服务器——这也是 README 中反复强调的 "Only Klavis AI MCPs can be added with this tool" 的落地位置。

URL 中的instance_id查询参数是实例标识，与 Klavis API 中 OAuth 流程的instance_id参数（见 openapi.json 中的 Start OAuth flow 描述）同属一套实例寻址体系；实例 URL 的获取方式参见 Gemini CLI 官方配置指南中"Get Strata Server URL"一节的 Dashboard 操作步骤。

写入配置的 JSON 结构

执行add成功后，源码 会把条目写入~/.gemini/settings.json的mcpServers下（写入前自动调用createBackup）：

{ "mcpServers": { "gmail": { "command": "npx", "args": ["mcp-remote", "https://gmail-mcp-server.klavis.ai/mcp/?instance_id=your-id"] } } }

这里的关键设计是npx mcp-remote <url>：Gemini CLI 以 stdio 方式启动本地子进程，mcp-remote充当远程桥接器，把 Klavis 托管的 HTTP MCP 端点转成本地 stdio 会话。因此运行环境除了 Node.js 之外，首次使用时还需能访问 npm registry 拉取mcp-remote包。这与 Klavis 知识库中 Claude Code 的npx mcp-remote用法是同一套远程接入模式（参见 claude_code.mdx）。

如果settings.json尚不存在，getSettingsPath() 会先创建~/.gemini目录再操作文件，因此首次add无需手工初始化。

移除与清空：remove / clear 子命令

# 移除指定 MCP（名称需与 mcpServers 中的键一致） klavis gemini remove gmail klavis gemini remove slack # 清空所有 Klavis AI MCP（必须带 --force） klavis gemini clear --force

两个子命令的安全边界都由 isKlavisAiService() 划定：它读取目标条目的args[1]（即 URL 位置），只有 URL 中包含klavis.ai才判定为 Klavis AI 服务：

• remove：先检查条目是否存在，再检查它是否为 Klavis AI 服务，非 Klavis 条目会被明确拒绝（is not a Klavis AI service and cannot be removed with this tool），从而保护了用户手工添加的其他 MCP 配置；
• clear：只遍历并删除 通过isKlavisAiService过滤出的条目，其余mcpServers键原样保留；若没有可清空的条目，直接提示 "configuration is already empty" 并退出，不产生任何写入。

两者在修改前都会调用备份函数，且clear的--force强制要求由命令行校验层保证。

列出已配置服务器：list 子命令

klavis gemini list

list 分支 遍历mcpServers的所有键，用isKlavisAiService过滤后按序号打印名称与总数。注意它只列出 Klavis AI 的条目，不会暴露配置中其他来源的 MCP 名称——这与该工具"只管 Klavis 集成"的定位一致。若结果为空，会提示使用klavis gemini add <INSTANCE_URL>添加。

备份与 JSON 容错：两个防错机制

自动备份策略

createBackup() 的行为细节值得注意：

• 备份文件命名为settings.json.bak.<毫秒时间戳>，与配置同目录存放；
• 每次修改（add、remove、clear）前执行一次备份；
• 备份后清理旧备份，仅保留最近 1 份（按文件名中的时间戳降序排序，删除其余）；
• 清理过程出错时被静默忽略，不影响主流程——备份是辅助能力，不能反过来阻塞配置修改。

这意味着误操作（例如clear --force后立即发现删多了）时，可以用最近一份.bak文件恢复，但只有一份历史快照，多次操作后更早的状态不可找回。

读取时的 JSON 修复

settings 读取逻辑 在JSON.parse之前做两次正则清洗：

1. /(,(\s*[}\]])/g → $1：删除}/]前的尾随逗号；
2. /(([{,]\s*)([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/g → $1"$2":：把未加引号的键名补上双引号。

这是针对用户手工编辑settings.json时最常见的两类 JSON 瑕疵的容错。若清洗后仍解析失败，工具会打印原始错误信息并提示手工修复配置文件，而不是带着损坏状态继续写入——这一点保证了"保留既有偏好"承诺的可靠性。

参数解析的实现

index.js#L6-L19 的 parseArgs() 是一个极简的手写解析器：以--开头的记为 flag（若下一个参数不以-开头则作为该 flag 的值，否则值为布尔true），其余收集为位置参数。由此带来两个使用注意：

• --force这类布尔旗标只能出现在位置参数之后解析，且不与位置参数混用（add的 URL 本身就是位置参数）；
• URL 中若含?instance_id=...这类查询串不需要额外转义，因为它整体作为一个 argv 元素传入。

使用前提与限制

综合 README 的 Requirements 部分 与源码行为，适用前提与边界如下：

• 环境：Node.js ≥ 14.0.0；已安装 Google Gemini CLI（或至少存在/可创建.gemini配置目录）；
• 归属限制：add只接受https://<service>.klavis.ai形态的 URL；remove/clear/list只对 URL 含klavis.ai的条目生效；
• 安全约束：clear必须带--force；备份只保留最近 1 份；
• 运行时依赖：配置写入后，Gemini CLI 实际调用 MCP 时需要npx mcp-remote可用，即机器需能执行 npx 并拉取该桥接包；
• 配置生效：与手工修改~/.gemini/settings.json相同，需要重启 Gemini CLI 才能加载新增的 MCP 服务器（这一点在 Gemini CLI 官方配置指南的验证步骤中也有明确说明：在 Gemini CLI 中执行/mcp命令查看工具加载情况）。

与手工配置流程的对照

如果不使用klavisCLI，等效的手工流程是：在 Klavis Dashboard 授权目标服务器、复制服务器 URL，然后把它以npx mcp-remote <URL>的形式追加进~/.gemini/settings.json的mcpServers（完整手工步骤见 docs/knowledge-base/use-mcp-server/gemini_cli.mdx）。klavis gemini add本质上把这条手工路径自动化了，并额外提供了备份、Klavis 归属校验与批量清理能力。两者写入的配置结构完全一致，因此可以混用：手工添加的 Klavis 条目同样能被list看到、被remove移除（前提是其args[1]位置包含klavis.ai的 URL）。

排障速查

结合工具输出与官方排障建议，常见问题定位如下：

• Invalid URL format：add传入的 URL 不是http(s)开头或域名不符合*.klavis.ai模式，请从 Klavis Dashboard 重新复制完整实例 URL；
• Service not found：remove的名称必须与mcpServers中已有的键完全一致，可先用klavis gemini list核对；
• is not a Klavis AI service：该条目 URL 中不含klavis.ai，工具拒绝操作，需手工编辑~/.gemini/settings.json处理；
• Error reading existing settings：settings.json存在超出两种容错范围之外的 JSON 错误，需按提示手工修复后重试；
• 添加后 Gemini CLI 中工具未出现：核对 URL 拼写、检查网络连通性、确认 Klavis Dashboard 中认证有效，并完全重启 Gemini CLI 后用/mcp查看加载状态（参考 gemini_cli.mdx 的 Troubleshooting 一节）。

小结

klavis是一个零依赖、单文件（index.js）的 npm CLI，以add/remove/list/clear四个子命令覆盖 Gemini CLI 中 Klavis MCP 集成的全生命周期管理；其实现上的三个要点——域名白名单（isKlavisAiService）、修改前滚动备份（createBackup）与读取时 JSON 容错——共同保证了"只动 Klavis 条目、随时可回滚"的行为边界。配合 README.md 中的命令示例与 Gemini CLI 配置指南，即可在终端内完成从集成注册到验证使用（/mcp）的完整闭环。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis