LLM client (Cherry Studio / Claude Code / ...)
    └── MCP (Streamable HTTP 或 stdio)
        └── mcp_socket_server (本服务, 中央节点, 1 实例)
                └── TCP socket_client (每靶机独立连接池)
                    └── socket_server (每靶机 :9000, N 实例)

# 方式一: git clone(若有远程仓库)
git clone <repo-url> /opt/mcp_socket_server
cd /opt/mcp_socket_server

# 方式二: 直接使用已部署的代码
cd /opt/mcp_socket_server
git pull   # 更新到最新

cd /opt/mcp_socket_server

# 创建虚拟环境(需 python3.10+)
python3.10 -m venv venv

# 激活
source venv/bin/activate

# 安装本包 + 依赖(mcp / uvicorn / pyyaml / anyio)+ 开发依赖(pytest / httpx)
pip install -e ".[dev]"

venv/bin/python -c "from mcp_socket_server.server import mcp; print('OK')"
venv/bin/mcp-socket-server --help 2>&1 || echo "命令存在(无 --help 是正常,直接启动)"

cp config.example.yaml config.yaml
vi config.yaml

cd /opt/mcp_socket_server
venv/bin/mcp-socket-server config.yaml

cd /opt/mcp_socket_server
nohup venv/bin/mcp-socket-server config.yaml \
  > /var/log/mcp-socket-server.log 2>&1 &

# 记下 PID
echo $! > /var/run/mcp-socket-server.pid
echo "started, pid=$(cat /var/run/mcp-socket-server.pid)"

[Unit]
Description=MCP Socket Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/mcp_socket_server
ExecStart=/opt/mcp_socket_server/venv/bin/mcp-socket-server /opt/mcp_socket_server/config.yaml
Restart=on-failure
RestartSec=5
StandardOutput=append:/var/log/mcp-socket-server.log
StandardError=append:/var/log/mcp-socket-server.log

[Install]
WantedBy=multi-user.target

# 首次建日志文件
touch /var/log/mcp-socket-server.log

systemctl daemon-reload
systemctl enable mcp-socket-server
systemctl start mcp-socket-server
systemctl status mcp-socket-server

ps aux | grep mcp-socket-server | grep -v grep
# 应无输出

# 实时跟踪
journalctl -u mcp-socket-server -f

# 最近 100 行
journalctl -u mcp-socket-server -n 100

# 今天的日志
journalctl -u mcp-socket-server --since today

# 某次报错前后
journalctl -u mcp-socket-server --since "10 min ago" | grep -i error

# 实时跟踪
tail -f /var/log/mcp-socket-server.log

# 最近 50 行
tail -50 /var/log/mcp-socket-server.log

# 只看错误
grep -iE "error|exception|failed" /var/log/mcp-socket-server.log | tail -30

cmd_exec CALLED: targets=["10.12.131.32"] args='echo hi'
[10.12.131.32] lock acquired: shell
[10.12.131.32] pool acquire (12ms)
connect start: 10.12.131.32:9000 timeout=60s
connect OK: 10.12.131.32:9000
cmd_exec send: dt=1 args='echo hi'
recv_gzip: got 45B gzip
[10.12.131.32] fn done (23ms)

venv/bin/python -c "
import sqlite3
c = sqlite3.connect('mcp_socket_server.db')
for r in c.execute('SELECT ts,tool,ok_count,failed_count FROM audit_log ORDER BY id DESC LIMIT 10'):
    print(r)
"

{
  "mcpServers": {
    "mcp-socket-server": {
      "url": "http://10.12.131.81:8080/mcp"
    }
  }
}

{
  "mcpServers": {
    "mcp-socket-server": {
      "command": "/opt/mcp_socket_server/venv/bin/python",
      "args": ["-m", "mcp_socket_server"]
    }
  }
}

{
  "ok": 2,
  "failed": [{"target": "10.0.0.3", "reason": "Connection refused"}],
  "results": [{"target": "10.0.0.1", "version": "1.3.9"}, ...]
}

export no_proxy="127.0.0.1,localhost,10.12.131.81"

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv python install 3.10
uv venv --python 3.10 venv
uv pip install --python venv/bin/python -e ".[dev]"

# 跑全量测试(47 个)
venv/bin/python -m pytest tests/ -v

# 跑单个模块
venv/bin/python -m pytest tests/test_socket_client.py -v

src/mcp_socket_server/
  __main__.py      CLI 入口
  config.py        配置加载(yaml + env)
  transport.py     Streamable HTTP(uvicorn)
  server.py        FastMCP + 17 个工具
  socket_client.py TCP 客户端(per-datatype recv + gzip + 文件传输)
  pool.py          连接池 + 批量调度 + session
  commands.py      datatype 注册表(锁类/危险等级)
  locks.py         LockManager(per-target 多模式锁)
  registry.py      靶机注册表(SQLite + @tag)
  audit.py         审计日志(SQLite)