Metadata-Version: 2.5
Name: mcp-server-tcp
Version: 1.1.0
Summary: A versatile TCP client/server proxy MCP server for LLMs
Author: Ateng
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# TCP MCP Server

<p align="center">
  <strong>通用 TCP 协议代理与自动化测试 Model Context Protocol (MCP) 服务端</strong>
</p>

<p align="center">
  <a href="https://github.com/atengk/mcp-server-tcp/actions/workflows/ci.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/atengk/mcp-server-tcp/ci.yml?branch=main&label=CI&style=flat-square" alt="CI Status" />
  </a>
  <a href="https://github.com/atengk/mcp-server-tcp/releases">
    <img src="https://img.shields.io/github/v/release/atengk/mcp-server-tcp?style=flat-square" alt="Release" />
  </a>
  <a href="./LICENSE">
    <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=flat-square" alt="License" />
  </a>
  <a href="./CONTRIBUTING.md">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome" />
  </a>
</p>

---

## 📖 项目简介

`mcp-server-tcp` 是一个基于 Python 3.10+、Model Context Protocol 官方 SDK (`mcp`) 与 `asyncio` 的高性能通用 TCP 协议 MCP 服务端。赋能大语言模型（LLM）与任意 TCP 目标服务、IoT 工业硬件及私有二进制协议（如 Modbus、自定义二进制 RPC）进行全双工收发与自动化联调。

---

## ✨ 核心特性

- 🎯 **双向通信全能**：不仅支持作为 TCP 客户端主动向外连接，还支持动态启动本地 **Mock Server** 被动捕获外部设备连入并模拟应答；
- ⚡ **原生全双工并发**：采用读写锁分离架构（ADR-0005），长轮询等待接收（`recv`）时绝不阻塞并发指令下发（`send`）；
- 🧩 **原子定界与半包保全**：独创软超时机制（Soft Timeout），定界符未达时不破坏报文流，无损保留半包缓冲（Drain Buffer）静默等待后续拼接；内置 10MB 缓冲区防 OOM 熔断门禁；
- 🛡️ **探针并发平滑门禁**：端口批量扫描限制单次上限 128 个端口，内置 32 并发信号量，彻底规避系统套接字句柄耗尽崩溃；
- 🔍 **内存环形流量审计**：每个连接独享 100 条环形缓冲区（Traffic Ring Buffer），提供时间戳、传输方向及 Hex/文本快照，零磁盘污染；支持标准 MCP Resource 挂载读取；
- 🔒 **工业级安全防线**：默认拦截云厂商元数据（`169.254.169.254`）及高危保留网段，Mock Server 监听绑定受分级安全策略管辖，全方位防范 SSRF 攻击；
- 🚀 **开箱即用与容器分发**：支持 `uvx` 零配置即开即用，同时发布多架构容器镜像至 GitHub Packages (`ghcr.io`)。

---

## 🛠️ 工具清单 (Tools)

| 分类 | 工具名称 | 核心职责说明 |
| :--- | :--- | :--- |
| **网络探针** | `tcp_ping_port` | 测试指定主机端口的 TCP SYN 握手时延（毫秒）与可达性 |
| | `tcp_port_scan` | 并发探测目标主机端口开放状态（上限 128 端口，32 信号量平滑限流） |
| | `tcp_send_once` | 一次性短连接发收探针（自动完成连接、发送、读取与优雅关闭） |
| **会话管理** | `tcp_connect` | 建立长连接并加入会话池，返回唯一 `conn_id` |
| | `tcp_disconnect` | 安全断开指定长连接并穿透式释放套接字 |
| | `tcp_list_connections` | 列出活跃连接（支持 `server_id` 拓扑过滤，展示入站/出站标识与待读缓冲） |
| **精准收发** | `tcp_send_text` | 发送 UTF-8 文本数据（可选追加 `\r\n`，全双工独立写锁保护） |
| | `tcp_send_hex` | 发送原始十六进制字节序列（Hex Payload） |
| | `tcp_recv_text` | 接收文本，支持定界符截断（定界符未达保全半包）、软超时返回与 10MB 防 OOM 熔断 |
| | `tcp_recv_hex` | 接收二进制字节流并格式化为 Hex 视图，支持最大字节数限制与防 OOM 熔断 |
| **Mock 服务** | `tcp_start_server` | 启动本地 TCP 服务监听器，外部连入客户端自动分配 `conn_id` 入池（受绑定安全门禁保护） |
| | `tcp_broadcast` | 向指定 Mock Server 连入的所有活跃客户端同时群发数据 |
| | `tcp_stop_server` | 停止服务监听并释放端口绑定，级联断开所有附属客户端 |
| **调试审计** | `tcp_dump_traffic` | 回溯指定连接最近的收发报文记录（含时间戳与方向快照） |

