mcp-for-shell 开发者文档

开发者文档

这份文档用于帮助后续开发新功能、排查问题和修改现有行为。

1. 目录结构

源码副本的主要目录如下：

  • src/：后端服务实现
  • web/：前端静态页面
  • config/：默认配置文件目录
  • scripts/：辅助脚本
  • package.json：脚本与依赖定义
  • tsconfig.json：TypeScript 构建配置

后端构建输出到 dist/，运行入口是 dist/index.js。

2. 核心运行模式

服务只有两种启动模式：

stdio 模式

用于接入 OpenCode 本地 MCP。

1
MCP_TRANSPORT=stdio node dist/index.js

入口逻辑在 src/index.ts 末尾，根据 MCP_TRANSPORT 判断是走 startStdio() 还是 startHttp()。

http 模式

用于提供 HTTP MCP、健康检查和 Web 页面。

1
node dist/index.js

默认监听：

  • /mcp
  • /health
  • /admin

Web 页面的静态资源目录由 src/index.ts 中的 webRoot 指向 web/。

3. 配置文件机制

配置文件处理在 src/config.ts。

关键点：

  • 默认路径：process.cwd()/config/servers.json
  • 可通过 MCP_SERVER_CONFIG 或 MCP_CONFIG_PATH 覆盖
  • 读取入口：loadConfig()
  • 保存入口：saveConfig()
  • 结构校验：validateConfig()

如果你要增加新的配置字段，必须同步修改：

  1. src/config.ts 中的类型定义
  2. validateConfig() 校验逻辑
  3. Web 页面表单和 JSON 生成逻辑
  4. 相关文档

4. 后端扩展入口

后端主入口在 src/index.ts。

你后续开发通常会改这几个区域：

MCP Tool 注册

createServer() 里通过 server.setRequestHandler(ListToolsRequestSchema, ...) 注册工具元数据。

如果要新增 MCP Tool，需要同时改两处：

  1. Tool 列表中的 schema 定义
  2. CallToolRequestSchema 中对应的实现分支

HTTP API

startHttp() 中挂载了所有 HTTP 路由。

当前常见接口分组：

  • /health
  • /api/config
  • /api/servers
  • /api/files/upload
  • /api/files/download
  • /admin 静态页面

如果要新增 Web 后端接口，优先放在 startHttp() 中现有 /api/* 路由区段，保持风格一致。

SSH 能力

SSH 与 SFTP 逻辑在 src/ssh.ts。

这里负责：

  • 远程命令执行
  • 连接测试
  • 上传本地文件到远程
  • 下载远程文件到本地
  • HTTP 流式上传下载

如果是 SSH 相关 bug 或增强，优先从这个文件开始改。

5. Web 页面扩展入口

Web 页面源码在：

  • web/index.html
  • web/app.js
  • web/styles.css

当前页面是一个本地配置文件生成器，不再依赖登录。

页面行为

web/app.js 里主要有三类逻辑：

  1. 本地文件读取与保存
  2. 服务器条目表单管理
  3. JSON 预览同步

如果你要新增字段，比如备注、代理跳板机、额外标签等，优先改这里：

  • HTML 表单字段
  • buildServerFromForm()
  • fillServerForm()
  • renderServers()
  • normalizeConfig()

浏览器能力依赖

当前页面使用 File System Access API：

  • showOpenFilePicker()
  • showSaveFilePicker()

因此这套页面更适合 Chromium 内核浏览器。如果要兼容更多浏览器，需要补一个降级方案，比如导入/导出文本或下载文件。

6. 本地开发方式

安装依赖：

1
npm install

开发运行：

1
npm run dev

构建：

1
npm run build

构建后运行：

1
node dist/index.js

如果要验证 HTTP 服务是否正常：

1
curl http://127.0.0.1:3000/health

预期返回：

1
{"status":"ok"}

7. 常见修改场景

新增一个 MCP Tool

改动位置：

  • src/index.ts 的 Tool 声明
  • src/index.ts 的 Tool 实现分支
  • 如有配置变化，再改 src/config.ts

修改服务器配置结构

改动位置：

  • src/config.ts
  • web/app.js
  • web/index.html
  • 文档文件

修改 Web 页面交互

改动位置：

  • 结构：web/index.html
  • 行为：web/app.js
  • 样式：web/styles.css

修改文件上传下载行为

改动位置：

  • src/ssh.ts
  • src/index.ts

8. 修改后的最小验证

后续开发完任意功能后，至少做这两步：

  1. 构建验证
1
npm run build
  1. HTTP 健康检查
1
2
node dist/index.js
curl http://127.0.0.1:3000/health

如果改了 Web 页面，还要实际打开 /admin 做一次手动操作验证。