ACS MCP Server

Arcadyan miniACS MCP Server — 通过 SSH 远程管理 CWMP/TR-069 ACS（Auto Configuration Server）的 MCP 服务器。

快速开始

编译

# 安装依赖
npm install

# 编译 TypeScript
npm run build
# 或直接使用 tsc
npx tsc

编译后 dist/index.js 即为 MCP 入口文件。

stdio 模式运行

用于 VS Code 等本地 MCP 客户端，通过标准输入输出通信：

# 直接运行
node dist/index.js

# 或通过 npx（安装为全局包后）
npx acs-mcp-server

HTTP 模式运行

启动 HTTP + SSE 服务器，支持远程 MCP 客户端连接：

# Windows
set ACS_TRANSPORT=http && set ACS_HTTP_PORT=3000 && set ACS_HTTP_HOST=0.0.0.0 && node dist/index.js

# Linux / macOS
ACS_TRANSPORT=http ACS_HTTP_PORT=3000 ACS_HTTP_HOST=0.0.0.0 node dist/index.js

端点：

• MCP 端点: POST http://localhost:3000/mcp — Streamable HTTP + SSE
• 健康检查: GET http://localhost:3000/health

.mcp.json 配置示例

项目根目录提供了 .mcp.json.example 示例文件，包含 stdio 和 HTTP 两种模式的 MCP 配置模板。该配置格式适用于以下 MCP 客户端：

客户端	配置路径	说明
VS Code	项目根目录 .mcp.json	Copilot Chat 自动加载，也可通过 .vscode/mcp.json 使用
VS Code Insiders	项目根目录 .mcp.json	同上
Claude Desktop	~/.config/claude/mcp.json 或设置面板	全局 MCP 配置

使用方法：复制 .mcp.json.example 为 .mcp.json，将 <your-acs-server-ip> 和 <your-ssh-password> 替换为实际值即可。

cp .mcp.json.example .mcp.json
# 编辑 .mcp.json 填入真实 IP 和密码

⚠️ .mcp.json 包含敏感信息，已在 .gitignore 中排除，请勿提交到版本库。

---

功能概述

该 MCP Server 提供以下工具分类：

🖥️ 服务器生命周期管理

工具	描述
acs_status	获取 ACS 运行状态
acs_start	启动 ACS 服务器
acs_stop	停止 ACS 服务器
acs_restart	重启 ACS 服务器

📱 设备管理

工具	描述
acs_list_devices	列出所有已知设备
acs_get_current_device	获取当前设备信息
acs_find_device	按 SN 查找设备

🔗 Connection Request

工具	描述
acs_connection_request	向指定设备发送 Connection Request
acs_connection_request_current	向当前设备发送 Connection Request

📜 脚本管理

工具	描述
acs_list_scripts	列出所有 TR-069 脚本
acs_get_script	查看脚本内容
acs_create_script	创建/更新脚本
acs_delete_script	删除脚本
acs_run_script	运行脚本

⚙️ 设备参数操作

工具	描述
acs_get_parameters	获取设备参数值
acs_set_parameters	设置设备参数
acs_reboot_device	重启设备
acs_get_rpc_methods	获取设备支持的 RPC 方法

📦 配置下发/上传

工具	描述
acs_download_config	向设备下发配置文件
acs_upload_config	从设备上传配置文件
acs_set_push_flag	设置 Push 标志
acs_push_config	立即推送配置

📋 日志与调试

工具	描述
acs_get_boot_log	获取 boot 日志
acs_get_trace_log	获取 trace 日志
acs_get_error_log	获取 error 日志
acs_get_sequence	获取脚本执行序列
acs_set_sequence	设置脚本执行序列
acs_exec_raw	执行原始 shell 命令

安装

# 设置私有 registry
npm config set registry http://10.118.81.229:4873/

# 创建安装目录
mkdir acs-server && cd acs-server

# 初始化项目
npm init -y

# 安装 ACS MCP Server
npm install acs-mcp-server

安装后目录结构：

acs-server/
├── node_modules/
│   └── acs-mcp-server/
│       └── dist/
│           └── index.js    ← MCP 入口
└── package.json

配置

通过环境变量配置 ACS 服务器连接和传输模式：

