Ops Kit

把公司的日志、数据库、缓存、配置中心接到 Cursor / Codex 里，让 AI 直接帮你查，不用自己翻控制台。

这份说明分成两块：

1. 上半部分：给完全没用过的人。照着做就能在自己电脑上用起来。
2. 下半部分：给要改、要复用、要接到自己公司的人。讲这个底子是怎么做的、能干什么、哪里适合改。

源码里没有公司地址、账号、密码。每台电脑自己填一份 .env，不要把这份文件发给别人。

---

上半部分：小白上手

这东西装好之后能干什么

在 Cursor 或 Codex 里直接问，例如：

• 「帮我查一下刚才那次登录失败的日志」
• 「测试库里这个用户有没有这条订单」
• 「Redis 里这个 key 现在是什么」
• 「Nacos 里这份配置现在是什么内容」

AI 会通过本机的 MCP 去查，不需要你再开网页、登堡垒机、复制 SQL。

你不需要先搞懂 MCP 是什么。把它理解成：给 AI 装了几个只给本机用的查询插件。

开始前准备这三样

在终端里分别执行，有版本号输出就行：

python3 --version    # 需要 3.9 或更高
node --version       # 需要 18 或更高
npm --version
ssh -V

没有的话：

• Python：从 python.org 安装，Windows 请勾选 Add Python to PATH
• Node.js：从 nodejs.org 安装 18 或更高
• SSH：Mac 自带；Windows 在「可选功能」里打开 OpenSSH 客户端

本机还要有 Cursor 或 Codex（或两个都有）。

如果上面这些你也不想自己装，可以把这个文件夹连同这篇说明一起丢给 AI，让它按「上半部分」一步步带你做。

一共就四步

1. 复制一份配置文件
2. 只打开你要用的中间件，把账号填进去
3. 跑一键安装
4. 完全退出并重新打开 Cursor / Codex，然后直接问

第 1 步：做出自己的配置文件

配置只写在一个地方：项目根目录的 .env。模板是 .env.example，不要改模板，复制一份来填。

Mac / Linux：

cd /你的路径/ops-mcp-kit
cp .env.example .env
open -e .env

Windows（PowerShell）：

Set-Location C:\你的路径\ops-mcp-kit
Copy-Item .env.example .env
notepad .env

打开后你会看到很多 ENABLE_...=false。
默认全是关的。 只用哪个，就把哪个改成 true，并填写那一组下面的内容。关掉的不用填，也不会装上去。

填完请保存。.env 里是密码，不要提交 Git，不要发聊天，不要截图。

第 2 步：按中间件填写

下面每一种都写了：它是干什么的、去哪拿账号、要填哪些项、填完长什么样。
只看你要用的那几段，其他可以当没看见。

---

阿里云日志 SLS

干什么： 让 AI 查阿里云日志（报错、接口调用、登录失败之类）。

去哪拿： 阿里云控制台 → 访问控制 RAM → 建一个只读用户 → 创建 AccessKey。
地域在 SLS 控制台，点进你的 Project 就能看到，例如 cn-hangzhou、cn-shenzhen。

要填：

项	含义	怎么填
ENABLE_ALIYUN_SLS	要不要接 SLS	改成 true
ALIBABA_CLOUD_ACCESS_KEY_ID	AccessKey ID	RAM 里复制
ALIBABA_CLOUD_ACCESS_KEY_SECRET	AccessKey Secret	RAM 里复制，只显示一次
SLS_REGIONS	日志所在地域	默认 cn-hangzhou，多个用逗号：cn-hangzhou,cn-shenzhen
SLS_NETWORK	走公网还是内网	笔记本一般填 public；公司内网机器填 vpc

示例：

ENABLE_ALIYUN_SLS=true
ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI5t........
ALIBABA_CLOUD_ACCESS_KEY_SECRET=........
SLS_REGIONS=cn-hangzhou
SLS_NETWORK=public

查不到日志时，九成是地域填错了，不是工具坏了。