---

## 📊 资源清单 (Resources)

服务端提供标准 MCP Resource 资源订阅能力，便于客户端与大模型挂载并实时回溯链路流量快照：

| 资源 URI 模式 | MIME 类型 | 说明 |
| :--- | :--- | :--- |
| `tcp://connection/{conn_id}/traffic` | `application/json` | 读取或订阅指定长连接的 Traffic Ring Buffer 流量审计数据（最多 100 条双工收发记录） |


---

## 🚀 快速开始

### 1. 通用 MCP 客户端配置 (推荐)

在任意支持 Model Context Protocol (MCP) 的客户端配置文件中，添加如下标准通用配置。你可以根据部署喜好选择 `tcp`（基于 `uvx`，零安装即开即用）或 `tcp-docker`（基于容器隔离）：

```json
{
  "mcpServers": {
    "tcp": {
      "command": "uvx",
      "args": ["mcp-server-tcp"],
      "env": {
        "MCP_TCP_MAX_CONNECTIONS": "10",
        "MCP_TCP_IDLE_TIMEOUT_SECONDS": "300.0",
        "MCP_TCP_ALLOW_PRIVATE_NETWORKS": "true"
      }
    },
    "tcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MCP_TCP_MAX_CONNECTIONS=10",
        "-e", "MCP_TCP_IDLE_TIMEOUT_SECONDS=300.0",
        "-e", "MCP_TCP_ALLOW_PRIVATE_NETWORKS=true",
        "ghcr.io/atengk/mcp-server-tcp:latest"
      ]
    }
  }
}
```

> 💡 **提示**：上述 `env` 字段中的环境变量均为可选调优项；若使用默认参数，仅需保留 `command` 与 `args` 即可。

### 2. 命令行独立调试 (CLI / Docker)

若需要在本地终端中直接测试 stdio 通信或验证服务健康状况，可执行以下命令：

```bash
# 方式 A：通过 uvx 直接启动
uvx mcp-server-tcp

# 方式 B：通过 Docker 运行
docker run -i --rm ghcr.io/atengk/mcp-server-tcp:latest
```


---

## 💡 常用提示词示例 (Prompt Examples)

在配置好 MCP 客户端后，你可以直接通过日常自然语言向大模型下达指令。以下覆盖 4 类典型业务场景：

### 1. 主动连接外部目标服务（出站客户端）

> **用户提问**：
> “帮我连接 `127.0.0.1:6379` 测试 Redis 是否连通，发送 `PING\r\n` 并读取回包确认。”
> 
> *👉 AI 将自动调度：`tcp_connect` -> `tcp_send_text(..., append_crlf=True)` -> `tcp_recv_text(..., delimiter="\r\n")`*

> **用户提问**：
> “向 `192.168.1.50:8080` 发送单次 HTTP 请求探测 `GET /health HTTP/1.1\r\nHost: localhost\r\n\r\n`，看服务端返回什么状态码。”
> 
> *👉 AI 将自动调度：`tcp_send_once`（短连接自动建连、发送、接收与关闭）*

### 2. IoT 工业设备与私有二进制协议（Hex 报文）

> **用户提问**：
> “连接目标 PLC 设备 `192.168.1.200:502`，发送 Modbus 读取保持寄存器报文 `01 03 00 00 00 02 C4 0B`，并将返回的 Hex 字节流解码分析。”
> 
> *👉 AI 将自动调度：`tcp_connect` -> `tcp_send_hex` -> `tcp_recv_hex` -> 结合领域知识解析 Hex 字节*

### 3. 网络探针与端口排障

> **用户提问**：
> “排查目标主机 `192.168.1.1` 的 TCP 握手时延，并并发扫描常见端口 `[22, 80, 443, 3306, 6379, 8080]`，列出开放状态。”
> 
> *👉 AI 将自动调度：`tcp_ping_port` 测试握手延迟 -> `tcp_port_scan` 批量平滑扫描*

### 4. 本地仿真与设备联调（Mock Server）

> **用户提问**：
> “在本地启动一个 TCP Mock 服务端监听 `8888` 端口，查看是否有外部客户端连入；一旦收到外部数据，向该客户端回复 `OK\r\n`。”
> 
> *👉 AI 将自动调度：`tcp_start_server` 开启监听 -> `tcp_list_connections(server_id=...)` 探查入站客户端 -> `tcp_recv_text` / `tcp_send_text` 交互响应*