变量	默认值	描述
ACS_HOST	120.238.249.244	ACS 服务器 IP
ACS_SSH_PORT	22	SSH 端口
ACS_USERNAME	root	SSH 用户名
ACS_PASSWORD	@arcadyan1234	SSH 密码
ACS_BASE_PATH	/root/Downloads/acs-tools/miniACS/Linux	ACS 安装路径
ACS_TRANSPORT	stdio	传输模式：stdio 或 http
ACS_HTTP_PORT	3000	HTTP 模式监听端口
ACS_HTTP_HOST	127.0.0.1	HTTP 模式监听地址

传输模式

stdio 模式（默认）

用于 VS Code 等本地 MCP 客户端，通过标准输入输出通信：

{
  "mcpServers": {
    "acs-mcp-server": {
      "command": "npx",
      "args": ["acs-mcp-server"],
      "env": {
        "ACS_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP + SSE 模式

启动 HTTP 服务器，支持远程 MCP 客户端通过 HTTP + SSE 连接：

ACS_TRANSPORT=http ACS_HTTP_PORT=3000 ACS_HTTP_HOST=0.0.0.0 npx acs-mcp-server

端点：

• MCP 端点: POST/GET http://host:3000/mcp — Streamable HTTP + SSE
• 健康检查: GET http://host:3000/health

远程客户端配置示例：

{
  "mcpServers": {
    "acs-mcp-server": {
      "url": "http://192.168.1.100:3000/mcp"
    }
  }
}

MCP 客户端配置

VS Code / Claude Desktop（stdio 模式）

{
  "mcpServers": {
    "acs-mcp-server": {
      "command": "npx",
      "args": ["acs-mcp-server"],
      "env": {
        "ACS_HOST": "120.238.249.244",
        "ACS_PASSWORD": "@arcadyan1234"
      }
    }
  }
}

远程客户端（HTTP 模式）

先在服务器上启动 HTTP 模式：

ACS_TRANSPORT=http ACS_HTTP_PORT=3000 ACS_HTTP_HOST=0.0.0.0 npx acs-mcp-server

客户端配置：

{
  "mcpServers": {
    "acs-mcp-server-http": {
      "url": "http://<server-ip>:3000/mcp"
    }
  }
}

架构

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│          (VS Code / Claude Desktop / 远程客户端)          │
└─────────┬──────────────────────────────┬────────────────┘
          │ stdio (JSON-RPC)             │ HTTP + SSE
┌─────────▼──────────┐    ┌──────────────▼───────────────┐
│ StdioServerTransport│    │ StreamableHTTPServerTransport │
└─────────┬──────────┘    └──────────────┬───────────────┘
          │                              │
┌─────────▼──────────────────────────────▼───────────────┐
│                 ACS MCP Server                          │
│  ┌───────────────────────────────────────────────────┐ │
│  │              index.ts (MCP Server)                  │ │
│  │    - 注册 26 个 Tools                              │ │
│  │    - 双传输模式：stdio / http+sse                  │ │
│  └──────────────────────┬────────────────────────────┘ │
│                         │                               │
│  ┌──────────────────────▼────────────────────────────┐ │
│  │           acs-client.ts (SSH Client)                │ │
│  │    - SSH 连接管理                                  │ │
│  │    - 远程命令执行                                  │ │
│  │    - ACS 操作封装                                  │ │
│  └──────────────────────┬────────────────────────────┘ │
└─────────────────────────┼──────────────────────────────┘
                          │ SSH (port 22)
┌─────────────────────────▼──────────────────────────────┐
│               Remote ACS Server                         │
│                (120.238.249.244)                        │
│  ┌────────────────────────────────────────────────┐    │
│  │  /root/Downloads/acs-tools/miniACS/Linux/       │    │
│  │  ├── acs          (主程序)                      │    │
│  │  ├── connreq      (Connection Request)         │    │
│  │  ├── acscmd       (命令行工具)                 │    │
│  │  ├── Tr69-Scripts/ (Lua 脚本库)                │    │
│  │  ├── DeviceList.json                            │    │
│  │  └── Current.json                               │    │
│  └────────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────────┘

使用示例

查看 ACS 状态

> acs_status
{
  "running": true,
  "pid": "132140",
  "port": 8080,
  "logFile": "/root/Downloads/acs-tools/miniACS/Linux/boot.log"
}

列出所有设备

> acs_list_devices
[
  { "SN": "ARC2025001", "CRURL": "http://10.55.101.10:7547/...", ... },
  ...
]

向设备推送配置

> acs_set_push_flag ARC2025001
Push flag set for ARC2025001. Config will deploy on next connection.

技术栈

• Runtime: Node.js (ESM)
• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• SSH: ssh2