---

MySQL 测试库 / 预发库（直连）

干什么： 电脑能直接连上的 MySQL，通常是测试库、预发库。

去哪拿： 找负责 DBA / 运维要只读账号，以及地址、端口、库名。不要用 root，不要用生产账号。

要填：

项	含义	怎么填
ENABLE_MYSQL_DIRECT	要不要接这套直连库	true
MYSQL_DIRECT_HOST	数据库地址	主机名或 IP
MYSQL_DIRECT_PORT	端口	一般是 3306
MYSQL_DIRECT_USER	用户名	只读账号
MYSQL_DIRECT_PASSWORD	密码	原样填写
MYSQL_DIRECT_DATABASE	库名	例如 app
MYSQL_DIRECT_SSL	是否强制 SSL	对方要求加密再改 true，否则保持 false
MYSQL_DIRECT_ALLOW_INSERT/UPDATE/DELETE	是否允许改数据	保持 false。真要在测试库改数，再单独开

示例：

ENABLE_MYSQL_DIRECT=true
MYSQL_DIRECT_HOST=mysql-test.example.com
MYSQL_DIRECT_PORT=3306
MYSQL_DIRECT_USER=readonly_user
MYSQL_DIRECT_PASSWORD=replace_me
MYSQL_DIRECT_DATABASE=app

测试库和活动库要同时接？看下半部分「多实例」。小白先接一套就够。

---

Redis 测试库 / 预发库（直连）

干什么： 让 AI 读测试 Redis 里的 key。

去哪拿： 运维给的 Redis 地址和密码。

要填：

项	含义	怎么填
ENABLE_REDIS_DIRECT	要不要接	true
REDIS_DIRECT_URL	连接串	redis://:密码@地址:6379/0
REDIS_DIRECT_PERMISSIONS	权限	保持 ["read"]。只有明确要写缓存时才改成 ["read","write"]

密码里如果有 @、:、/、#、?，要先做 URL 编码，否则会连错。

示例：

ENABLE_REDIS_DIRECT=true
REDIS_DIRECT_URL=redis://:[email protected]:6379/0
REDIS_DIRECT_PERMISSIONS=["read"]

---

跳板机 SSH（接生产前先看）

生产 MySQL / Redis 一般不能从你的笔记本直连，要先登录跳板机。
本工具不支持把 SSH 密码写进配置，只用密钥或 SSH Agent。

去哪拿： 运维给你的跳板机账号，以及本机私钥，例如 ~/.ssh/id_ed25519。

要填（生产 MySQL 或 Redis 只要开一个，就要填这一组）：

项	含义	怎么填
SSH_HOST	跳板机地址	主机名或 IP
SSH_PORT	SSH 端口	一般是 22
SSH_USER	跳板机用户名	例如 ops
SSH_IDENTITY_FILE	私钥路径	必须是绝对路径

先在终端试一次，能进去再装：

ssh -i /Users/你/.ssh/id_ed25519 用户名@跳板机地址

第一次会问 Are you sure you want to continue connecting，输入 yes。
这台电脑上没成功登录过，安装时生产隧道也会失败。

示例：

SSH_HOST=jump.example.com
SSH_PORT=22
SSH_USER=ops
SSH_IDENTITY_FILE=/Users/你/.ssh/id_ed25519

Windows 路径写成：C:/Users/你/.ssh/id_ed25519。

---

生产 MySQL（走 SSH，强制只读）

干什么： 通过跳板机查生产库。工具会禁止增删改和建表删表。

去哪拿： 生产只读账号，以及从跳板机看的数据库内网地址（不是你笔记本直接访问的地址）。

要填： 上面的 SSH 一组，再加上：

项	含义	怎么填
ENABLE_MYSQL_SSH	要不要接生产库	true
REMOTE_MYSQL_HOST	跳板机后面的 MySQL 地址	内网主机名或 IP
REMOTE_MYSQL_PORT	端口	一般 3306
MYSQL_SSH_USER	数据库用户	只读账号
MYSQL_SSH_PASSWORD	数据库密码
MYSQL_SSH_DATABASE	库名

