linux-mcp-agent 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. linux_mcp_agent-1.0.0/PKG-INFO +277 -0
  2. linux_mcp_agent-1.0.0/README.md +248 -0
  3. linux_mcp_agent-1.0.0/linux_mcp_agent.egg-info/PKG-INFO +277 -0
  4. linux_mcp_agent-1.0.0/linux_mcp_agent.egg-info/SOURCES.txt +14 -0
  5. linux_mcp_agent-1.0.0/linux_mcp_agent.egg-info/dependency_links.txt +1 -0
  6. linux_mcp_agent-1.0.0/linux_mcp_agent.egg-info/entry_points.txt +4 -0
  7. linux_mcp_agent-1.0.0/linux_mcp_agent.egg-info/requires.txt +3 -0
  8. linux_mcp_agent-1.0.0/linux_mcp_agent.egg-info/top_level.txt +1 -0
  9. linux_mcp_agent-1.0.0/linux_mcp_toolkit/__init__.py +18 -0
  10. linux_mcp_agent-1.0.0/linux_mcp_toolkit/main.py +1775 -0
  11. linux_mcp_agent-1.0.0/pyproject.toml +62 -0
  12. linux_mcp_agent-1.0.0/setup.cfg +4 -0
  13. linux_mcp_agent-1.0.0/tests/test_container_and_cli.py +79 -0
  14. linux_mcp_agent-1.0.0/tests/test_core_utils.py +146 -0
  15. linux_mcp_agent-1.0.0/tests/test_read_only_and_jump.py +221 -0
  16. linux_mcp_agent-1.0.0/tests/test_ssh_config.py +192 -0