> **用户提问**：
> “调出当前连接最近的 20 条通信审计日志，分析刚才数据交互的收发时序与报文快照。”
> 
> *👉 AI 将自动调度：`tcp_dump_traffic`（或读取 MCP 资源 `tcp://connection/{conn_id}/traffic`）回溯 Traffic Ring Buffer 记录*

---

## ⚙️ 运行时环境变量配置 (Runtime Configuration)


服务端支持通过系统环境变量进行无代码入侵式参数调优（遵循 [ADR-0003](./docs/adr/0003-runtime-configuration-and-security-posture.md)）：

| 环境变量名称 | 默认值 | 作用说明 |
| :--- | :--- | :--- |
| `MCP_TCP_MAX_CONNECTIONS` | `10` | 连接池最大允许的并发连接数配额上限 |
| `MCP_TCP_IDLE_TIMEOUT_SECONDS` | `300.0` | 连接空闲自愈阈值（秒），超过此时间未活动的连接将被后台协程自动回收 |
| `MCP_TCP_ALLOW_PRIVATE_NETWORKS` | `true` | 是否允许连接本地回环（`127.0.0.1`）与私有网段（RFC 1918）。企业安全受限环境可置为 `false` 一键拦截 |

> 🔒 **强制安全防线**：无论如何配置，公有云敏感元数据端点（AWS/GCP/Azure `169.254.169.254`、阿里云 `100.100.100.200` 等）均被绝对硬性阻断，保障宿主网络免受 SSRF 渗透。


---

## 💻 本地开发与测试

```bash
# 1. 检出仓库并激活 Git 规范提交守护钩子
git clone https://github.com/atengk/mcp-server-tcp.git
cd mcp-server-tcp
git config core.hooksPath .githooks

# 2. 安装开发依赖（推荐使用现代化 uv 工具链）
uv sync --all-extras
# 或使用传统 pip 模式：pip install -e ".[test]" && pip install ruff

# 3. 静态代码检查与格式校验
uv run ruff check .
uv run ruff format --check .

# 4. 运行全量单元测试与覆盖率统计
uv run pytest --cov

```

---

## 📦 自动发版与分发流水线

本项目内置双通道自动化发版体系：
1. **GitHub 网页端发版**：在 Actions 中选择 **GitHub Release** 输入版本号（如 `v1.0.0`），自动提取更新日志、创建 Tag 并级联触发 PyPI 与 Docker 镜像发布；
2. **本地脚本发版**：
   ```bash
   bash scripts/release.sh v1.0.0 -y
   ```


---

## 📂 仓库目录结构

```text
.
├── .github/
│   ├── ISSUE_TEMPLATE/             # Issue 缺陷与需求模版
│   ├── workflows/
│   │   ├── ci.yml                  # PR 标题校验、Shell 脚本守门与 Python 矩阵测试
│   │   ├── release.yml             # 双通道发版与 git-cliff 更新日志提取
│   │   ├── publish.yml             # PyPI 发行包自动发布
│   │   └── docker.yml              # 多架构 GHCR 容器镜像构建与发布
│   ├── CODEOWNERS                  # 代码所有者自动审阅配置
│   ├── dependabot.yml              # Actions、Python 与 Docker 依赖月度自动巡检
│   └── PULL_REQUEST_TEMPLATE.md    # PR 提交规范模版
├── .githooks/
│   └── commit-msg                  # 原生 Git 提交规范守门钩子
├── scripts/
│   ├── commit.sh                   # 规范化交互式提交助手
│   └── release.sh                  # 全生命周期发版防呆脚本
├── src/
│   └── mcp_server_tcp/             # TCP MCP Server 核心实现
├── tests/                          # 自动化端到端与单元测试集
├── docs/
│   ├── adr/                        # 关键架构决策记录 (ADR)
│   └── agents/                     # 智能体协作与规范文档
├── .cliff.toml                     # git-cliff 变更日志分类配置
├── CONTEXT.md                      # 核心领域模型与术语词汇表
├── Dockerfile                      # 生产级多架构轻量镜像构建
├── pyproject.toml                  # 现代 Python 打包与依赖配置
├── CONTRIBUTING.md                 # 贡献指南
└── LICENSE                         # Apache-2.0 许可证
```

---

## 🤝 参与贡献

欢迎任何形式的贡献！提交代码前请仔细阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。