示例：

ENABLE_MYSQL_SSH=true
REMOTE_MYSQL_HOST=mysql.prod.internal
REMOTE_MYSQL_PORT=3306
MYSQL_SSH_USER=readonly_user
MYSQL_SSH_PASSWORD=replace_me
MYSQL_SSH_DATABASE=app

---

生产 Redis（走 SSH，强制只读）

干什么： 通过跳板机读生产 Redis。密码可以没有。

要填： SSH 一组，再加上：

项	含义	怎么填
ENABLE_REDIS_SSH	要不要接	true
REMOTE_REDIS_HOST	跳板机后面的 Redis 地址	内网地址
REMOTE_REDIS_PORT	端口	一般 6379
REDIS_SSH_PASSWORD	Redis 密码	没有就留空
REDIS_SSH_DATABASE	DB 编号	一般 0

示例：

ENABLE_REDIS_SSH=true
REMOTE_REDIS_HOST=redis.prod.internal
REMOTE_REDIS_PORT=6379
REDIS_SSH_PASSWORD=replace_me
REDIS_SSH_DATABASE=0

---

Nacos 配置中心（只读）

干什么： 让 AI 读配置、列配置、列命名空间。没有发布、没有删除。

去哪拿： Nacos 控制台地址、登录用户名密码、命名空间 ID（就是控制台里那一长串，不是显示名）。

要填：

项	含义	怎么填
ENABLE_NACOS_READONLY	要不要接	true
NACOS_SERVER_ADDR	地址	host:8848 或 http://host:8848 或 https://host，不要带多余路径
NACOS_CONTEXT_PATH	上下文	一般是 /nacos
NACOS_NAMESPACE	命名空间 ID	公共空间可留空
NACOS_GROUP	分组	常用 DEFAULT_GROUP；想列出全部分组就留空
NACOS_USERNAME / NACOS_PASSWORD	登录账号	开了鉴权就要填

示例：

ENABLE_NACOS_READONLY=true
NACOS_SERVER_ADDR=nacos.example.com:8848
NACOS_CONTEXT_PATH=/nacos
NACOS_NAMESPACE=
NACOS_GROUP=DEFAULT_GROUP
NACOS_USERNAME=nacos
NACOS_PASSWORD=replace_me

---

第 3 步：装载到本机 AI 工具

.env 保存好后，在项目目录执行。

Mac / Linux：

bash install-ops-mcp.sh

Windows：

powershell -ExecutionPolicy Bypass -File .\install-ops-mcp.ps1

安装脚本会：

1. 检查你填的配置
2. 把运行文件拷到本机用户目录
3. 下载 MCP 依赖
4. 探测你刚启用的服务能不能连上
5. 把配置写进 Cursor 和 Codex（已有的其他 MCP 不会被删掉，只管理名字以 ops- 开头的）

看到「完成。请完全退出并重新打开 Cursor/Codex。」就对了。

想先检查、先不改电脑上的文件：

bash install-ops-mcp.sh --dry-run

网络暂时不通、只想先把配置写进去：

bash install-ops-mcp.sh --skip-probe

以后改了 .env，再跑一遍同样的安装命令就会更新。

第 4 步：重启 AI 工具，直接用

必须完全退出再打开 Cursor / Codex。只关窗口往往不够，MCP 还是旧的。

打开后：

• Cursor：设置里找 MCP，应能看到 ops-mysql-direct、ops-aliyun-sls 这类名字，状态是已连接 / 绿灯
• Codex：对应 MCP 列表里同样会出现

然后直接问，例如：

• 「用 ops-mysql-direct 查一下 users 表有哪些字段」
• 「帮我看最近 15 分钟 SLS 里的 ERROR」
• 「读一下 Nacos 里 dataId=xxx 的配置」

