infra-mcp-runtime
v1.0.14
Published
Obfuscated runtime package for Infra MCP.
Readme
Infra MCP
Infra MCP 是一个独立运行的 HTTP MCP Server,用于让 AI 按项目隔离访问服务端配置的 SQL、Redis 和部署环境 Linux 命令行。SQL 当前支持 MySQL 和 PostgreSQL。
真实连接信息只保存在用户空间目录 ~/.infra-mcp/infra-mcp.server.config.json 中。客户端 infra-mcp.client.config.json 只包含 projectName、projectKey 和 prompt,不配置环境字段或连接凭据。同一项目共用数据库连接时使用一段 JSON;不同连接分成多段,使用服务端生成的对应项目 Key。prompt 说明开发库、生产库等用途,执行权限由服务端按实际库名控制。
功能说明
sql_list_databases:返回项目当前连接下已配置的全部库名、用途及 SQL 执行权限。sql_list_tables:列出指定数据库的表,最多返回 400 条。sql_select:只允许执行单条SELECT查询,返回记录最多 400 条。sql_execute(兼容别名mysql_execute):仅在目标库允许 SQL 执行时运行单条语句;工具说明要求 AI 归档生产需要的 SQL,并维护文件执行记录。mysql_*兼容别名:保留mysql_list_databases、mysql_list_tables、mysql_select,仅支持目标环境的连接引擎为mysql。redis_list_databases:列出项目当前 Redis 连接下配置的数据库编号和用途。redis_query:通过可选database选择编号,只允许执行 Redis 只读命令白名单;多编号时必须指定。linux_exec:通过 SSH 执行结构化部署环境 Linux 命令;单命令传program、args、cwd、explanation,多命令传commands数组,不要用bash -lc或sh -c包装多条命令。只读诊断命令命中白名单会直接执行,有副作用或未知命令会在网页控制台触发人工确认。- 网页控制台:访问
http://127.0.0.1:3120/console查看 SQL、Redis、Linux 三类输入输出,维护 Linux 风险类型审批策略,并通过动态表单编辑保存~/.infra-mcp/infra-mcp.server.config.json。
使用方式
安装 Node.js 20 或更高版本。
全局安装运行版包:
npm install -g infra-mcp-runtime直接启动服务端:
infrainfra等同于infra start,默认会在后台守护进程中运行,启动成功后终端可以关闭。安装完成后会自动执行初始化;首次启动时如果~/.infra-mcp不存在模板文件,也会自动创建默认模板。服务管理命令:
infra start infra stop infra restart infra status infra log infra help其中
infra stop用于停止后台服务,infra status用于查看运行状态和进程 PID,infra restart用于重启服务,infra log用于查看最近日志,infra help用于查看命令帮助。如果需要前台运行,可以使用:
infra --foreground前台运行时需要保持当前终端窗口打开;停止服务时按
Ctrl+C,或关闭当前终端窗口。配置文件会保存在用户空间目录
~/.infra-mcp下。Windows 默认路径示例:
%USERPROFILE%\.infra-mcp\infra-mcp.server.config.jsonmacOS / Linux 默认路径示例:
~/.infra-mcp/infra-mcp.server.config.json客户端模板路径与它位于同一目录:
~/.infra-mcp/infra-mcp.client.config.json打开网页控制台配置服务端:
http://127.0.0.1:3120/console网页控制台按“服务器 → 数据库连接 → Redis 连接 → 项目”配置:共享服务器在
servers中维护,数据库连接在sqlConnections中维护。新增项目后关联服务器并填写部署目录,分别为生产、测试、开发库选择连接、填写库名、勾选允许 SQL 执行。SQL 三个环境可使用同一连接或不同连接;权限默认关闭,未勾选仍可只读查询。Redis 连接在redisConnections中维护,项目的redisEnvironments分别填写连接引用和数据库编号,全部只读。详见 共享连接配置。保存项目后,从控制台“客户端模板”复制配置到业务项目根目录的
infra-mcp.client.config.json。也可通过infra_list_projects获取各连接对应的clientConfig。开发库和生产库共用连接时,一段 JSON 即可:{ "projectName": "订单服务", "projectKey": "order-service", "prompt": "order_dev 是开发库,order_prod 是生产库。生产库仅用于只读排查;先列出可用库,再按任务选择库名。执行权限以服务端配置为准。" }使用不同数据库连接时分为两段。下面假设服务端连接标识分别为
dev-db和prod-db;实际项目 Key 请直接复制服务端生成的值:[ { "projectName": "开发环境", "projectKey": "order-service::dev-db", "prompt": "这是给 Agent 工具使用的额外自然语言说明:当前环境用于开发调试,常用数据库为 order_dev,Redis key 通常以 order:dev: 开头;查询前先确认表含义,不要填写账号密码、token 等敏感信息。" }, { "projectName": "生产环境", "projectKey": "order-service::prod-db", "prompt": "order_prod 是生产库,只做必要的只读排查,执行权限由服务端关闭。" } ]在 MCP 客户端中使用下面的 HTTP 地址连接本服务:
http://127.0.0.1:3120/mcpAgent 先读取客户端配置,按
prompt选择连接入口并传入projectKey,使用sql_list_databases查看可用库。其他 SQL 工具通过可选database参数指定本次目标库;MySQL 也可根据 SQL 中明确的库限定符选择目标。只有一个可用库时可省略,多库且目标不明确时拒绝执行。SQL 中跨库引用会被拒绝;prompt 不能开启服务端关闭的权限。控制台模板由已保存项目生成,不会自动覆盖业务项目根目录的配置。
SQL 文件执行记录
开发库开启 AI 执行权限后,工具说明要求 AI 在该库维护 infra_sql_file_history,不存在则创建,记录文件路径、内容校验值、执行状态、逐条结果和时间。需要生产执行的正式变更保存在业务项目的 docs/sql,每份文件末尾必须包含缺表初始化和本文件成功登记 SQL。
生产库保持 MCP SQL 执行权限关闭。你手动执行交付的 SQL 文件时,先运行业务 SQL,再由文件内的记账 SQL 自动记录实际生产库名和执行时间,无需另跑登记脚本。执行器必须设置为遇错立即停止,避免业务失败后仍执行末尾成功登记。
查看发布进度时,对比本地文件清单与对应库的成功记录;生产库不需要预存“待执行”记录。开发执行成功不等于生产已执行,历史文件没有记录时需要先核实。该流程由 MCP 工具提示词指导 AI 生成文件和维护台账,详见数据库查询与受控执行。
本地开发怎么看效果
修改
public/index.html、public/app.js、public/styles.css这类网页控制台静态资源后,直接刷新http://127.0.0.1:3120/console就能看到效果;服务端会在请求/console、/console/app.js、/console/styles.css时直接读取仓库里的public/目录。修改
src/*.ts这类后端逻辑后,需要重新编译再重启服务,因为实际运行的是dist/index.js。推荐执行:npm run build infra restart修改工具逻辑后,除了刷新控制台页面,还需要重新触发一次对应的 MCP 请求,或者重新在客户端里调用一次 SQL、Redis、Linux 工具,才能看到新的运行效果。
如果只是修改
~/.infra-mcp/infra-mcp.server.config.json里的项目连接信息,一般保存后重新调用工具即可;如果修改的是http.host、http.port、http.path这类监听参数,则需要重启服务后才会生效。日常开发时可以按这个节奏操作:改前端就刷新
/console,改后端就执行npm run build && infra restart,改完功能再执行npm test做一次验证。
Codex 配置方式
在 Codex 的用户配置文件中添加 Infra MCP 服务配置。Windows 默认路径为:
%USERPROFILE%\.codex\config.toml示例:
[mcp_servers.infra-mcp]
type = "streamable_http"
url = "http://127.0.0.1:3120/mcp"
startup_timeout_ms = 20000
tool_timeout_sec = 60
enabled = true如果 ~/.infra-mcp/infra-mcp.server.config.json 中修改过 http.port 或 http.path,需要同步修改上面 url 的端口或路径。保存后重启 Codex,或在 Codex 中重新加载 MCP Server。使用前只需要保持 infra 启动的服务进程正在运行。
Codex 配置文件只写 MCP 服务地址,不写数据库、Redis 或 SSH 账号密码。业务项目根目录放置 infra-mcp.client.config.json,其中 projectKey 使用控制台模板或项目发现工具生成的入口值。
安全说明
- SQL 默认只读;仅目标库的
allowSqlExecute开启时允许通过执行工具提交单条写入或 DDL,生产库可保持关闭并由用户手动执行交付文件。 - Redis 只开放白名单内的只读命令。
- Linux 自动执行只允许结构化命令格式化后的简单命令或只读白名单命令组成的管道。
- Linux 命令包含
sudo、多语句、重定向、后台执行、命令替换、未知命令或疑似副作用操作时,会在网页控制台等待人工确认。 - Linux 审批弹窗会按列表显示待执行命令和 Agent 提供的
explanation,触发审批的命令会用红色强调。 - Linux 审批按风险类型控制,策略保存在用户空间目录的
~/.infra-mcp/infra-mcp.approval-policy.json。在网页取消某个风险类型的“需要审批”后,同类型命令后续会按策略免审批执行。 - 不要把 HTTP 服务监听到不可信网络。
