# ACS MCP Server

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

## 快速开始

### 编译

```bash
# 安装依赖
npm install

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

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

### stdio 模式运行

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

```bash
# 直接运行
node dist/index.js

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

### HTTP 模式运行

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

```bash
# 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>` 替换为实际值即可。

```bash
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 命令 |

## 安装

```bash
# 设置私有 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` | `<your-acs-server-ip>` | ACS 服务器 IP |
| `ACS_SSH_PORT` | `22` | SSH 端口 |
| `ACS_USERNAME` | `root` | SSH 用户名 |
| `ACS_PASSWORD` | `<your-ssh-password>` | 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 客户端，通过标准输入输出通信：

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

### HTTP + SSE 模式

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

```bash
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`

远程客户端配置示例：
```json
{
  "mcpServers": {
    "acs-mcp-server": {
      "url": "http://192.168.1.100:3000/mcp"
    }
  }
}
```

## MCP 客户端配置

### VS Code / Claude Desktop（stdio 模式）

```json
{
  "mcpServers": {
    "acs-mcp-server": {
      "command": "npx",
      "args": ["acs-mcp-server"],
      "env": {
        "ACS_HOST": "<your-acs-server-ip>",
        "ACS_PASSWORD": "<your-ssh-password>"
      }
    }
  }
}
```

### 远程客户端（HTTP 模式）

先在服务器上启动 HTTP 模式：
```bash
ACS_TRANSPORT=http ACS_HTTP_PORT=3000 ACS_HTTP_HOST=0.0.0.0 npx acs-mcp-server
```

客户端配置：
```json
{
  "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                         │
│                (<your-acs-server-ip>)                        │
│  ┌────────────────────────────────────────────────┐    │
│  │  /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": "<device-sn>", "CRURL": "http://<acs-ip>:7547/...", ... },
  ...
]
```

### 向设备推送配置
```
> acs_set_push_flag <device-sn>
Push flag set for <device-sn>. Config will deploy on next connection.
```

## 技术栈

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