装好后，配置已经在你这台电脑的 AI 工具里，日常使用不用再进这个项目文件夹。只有换账号、换库、换机器时才回来改 .env 再装一次。

装完东西在哪（一般不用手改）

系统	运行文件	Cursor	Codex
Mac / Linux	~/.local/share/ops-mcp-kit	~/.cursor/mcp.json	~/.codex/config.toml
Windows	%LOCALAPPDATA%\ops-mcp-kit	%USERPROFILE%\.cursor\mcp.json	%USERPROFILE%\.codex\config.toml

每次覆盖前都会在同目录留一份带时间戳的备份。

常见问题（先看这里）

提示找不到 Python / Node
先在当前这个终端里执行 python3 --version、node --version。有输出再跑安装。装完 Node 后请新开一个终端。

安装说连通性探测失败
说明账号、网络或跳板机还不通。先自己用常规客户端连一下（Navicat、redis-cli、浏览器打开 Nacos、ssh 用户@跳板机）。确认能通再装。实在要先写配置：--skip-probe。

SLS 能启动但查不到 Project
把 SLS_REGIONS 改成日志真实所在地域。国内常见是 cn-hangzhou，不是海外区。

SSH 隧道失败
先单独 ssh -i 私钥 用户@跳板机。要确认：指纹已经 yes 过、私钥权限不是太开放（Mac 上通常要 chmod 600）、跳板机能访问后面的 MySQL/Redis。

Cursor 里 MCP 是红的 / 找不到

1. 完全退出再打开
2. 跑一次 bash install-ops-mcp.sh --dry-run 看缺了哪个变量
3. 看 Cursor / Codex 的 MCP 日志：常见是没重启、密码过期、账号没这个库的权限

Nacos 登录失败
NACOS_SERVER_ADDR 不要写成带 /nacos/index.html 的完整网页地址。地址和上下文路径是分开的。

我不会填，能不能让 AI 帮我
可以。把 .env.example 和这篇「上半部分」一起给它，告诉它你要用哪些中间件、账号在哪。不要把填好的 .env 发给任何人，包括群里的同事截图。

---

下半部分：底子说明（给要改、要复用的人）

上半部分保证「能用」。下面说明这个仓库实际是什么、实现上踩过哪些坑、接到另一家公司时该动哪里。

它在解决什么问题

运维查询场景很碎：SLS 控制台、Navicat、Redis Desktop、Nacos、跳板机。把这些接到 Cursor / Codex 后，排障可以在对话里完成。

直接把生产账号写进 MCP 很危险，所以这套东西刻意做成：

• 可带走的空壳：源码无公司 IP、无密钥
• 本机安装器：读 .env，生成 Cursor mcp.json 和 Codex config.toml
• 默认只读，生产更硬：测试可按开关放开写；生产 SSH 路径在脚本里再次钉死写权限
• 只管理 ops- 前缀：不碰你已经装的其他 MCP

它不是一个长期运行的网关服务，也不是公司统一的权限中台。权限的真正边界仍是 RAM、数据库账号、跳板机账号。MCP 层限制只是多加一道刹车。

装载时实际发生了什么

.env  +  config/mcp.template.json
        │
        ▼
install-ops-mcp.sh / .ps1
        │
        ▼
install_ops_mcp.py
        │  1. 解析 .env，检查 Node ≥ 18
        │  2. 按 ENABLE_* 和 *_INSTANCES 展开出要注册的 MCP
        │  3. 校验 SSH 私钥是否存在、权限是否过宽
        │  4. 复制 bin/ 和 package.json 到本机 runtime
        │  5. npm install（可用 --skip-npm-install）
        │  6. ops_mcp_probe.py 探测连通性（可用 --skip-probe）
        │  7. 合并写入 Cursor / Codex，并做时间戳备份
        ▼
~/.local/share/ops-mcp-kit          运行时（Node MCP + 隧道脚本）
~/.cursor/mcp.json                  Cursor 里能看到的插件列表
~/.codex/config.toml                用标记块包住，可重复安装