linux_mcp_agent-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,277 @@
1
+ Metadata-Version: 2.4
2
+ Name: linux-mcp-agent
3
+ Version: 1.0.0
4
+ Summary: Linux MCP Agent - Remote Linux Server Management via MCP for AI Clients
5
+ Author-email: Linux MCP Team <contact@linuxmcp.com>
6
+ Project-URL: Homepage, https://github.com/2653533859/Linux-MCP
7
+ Project-URL: Bug Reports, https://github.com/2653533859/Linux-MCP/issues
8
+ Project-URL: Source, https://github.com/2653533859/Linux-MCP
9
+ Project-URL: Documentation, https://github.com/2653533859/Linux-MCP#readme
10
+ Keywords: linux,ssh,mcp,system-administration,remote-management,interactive-shell
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: System Administrators
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.8
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: System :: Systems Administration
23
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
24
+ Requires-Python: >=3.8
25
+ Description-Content-Type: text/markdown
26
+ Requires-Dist: paramiko>=2.7.0
27
+ Requires-Dist: mcp<2,>=1.10.0
28
+ Requires-Dist: anyio>=4.5
29
+
30
+ # Linux MCP Agent (`linux-mcp-agent`)
31
+
32
+ [![PyPI Version](https://img.shields.io/pypi/v/linux-mcp-agent.svg)](https://pypi.org/project/linux-mcp-agent/)
33
+ [![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/linux-mcp-agent/)
34
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
35
+ [![MCP Protocol](https://img.shields.io/badge/MCP-1.10.0%2B-purple.svg)](https://modelcontextprotocol.io/)
36
+
37
+ 专为大模型客户端（Claude Desktop、Cursor、Windsurf 等）打造的远程 Linux 服务器运维与管理 MCP (Model Context Protocol) Server。
38
+
39
+ 通过 SSH 与 SFTP 协议，让 AI 客户端能够使用自然语言安全、高效地管理远程 Linux 服务器。提供无状态高并发执行、持久化交互式 PTY 会话、容器与系统状态诊断、SFTP 文件管理以及跳板机代理。
40
+
41
+ ---
42
+
43
+ ## 🌟 核心特性
44
+
45
+ - **⚡ 双轨连接架构**：
46
+ - **无状态高并发连接池**：连接自动复用与 Keepalive 保活，一次性命令和状态巡检毫秒级往返。
47
+ - **持久化交互式 PTY 会话**：保留工作目录（`cwd`）与环境变量，支持需要用户输入确认的交互式命令（如 `sudo`、密码提示、持续日志采样）。
48
+ - **🛡️ 生产级安全防护**：
49
+ - **默认严格主机密钥校验**（`StrictHostKeyChecking=yes`）：加载 `known_hosts`，使用 `RejectPolicy` 拦截未登记或不匹配的主机，有效防御中间人（MITM）攻击。
50
+ - **企业跳板机代理**（`JUMP_HOST`）：通过 Bastion / Jump Host 建立 `direct-tcpip` 隧道代理，可无缝纳管隔离私有云内的目标主机。
51
+ - **Opt-in 只读安全模式**（`READ_ONLY=1`）：审计或只读监控场景下一键开启，严格阻断文件修改、服务生命周期变更及高危破坏性命令（如 `rm`、`reboot` 等）。
52
+ - **SFTP 原生文件引擎**：杜绝传统拼接 Shell 命令造成的字符转义与注入风险。
53
+ - **🪙 极致 Token 优化**：
54
+ - 禁用双重结构化输出（`structured_output=False`），单次响应 Payload 降低约 50%。
55
+ - 系统诊断多命令单次 SSH 往返执行（`_run_batch`），自动清理无效行尾空格并保留排版缩进。
56
+ - 输出熔断保底截断（默认 50KB），保留头尾关键上下文，防止超长输出撑爆模型上下文。
57
+ - **🛠️ 本地 CLI 辅助自检**：内建 `--test-connection`、`--ping`、`--version` 诊断工具，在接入 AI 客户端前即可完成离线验证。
58
+
59
+ ---
60
+
61
+ ## 📋 15 个内建 MCP 工具一览
62
+
63
+ | 类别 | 工具名称 | 参数签名 | 功能说明 |
64
+ | :--- | :--- | :--- | :--- |
65
+ | **网络与连接** | `connect_default_host` | `()` | 使用当前环境变量或 MCP 配置连接默认主机，返回当前用户、主机名和负载 |
66
+ | | `ping_host` | `(host?, count=4)` | 本机直接执行 Ping 测试网络连通性与延迟（不走 SSH，支持跨平台输出编码） |
67
+ | | `create_interactive_session` | `(ip_address?, username?, password?, ...)` | 创建持久化 PTY 交互会话，返回形如 `root@host:22` 的会话 ID |
68
+ | | `list_active_sessions` | `()` | 列出所有活跃的交互会话及其空闲时长（空闲超期自动回收） |
69
+ | | `close_session` | `(ip_address)` | 显式关闭并释放远端 PTY 会话与 Shell 资源 |
70
+ | **命令执行** | `execute_command` | `(command, ip_address?, timeout=30)` | 在远程主机无状态执行单条命令，返回退出码、标准输出和标准错误 |
71
+ | | `execute_interactive_command` | `(ip_address, command, timeout=30)` | 在指定交互会话中执行命令，保留上一条命令留下的状态（目录与环境变量） |
72
+ | | `send_interactive_input` | `(ip_address, input_text)` | 向处于等待输入状态的会话发送文本（用于确认提示、密码交互等） |
73
+ | | `get_real_time_output` | `(ip_address, duration=5)` | 读取指定会话在若干秒内持续产生的输出（用于 `tail -f` 等流式日志） |
74
+ | **系统聚合诊断** | `quick_system_info` | `(ip_address?)` | 单次往返批量获取系统总览：内核、发行版、内存、磁盘与活跃进程 |
75
+ | | `network_info` | `(ip_address?)` | 单次往返批量获取网络状态：网卡 IP、监听端口（`ss`/`netstat`）与防火墙状态 |
76
+ | | `monitor_process` | `(process_name, ip_address?)` | 单次往返查看指定进程列表、实例数及对应的 systemd 服务存活状态 |
77
+ | | `container_info` | `(ip_address?)` | 单次往返获取 Docker / Podman 引擎版本、运行中容器列表与资源消耗统计 |
78
+ | | `service_control` | `(service, action, ip_address?)` | 控制 systemd 服务生命周期（`start`/`stop`/`restart`/`status`/`enable`/`disable`） |
79
+ | **文件管理** | `file_operations` | `(operation, path, ip_address?, ...)` | 基于原生 SFTP 通道的文件操作：`read`/`write`/`create`/`list`/`exists`/`upload`/`download`/`chmod` |
80
+
81
+ ---
82
+
83
+ ## 🚀 快速上手
84
+
85
+ ### 1. AI 客户端配置
86
+
87
+ 推荐使用 `uvx` 直接拉起服务，无需在开发机手动安装虚拟环境：
88
+
89
+ #### Claude Desktop 配置
90
+ 配置文件路径：
91
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
92
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
93
+ - **Linux**: `~/.config/Claude/claude_desktop_config.json`
94
+
95
+ ##### 推荐：SSH 密钥认证方式（最安全）
96
+ ```json
97
+ {
98
+ "mcpServers": {
99
+ "linux-mcp-agent": {
100
+ "command": "uvx",
101
+ "args": ["linux-mcp-agent"],
102
+ "env": {
103
+ "HOST": "192.168.1.100",
104
+ "PORT": "22",
105
+ "USERNAME": "admin",
106
+ "KEY_FILE": "/Users/yourname/.ssh/id_rsa",
107
+ "PASSPHRASE": ""
108
+ }
109
+ }
110
+ }
111
+ }
112
+ ```
113
+
114
+ ##### 进阶：跳板机 / 堡垒机网络配置
115
+ ```json
116
+ {
117
+ "mcpServers": {
118
+ "linux-mcp-agent": {
119
+ "command": "uvx",
120
+ "args": ["linux-mcp-agent"],
121
+ "env": {
122
+ "HOST": "10.0.1.50",
123
+ "PORT": "22",
124
+ "USERNAME": "appuser",
125
+ "KEY_FILE": "/Users/yourname/.ssh/id_rsa",
126
+ "JUMP_HOST": "bastion.example.com",
127
+ "JUMP_PORT": "22",
128
+ "JUMP_USER": "bastion_user",
129
+ "JUMP_KEY_FILE": "/Users/yourname/.ssh/id_rsa"
130
+ }
131
+ }
132
+ }
133
+ }
134
+ ```
135
+
136
+ ##### 进阶：只读安全模式配置
137
+ ```json
138
+ {
139
+ "mcpServers": {
140
+ "linux-mcp-agent": {
141
+ "command": "uvx",
142
+ "args": ["linux-mcp-agent"],
143
+ "env": {
144
+ "HOST": "192.168.1.100",
145
+ "USERNAME": "admin",
146
+ "READ_ONLY": "1"
147
+ }
148
+ }
149
+ }
150
+ }
151
+ ```
152
+
153
+ #### Cursor 配置
154
+ 在 `~/.cursor/mcp.json`（或项目级 `.cursor/mcp.json`）中添加：
155
+ ```json
156
+ {
157
+ "mcpServers": {
158
+ "linux-mcp-agent": {
159
+ "command": "uvx",
160
+ "args": ["linux-mcp-agent"],
161
+ "env": {
162
+ "HOST": "192.168.1.100",
163
+ "USERNAME": "admin",
164
+ "KEY_FILE": "$HOME/.ssh/id_rsa"
165
+ }
166
+ }
167
+ }
168
+ }
169
+ ```
170
+
171
+ ---
172
+
173
+ ## ⚙️ 配置参数全解
174
+
175
+ 本 Server 解析配置的优先级为：**工具调用显式入参 > 环境变量 > 客户端配置文件 `env` 字段 > 内置默认值**。
176
+
177
+ | 环境变量 / 配置项 | 默认值 | 作用说明 |
178
+ | :--- | :--- | :--- |
179
+ | `HOST` | - | 默认目标 Linux 主机地址（IP 或域名） |
180
+ | `PORT` | `22` | 默认 SSH 端口 |
181
+ | `USERNAME` | `root` | 登录用户名 |
182
+ | `PASSWORD` | - | 登录密码（若配置了密钥，建议不设密码） |
183
+ | `KEY_FILE` | - | 本机上的 SSH 私钥文件绝对路径（支持 `~` 与环境变量展开） |
184
+ | `PASSPHRASE` | - | 加密 SSH 私钥的密码口令（未加密私钥留空） |
185
+ | `TIMEOUT` | `10` | SSH 建立连接、TCP 握手与 Banner 认证的阶段超时时间（秒） |
186
+ | `RETRY` | `0` | 网络层偶发抖动失败后的额外自动重试次数（`0` ~ `10`） |
187
+ | `STRICT_HOST_KEY_CHECKING` | `yes` | 主机密钥校验策略。默认严格校验（`RejectPolicy`），未登记的主机会被拒绝连接以防 MITM；设为 `no` 退回自动记录（`AutoAddPolicy`） |
188
+ | `KNOWN_HOSTS_FILE` | `~/.ssh/known_hosts` | 严格模式下读取已知主机指纹的文件路径 |
189
+ | `READ_ONLY` | `0` | 只读安全模式。设为 `1` / `yes` / `true` 开启，阻断写文件、服务控制操作及危险 Shell 命令 |
190
+ | `JUMP_HOST` | - | 跳板机 / 堡垒机主机地址。设置后自动建立 `direct-tcpip` 隧道代理目标服务器 |
191
+ | `JUMP_PORT` | `22` | 跳板机 SSH 端口 |
192
+ | `JUMP_USER` | 同 `USERNAME` | 跳板机登录用户名（亦可使用 `JUMP_USERNAME`） |
193
+ | `JUMP_PASSWORD` | 同 `PASSWORD` | 跳板机密码认证 |
194
+ | `JUMP_KEY_FILE` | 同 `KEY_FILE` | 跳板机 SSH 私钥路径 |
195
+ | `JUMP_PASSPHRASE` | 同 `PASSPHRASE` | 跳板机私钥口令 |
196
+ | `MAX_OUTPUT_BYTES` | `50000` | 单次工具输出的最大字节上限，超过时自动保留头尾、省略中间 |
197
+ | `SESSION_IDLE_TIMEOUT` | `600` | 交互会话及池化连接空闲无活动后的回收时间（秒） |
198
+
199
+ > **配置值引用说明**：`KEY_FILE`、`PASSWORD` 等配置项支持使用 `$VAR_NAME`、`${VAR_NAME}` 或 Windows 的 `%VAR_NAME%` 引用开发机系统环境变量。
200
+
201
+ ---
202
+
203
+ ## 🔍 CLI 连通性自检与脱机排障
204
+
205
+ 在将配置写入 AI 客户端前，可直接在终端中运行 CLI 命令检测配置与网络：
206
+
207
+ ```bash
208
+ # 1. 打印版本
209
+ linux-mcp-agent --version
210
+
211
+ # 2. 一键诊断连通性（检测目标主机、跳板机、严格主机密钥策略、只读模式及 SSH 握手状态）
212
+ env HOST=192.168.1.100 USERNAME=root KEY_FILE=~/.ssh/id_rsa linux-mcp-agent --test-connection
213
+
214
+ # 3. 本机快速 Ping 目标主机
215
+ linux-mcp-agent --ping 192.168.1.100
216
+
217
+ # 4. 查看所有 CLI 选项
218
+ linux-mcp-agent --help
219
+ ```
220
+
221
+ ---
222
+
223
+ ## 💬 自然语言使用场景示例
224
+
225
+ 配置完成后，重启 AI 客户端即可直接使用自然语言交互：
226
+
227
+ * **系统巡检**：
228
+ > “帮我检查一下服务器当前的整体状态、负载和磁盘使用情况。”
229
+ > （*调用 `quick_system_info` 一次往返汇总返回*）
230
+
231
+ * **网络与防火墙**：
232
+ > “看看当前机器开放了哪些监听端口，防火墙有没有开启？”
233
+ > （*调用 `network_info` 查询网卡接口、`ss -tlnp` 端口与 UFW 状态*）
234
+
235
+ * **容器与服务监控**：
236
+ > “服务器上跑了哪些 Docker 容器？资源占用情况如何？”
237
+ > （*调用 `container_info` 查看 Docker/Podman 版本、活跃容器及 CPU/内存占用*）
238
+
239
+ * **安全文件修改**：
240
+ > “读取 `/etc/nginx/nginx.conf` 前 50 行，确认配置是否正确。”
241
+ > （*调用 `file_operations(operation="read", path=...)` 原生 SFTP 传输*）
242
+
243
+ * **多步交互排查**：
244
+ > “进入交互会话，切换到 `/opt/app` 目录，执行数据库迁移脚本并实时观察输出。”
245
+ > （*调用 `create_interactive_session` + `execute_interactive_command`*）
246
+
247
+ ---
248
+
249
+ ## 🛡️ 生产安全规范建议
250
+
251
+ 1. **避免 root 直连**：建议为 AI 客户端创建独立的专用系统账号，并仅在 `sudoers` 中开放必要的运维指令。
252
+ 2. **保持严格主机密钥校验**：默认保持 `STRICT_HOST_KEY_CHECKING=yes`。首次纳管新机器前，在开发机使用 `ssh user@host` 建立指纹认证。
253
+ 3. **审计与只读隔离**：若仅授权 AI 客户端分析故障日志和监控巡检，请配置 `READ_ONLY=1`，确保不可产生误操作。
254
+ 4. **长耗时命令监控**：对于大型编译、批量更新等慢任务，建议在交互会话中配合 `get_real_time_output` 轮询，避免单条命令执行阻塞超时。
255
+
256
+ ---
257
+
258
+ ## 🛠️ 本地开发与单元测试
259
+
260
+ ```bash
261
+ # 克隆代码库
262
+ git clone https://github.com/2653533859/Linux-MCP.git
263
+ cd Linux-MCP
264
+
265
+ # 安装开发依赖
266
+ pip install -e .
267
+ pip install pytest
268
+
269
+ # 运行全量单元测试
270
+ pytest
271
+ ```
272
+
273
+ ---
274
+
275
+ ## 📄 开源许可证
276
+
277
+ 本项目基于 [MIT License](LICENSE) 开源。欢迎提交 Issue 与 Pull Request！
linux_mcp_agent-1.0.0/README.md ADDED
@@ -0,0 +1,248 @@
1
+ # Linux MCP Agent (`linux-mcp-agent`)
2
+
3
+ [![PyPI Version](https://img.shields.io/pypi/v/linux-mcp-agent.svg)](https://pypi.org/project/linux-mcp-agent/)
4
+ [![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/linux-mcp-agent/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![MCP Protocol](https://img.shields.io/badge/MCP-1.10.0%2B-purple.svg)](https://modelcontextprotocol.io/)
7
+
8
+ 专为大模型客户端（Claude Desktop、Cursor、Windsurf 等）打造的远程 Linux 服务器运维与管理 MCP (Model Context Protocol) Server。
9
+
10
+ 通过 SSH 与 SFTP 协议，让 AI 客户端能够使用自然语言安全、高效地管理远程 Linux 服务器。提供无状态高并发执行、持久化交互式 PTY 会话、容器与系统状态诊断、SFTP 文件管理以及跳板机代理。
11
+
12
+ ---
13
+
14
+ ## 🌟 核心特性
15
+
16
+ - **⚡ 双轨连接架构**：
17
+ - **无状态高并发连接池**：连接自动复用与 Keepalive 保活，一次性命令和状态巡检毫秒级往返。
18
+ - **持久化交互式 PTY 会话**：保留工作目录（`cwd`）与环境变量，支持需要用户输入确认的交互式命令（如 `sudo`、密码提示、持续日志采样）。
19
+ - **🛡️ 生产级安全防护**：
20
+ - **默认严格主机密钥校验**（`StrictHostKeyChecking=yes`）：加载 `known_hosts`，使用 `RejectPolicy` 拦截未登记或不匹配的主机，有效防御中间人（MITM）攻击。
21
+ - **企业跳板机代理**（`JUMP_HOST`）：通过 Bastion / Jump Host 建立 `direct-tcpip` 隧道代理，可无缝纳管隔离私有云内的目标主机。
22
+ - **Opt-in 只读安全模式**（`READ_ONLY=1`）：审计或只读监控场景下一键开启，严格阻断文件修改、服务生命周期变更及高危破坏性命令（如 `rm`、`reboot` 等）。
23
+ - **SFTP 原生文件引擎**：杜绝传统拼接 Shell 命令造成的字符转义与注入风险。
24
+ - **🪙 极致 Token 优化**：
25
+ - 禁用双重结构化输出（`structured_output=False`），单次响应 Payload 降低约 50%。
26
+ - 系统诊断多命令单次 SSH 往返执行（`_run_batch`），自动清理无效行尾空格并保留排版缩进。
27
+ - 输出熔断保底截断（默认 50KB），保留头尾关键上下文，防止超长输出撑爆模型上下文。
28
+ - **🛠️ 本地 CLI 辅助自检**：内建 `--test-connection`、`--ping`、`--version` 诊断工具，在接入 AI 客户端前即可完成离线验证。
29
+
30
+ ---
31
+
32
+ ## 📋 15 个内建 MCP 工具一览
33
+
34
+ | 类别 | 工具名称 | 参数签名 | 功能说明 |
35
+ | :--- | :--- | :--- | :--- |
36
+ | **网络与连接** | `connect_default_host` | `()` | 使用当前环境变量或 MCP 配置连接默认主机，返回当前用户、主机名和负载 |
37
+ | | `ping_host` | `(host?, count=4)` | 本机直接执行 Ping 测试网络连通性与延迟（不走 SSH，支持跨平台输出编码） |
38
+ | | `create_interactive_session` | `(ip_address?, username?, password?, ...)` | 创建持久化 PTY 交互会话，返回形如 `root@host:22` 的会话 ID |
39
+ | | `list_active_sessions` | `()` | 列出所有活跃的交互会话及其空闲时长（空闲超期自动回收） |
40
+ | | `close_session` | `(ip_address)` | 显式关闭并释放远端 PTY 会话与 Shell 资源 |
41
+ | **命令执行** | `execute_command` | `(command, ip_address?, timeout=30)` | 在远程主机无状态执行单条命令，返回退出码、标准输出和标准错误 |
42
+ | | `execute_interactive_command` | `(ip_address, command, timeout=30)` | 在指定交互会话中执行命令，保留上一条命令留下的状态（目录与环境变量） |
43
+ | | `send_interactive_input` | `(ip_address, input_text)` | 向处于等待输入状态的会话发送文本（用于确认提示、密码交互等） |
44
+ | | `get_real_time_output` | `(ip_address, duration=5)` | 读取指定会话在若干秒内持续产生的输出（用于 `tail -f` 等流式日志） |
45
+ | **系统聚合诊断** | `quick_system_info` | `(ip_address?)` | 单次往返批量获取系统总览：内核、发行版、内存、磁盘与活跃进程 |
46
+ | | `network_info` | `(ip_address?)` | 单次往返批量获取网络状态：网卡 IP、监听端口（`ss`/`netstat`）与防火墙状态 |
47
+ | | `monitor_process` | `(process_name, ip_address?)` | 单次往返查看指定进程列表、实例数及对应的 systemd 服务存活状态 |
48
+ | | `container_info` | `(ip_address?)` | 单次往返获取 Docker / Podman 引擎版本、运行中容器列表与资源消耗统计 |
49
+ | | `service_control` | `(service, action, ip_address?)` | 控制 systemd 服务生命周期（`start`/`stop`/`restart`/`status`/`enable`/`disable`） |
50
+ | **文件管理** | `file_operations` | `(operation, path, ip_address?, ...)` | 基于原生 SFTP 通道的文件操作：`read`/`write`/`create`/`list`/`exists`/`upload`/`download`/`chmod` |
51
+
52
+ ---
53
+
54
+ ## 🚀 快速上手
55
+
56
+ ### 1. AI 客户端配置
57
+
58
+ 推荐使用 `uvx` 直接拉起服务，无需在开发机手动安装虚拟环境：
59
+
60
+ #### Claude Desktop 配置
61
+ 配置文件路径：
62
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
63
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
64
+ - **Linux**: `~/.config/Claude/claude_desktop_config.json`
65
+
66
+ ##### 推荐：SSH 密钥认证方式（最安全）
67
+ ```json
68
+ {
69
+ "mcpServers": {
70
+ "linux-mcp-agent": {
71
+ "command": "uvx",
72
+ "args": ["linux-mcp-agent"],
73
+ "env": {
74
+ "HOST": "192.168.1.100",
75
+ "PORT": "22",
76
+ "USERNAME": "admin",
77
+ "KEY_FILE": "/Users/yourname/.ssh/id_rsa",
78
+ "PASSPHRASE": ""
79
+ }
80
+ }
81
+ }
82
+ }
83
+ ```
84
+
85
+ ##### 进阶：跳板机 / 堡垒机网络配置
86
+ ```json
87
+ {
88
+ "mcpServers": {
89
+ "linux-mcp-agent": {
90
+ "command": "uvx",
91
+ "args": ["linux-mcp-agent"],
92
+ "env": {
93
+ "HOST": "10.0.1.50",
94
+ "PORT": "22",
95
+ "USERNAME": "appuser",
96
+ "KEY_FILE": "/Users/yourname/.ssh/id_rsa",
97
+ "JUMP_HOST": "bastion.example.com",
98
+ "JUMP_PORT": "22",
99
+ "JUMP_USER": "bastion_user",
100
+ "JUMP_KEY_FILE": "/Users/yourname/.ssh/id_rsa"
101
+ }
102
+ }
103
+ }
104
+ }
105
+ ```
106
+
107
+ ##### 进阶：只读安全模式配置
108
+ ```json
109
+ {
110
+ "mcpServers": {
111
+ "linux-mcp-agent": {
112
+ "command": "uvx",
113
+ "args": ["linux-mcp-agent"],
114
+ "env": {
115
+ "HOST": "192.168.1.100",
116
+ "USERNAME": "admin",
117
+ "READ_ONLY": "1"
118
+ }
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ #### Cursor 配置
125
+ 在 `~/.cursor/mcp.json`（或项目级 `.cursor/mcp.json`）中添加：
126
+ ```json
127
+ {
128
+ "mcpServers": {
129
+ "linux-mcp-agent": {
130
+ "command": "uvx",
131
+ "args": ["linux-mcp-agent"],
132
+ "env": {
133
+ "HOST": "192.168.1.100",
134
+ "USERNAME": "admin",
135
+ "KEY_FILE": "$HOME/.ssh/id_rsa"
136
+ }
137
+ }
138
+ }
139
+ }
140
+ ```
141
+
142
+ ---
143
+
144
+ ## ⚙️ 配置参数全解
145
+
146
+ 本 Server 解析配置的优先级为：**工具调用显式入参 > 环境变量 > 客户端配置文件 `env` 字段 > 内置默认值**。
147
+
148
+ | 环境变量 / 配置项 | 默认值 | 作用说明 |
149
+ | :--- | :--- | :--- |
150
+ | `HOST` | - | 默认目标 Linux 主机地址（IP 或域名） |
151
+ | `PORT` | `22` | 默认 SSH 端口 |
152
+ | `USERNAME` | `root` | 登录用户名 |
153
+ | `PASSWORD` | - | 登录密码（若配置了密钥，建议不设密码） |
154
+ | `KEY_FILE` | - | 本机上的 SSH 私钥文件绝对路径（支持 `~` 与环境变量展开） |
155
+ | `PASSPHRASE` | - | 加密 SSH 私钥的密码口令（未加密私钥留空） |
156
+ | `TIMEOUT` | `10` | SSH 建立连接、TCP 握手与 Banner 认证的阶段超时时间（秒） |
157
+ | `RETRY` | `0` | 网络层偶发抖动失败后的额外自动重试次数（`0` ~ `10`） |
158
+ | `STRICT_HOST_KEY_CHECKING` | `yes` | 主机密钥校验策略。默认严格校验（`RejectPolicy`），未登记的主机会被拒绝连接以防 MITM；设为 `no` 退回自动记录（`AutoAddPolicy`） |
159
+ | `KNOWN_HOSTS_FILE` | `~/.ssh/known_hosts` | 严格模式下读取已知主机指纹的文件路径 |
160
+ | `READ_ONLY` | `0` | 只读安全模式。设为 `1` / `yes` / `true` 开启，阻断写文件、服务控制操作及危险 Shell 命令 |
161
+ | `JUMP_HOST` | - | 跳板机 / 堡垒机主机地址。设置后自动建立 `direct-tcpip` 隧道代理目标服务器 |
162
+ | `JUMP_PORT` | `22` | 跳板机 SSH 端口 |
163
+ | `JUMP_USER` | 同 `USERNAME` | 跳板机登录用户名（亦可使用 `JUMP_USERNAME`） |
164
+ | `JUMP_PASSWORD` | 同 `PASSWORD` | 跳板机密码认证 |
165
+ | `JUMP_KEY_FILE` | 同 `KEY_FILE` | 跳板机 SSH 私钥路径 |
166
+ | `JUMP_PASSPHRASE` | 同 `PASSPHRASE` | 跳板机私钥口令 |
167
+ | `MAX_OUTPUT_BYTES` | `50000` | 单次工具输出的最大字节上限，超过时自动保留头尾、省略中间 |
168
+ | `SESSION_IDLE_TIMEOUT` | `600` | 交互会话及池化连接空闲无活动后的回收时间（秒） |
169
+
170
+ > **配置值引用说明**：`KEY_FILE`、`PASSWORD` 等配置项支持使用 `$VAR_NAME`、`${VAR_NAME}` 或 Windows 的 `%VAR_NAME%` 引用开发机系统环境变量。
171
+
172
+ ---
173
+
174
+ ## 🔍 CLI 连通性自检与脱机排障
175
+
176
+ 在将配置写入 AI 客户端前，可直接在终端中运行 CLI 命令检测配置与网络：
177
+
178
+ ```bash
179
+ # 1. 打印版本
180
+ linux-mcp-agent --version
181
+
182
+ # 2. 一键诊断连通性（检测目标主机、跳板机、严格主机密钥策略、只读模式及 SSH 握手状态）
183
+ env HOST=192.168.1.100 USERNAME=root KEY_FILE=~/.ssh/id_rsa linux-mcp-agent --test-connection
184
+
185
+ # 3. 本机快速 Ping 目标主机
186
+ linux-mcp-agent --ping 192.168.1.100
187
+
188
+ # 4. 查看所有 CLI 选项
189
+ linux-mcp-agent --help
190
+ ```
191
+
192
+ ---
193
+
194
+ ## 💬 自然语言使用场景示例
195
+
196
+ 配置完成后，重启 AI 客户端即可直接使用自然语言交互：
197
+
198
+ * **系统巡检**：
199
+ > “帮我检查一下服务器当前的整体状态、负载和磁盘使用情况。”
200
+ > （*调用 `quick_system_info` 一次往返汇总返回*）
201
+
202
+ * **网络与防火墙**：
203
+ > “看看当前机器开放了哪些监听端口，防火墙有没有开启？”
204
+ > （*调用 `network_info` 查询网卡接口、`ss -tlnp` 端口与 UFW 状态*）
205
+
206
+ * **容器与服务监控**：
207
+ > “服务器上跑了哪些 Docker 容器？资源占用情况如何？”
208
+ > （*调用 `container_info` 查看 Docker/Podman 版本、活跃容器及 CPU/内存占用*）
209
+
210
+ * **安全文件修改**：
211
+ > “读取 `/etc/nginx/nginx.conf` 前 50 行，确认配置是否正确。”
212
+ > （*调用 `file_operations(operation="read", path=...)` 原生 SFTP 传输*）
213
+
214
+ * **多步交互排查**：
215
+ > “进入交互会话，切换到 `/opt/app` 目录，执行数据库迁移脚本并实时观察输出。”
216
+ > （*调用 `create_interactive_session` + `execute_interactive_command`*）
217
+
218
+ ---
219
+
220
+ ## 🛡️ 生产安全规范建议
221
+
222
+ 1. **避免 root 直连**：建议为 AI 客户端创建独立的专用系统账号，并仅在 `sudoers` 中开放必要的运维指令。
223
+ 2. **保持严格主机密钥校验**：默认保持 `STRICT_HOST_KEY_CHECKING=yes`。首次纳管新机器前，在开发机使用 `ssh user@host` 建立指纹认证。
224
+ 3. **审计与只读隔离**：若仅授权 AI 客户端分析故障日志和监控巡检，请配置 `READ_ONLY=1`，确保不可产生误操作。
225
+ 4. **长耗时命令监控**：对于大型编译、批量更新等慢任务，建议在交互会话中配合 `get_real_time_output` 轮询，避免单条命令执行阻塞超时。
226
+
227
+ ---
228
+
229
+ ## 🛠️ 本地开发与单元测试
230
+
231
+ ```bash
232
+ # 克隆代码库
233
+ git clone https://github.com/2653533859/Linux-MCP.git
234
+ cd Linux-MCP
235
+
236
+ # 安装开发依赖
237
+ pip install -e .
238
+ pip install pytest
239
+
240
+ # 运行全量单元测试
241
+ pytest
242
+ ```
243
+
244
+ ---
245
+
246
+ ## 📄 开源许可证
247
+
248
+ 本项目基于 [MIT License](LICENSE) 开源。欢迎提交 Issue 与 Pull Request！