探测在写客户端配置之前做。失败就中止，避免「MCP 是绿的，一查就超时」。

目录里每个文件干什么

ops-mcp-kit/
├── .env.example              唯一需要照着填的模板；真正生效的是你复制出来的 .env
├── config/mcp.template.json  六种 MCP 的 command/args/env 模板，含 ${VAR:-default} 展开
├── bin/
│   ├── run-mysql-mcp-with-ssh.sh/.ps1   先起 SSH 隧道，再拉起 MySQL MCP，并强制只读
│   ├── run-redis-mcp-with-ssh.sh/.ps1   同上，Redis 用 HOST/PORT/PASSWORD，不拼 URL
│   ├── ssh-tunnel-common.sh/.ps1        分配本地端口、拉起 ssh -N -L、健康检查、隧道断开则退出 MCP
│   ├── nacos-mcp-server-ro.mjs          自写的只读 Nacos MCP，没有 publish/delete
│   └── probe-mysql.mjs                  安装探测用，对 MySQL 执行 SELECT 1
├── install_ops_mcp.py        跨平台安装核心：解析、展开多实例、写配置、调探测
├── ops_mcp_probe.py          SLS / Redis / Nacos / SSH 隧道 / MySQL 的连通性探测
├── install-ops-mcp.sh        Mac/Linux 入口，要求 python3
├── install-ops-mcp.ps1       Windows 入口，优先 py -3
├── package.json              钉死的 Node 依赖 + overrides
├── package-lock.json         锁定传递依赖，保证各人装到同一套包
└── tests/                    安装器与探测辅助函数的单元测试

第三方 MCP 本身不在这个仓库里维护，安装时下到 runtime：

服务	包	说明
SLS	aliyun-sls-mcp	查 Project / Logstore / 日志 / SQL
MySQL	@benborla29/mcp-server-mysql	直连和 SSH 包装共用；写权限靠环境变量
Redis	@easy-mcps/redis-mcp-server	MCP_PERMISSIONS 控制工具是否出现
Nacos	仓库内 nacos-mcp-server-ro.mjs	只用 MCP SDK + Nacos HTTP API
探测 MySQL	直接依赖 mysql2	避免只能测端口、测不到账号

实现上值得注意的细节

配置展开
模板用 ${NAME} / ${NAME:-default}。空字符串视为未填。关掉的 ENABLE_* 不会去要凭据。
多实例：MYSQL_DIRECT_INSTANCES=test,activity 会生成 ops-mysql-direct-test 和 ops-mysql-direct-activity。命名实例的变量是 MYSQL_DIRECT_ACTIVITY_HOST 这种，映射回模板里的 MYSQL_DIRECT_HOST。没写的字段继承默认实例（生产 SSH 因此可以共用一套 SSH_*）。default 这个实例名表示继续用未加前缀的那组变量。

SSH 隧道
不用第三方 MCP 自带的隧道，自己包了一层，为的是：禁止密码登录、StrictHostKeyChecking=yes、生产写权限在包装脚本里再钉一次、隧道断了让 MCP 进程退出以便客户端拉起。
SSH 的 stdin/stdout 与 MCP 的 stdio 隔离，避免协议被 ssh 输出污染。健康检查用 Python 探测端口，不依赖 nc。Windows 用后台监控，隧道死后杀掉 node。

生产只读
MySQL SSH：ALLOW_INSERT/UPDATE/DELETE/DDL=false，且 MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=false。
Redis SSH：MCP_PERMISSIONS=["read"]。
Nacos：代码里根本没有写接口。
这些都防不住「有人改已经生成的 mcp.json」。真正安全仍靠只读账号和 RAM。

探测

• MySQL：有 mysql2 时 SELECT 1，否则只测 TCP（dry-run 允许这种降级）
• Redis：标准库讲 RESP，AUTH + PING
• SLS：HMAC-SHA1 签 ListProject，不额外引阿里云 SDK
• Nacos：有用户名就先 login，再拉一页配置
• SSH 服务：先 ssh echo ok，再建临时隧道探后面的库

安全相关实现
安装日志会脱敏 password / secret / token / access key / redis URL。
私钥权限在 Unix 上若对组/其他人可读，直接拒绝。
Cursor / Codex 配置里仍然是明文环境变量，这是 MCP stdio 的常态，磁盘加密和家目录权限要自己管。

依赖
用 overrides 把 @modelcontextprotocol/sdk、undici、jsondiffpatch 钉到无高危版本。
MySQL MCP 还带着 mcp-evals / @ai-sdk/*，审计会剩一组 low。npm audit fix --force 会把 MySQL MCP 降级，不要跑。

优点

• 跨公司可复制：换环境只换 .env，不改代码
• 一键进 Cursor 和 Codex，且不覆盖别人的 MCP
• 生产路径默认只读，SSH 不用密码
• 多实例能覆盖「测试 + 生产 + 活动」这种常见拆分
• 安装时探测，减少「配好了但连不上」
• Mac / Windows 同一套逻辑

不足和边界

• 不是公司级权限系统。 不能按员工工号做审批，也不能代替数据库只读账号
• 凭据落在本机配置文件里。 离职必须在云平台和数据库侧撤账号，删 .env 不够
• 第三方 MCP 能力受上游限制。 SLS 包仍较早期；MySQL 包夹带评估依赖
• Nacos 只覆盖配置查询，没有服务发现、没有历史版本对比
• SSH 只按 OpenSSH 单跳来做。 更复杂的 ProxyJump 可以靠本机 ~/.ssh/config 的 Host 别名碰运气，没有一等公民支持
• 探测会打真实环境。 只读接口，但仍是网络请求；不通或不想打时用 --skip-probe
• 没有 Web UI。 小白的配置入口就是文本 .env
• 每种服务的「实例名」有限制：字母开头的字母数字，不能叫 host、password 这种字段名

别人接到自己公司时，建议怎么改

不要改着改着把密钥写进仓库。推荐按这个顺序定制：

1. 先不要改代码。 复制空仓库，新建 .env，用上半部分接一两种服务跑通。
2. 把公司约定写成 .env 注释或内部 wiki。 例如默认 SLS 地域、跳板机 Host 别名、测试库只读账号申请流程。这些属于公司知识，不属于这个开源空壳。
3. 多套库用 *_INSTANCES，不要复制多份仓库。 测试 / 生产 / 活动库是设计内的能力。
4. 需要接第 7 种系统时再改模板。 在 config/mcp.template.json 加一个 ops-xxx，enabled_env + 需要的变量，必要时在 INSTANCE_CONFIG（install_ops_mcp.py）登记多实例字段映射，在 ops_mcp_probe.py 加探测。名字必须继续以 ops- 开头。
5. 生产写权限不要靠改包装脚本打开。 若业务确实要在测试库写入，只用 MYSQL_DIRECT_ALLOW_* / REDIS_DIRECT_PERMISSIONS，并继续使用数据库侧最小权限账号。
6. 默认值按公司改。 例如把 .env.example 和模板里的 SLS_REGIONS 改成你们的主地域；Nacos 默认 group、上下文路径按实际改。
7. Node / Python 探测逻辑可以换成你们已有的堡垒机或 VPN 检查。 ops_mcp_probe.py 是独立模块，安装器在写配置前调用，替换成本低。
8. 不要把旧公司的 .env、mcp.json、config.toml 带到新公司。 只带走这个空项目。
9. 内部二次分发时，删掉你们自己的 .env，保留 .env.example。 安装器已经把 .env gitignore 了，但备份文件和聊天记录是另一回事。

一套务实的公司内部用法：这个仓库当「安装器 + 安全默认值」；真正的地址和账号放在每个人自己的 .env；若要做统一门户或审批，另起服务，不要把这个 kit 长成网关。