STARWARCLOUD STARWAR.AI
返回市场
Tcp套接字MCP

Tcp套接字MCP

作者：SpaceyKasey8 星标更新：2025-08-17
安装使用来源：spider==github.com

项目介绍

TCP Socket MCP Server

CI 状态 测试覆盖率 质量门控 PyPI 版本 PyPI 下载量 Python 支持版本

一个提供原始TCP套接字访问的模型上下文协议（MCP）服务器，使AI模型能够通过原始TCP套接字直接与网络服务交互。支持多并发连接、响应数据缓冲以及触发自动响应。

动机和背景

许多网络服务和物联网设备使用原始TCP协议进行通信，这些协议未被现有的基于HTTP的MCP服务器覆盖。TcpSocketMCP实现了以下功能：

  • 直接与嵌入式设备和物联网系统交互
  • 网络协议调试和测试
  • 无需HTTP包装器的遗留系统集成
  • 协议逆向工程和分析
  • 通过触发模式实现自动化响应（对于IRC、telnet、自定义协议非常有用）

这满足了社区成员对低级网络访问的需求，特别是在工业自动化、物联网开发和网络安全测试场景中。

演示

演示 1 查询设备以确定其类型

演示 2 向设备发送数据

输出示例 来自TCP交互的样本输出

安装与设置

从PyPI安装

# 使用pip安装
pip install TcpSocketMCP

# 使用uv安装（推荐）
uv add TcpSocketMCP

# 添加到Claude Code（推荐）
claude mcp add rawtcp -- uvx TcpSocketMCP

对于Claude Desktop

在您的Claude Desktop配置文件中添加服务器：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

选项 1：使用已安装的包（推荐）

{
  "mcpServers": {
    "tcp-socket": {
      "command": "TcpSocketMCP",
      "env": {}
    }
  }
}

选项 2：从源代码

{
  "mcpServers": {
    "tcp-socket": {
      "command": "python",
      "args": ["/path/to/tcp-socket-mcp/run.py"],
      "env": {}
    }
  }
}

开发设置

# 克隆仓库
git clone https://github.com/kaseyk/tcp-socket-mcp.git
cd tcp-socket-mcp

# 使用uv安装（推荐）
uv pip install -e .

# 或者使用pip安装
pip install -e .

# 直接运行服务器
python run.py

# 或者使用命令
TcpSocketMCP

可用工具

一旦通过MCP配置，以下工具将对AI模型可用：

核心连接工具

tcp_connect

打开到任何主机端口的TCP连接

  • 返回用于后续操作的connection_id
  • 支持为预注册触发器设置自定义connection_id
  • 示例：tcp_connect("example.com", 80)

tcp_send

通过已建立的连接发送数据

  • 编码选项：utf-8，hex（建议用于二进制），base64
  • 十六进制格式：如"48656C6C6F"表示"Hello"
  • 终止符：可选的十六进制后缀如"0D0A"表示CRLF

tcp_read_buffer

从连接缓冲区读取接收的数据

  • 发送后数据可能不会立即可用
  • 缓冲区存储所有接收的数据直到清除
  • 支持部分读取的index/count
  • 格式选项：utf-8，hex，base64

tcp_disconnect

关闭连接并释放资源

  • 完成时始终关闭连接
  • 所有触发器自动移除

高级特性

tcp_set_trigger

为模式匹配设置自动响应

  • 预注册：在连接前设置触发器以立即激活
  • 支持带有捕获组的正则表达式模式（如$1，$2）
  • 当模式匹配时自动触发响应
  • 适用于协议握手（如IRC PING/PONG等）

tcp_connect_and_send

在一个原子操作中结合连接和发送

  • 对于时间敏感的协议至关重要
  • 适用于即时握手或抓取欢迎信息
  • 返回connection_id用于进一步操作

实用工具

  • tcp_list_connections：查看所有活动连接及其统计信息
  • tcp_connection_info：获取特定连接的详细信息
  • tcp_buffer_info：检查缓冲区统计信息而不读取数据
  • tcp_clear_buffer：从缓冲区清除接收的数据
  • tcp_remove_trigger：移除特定的自动响应触发器

使用示例

基本TCP通信

# 连接到服务
conn_id = tcp_connect("example.com", 80)

# 发送数据（建议使用十六进制编码）
tcp_send(conn_id, "474554202F20485454502F312E310D0A", encoding="hex")  # GET / HTTP/1.1\r\n

# 读取响应（可能需要等待数据）
response = tcp_read_buffer(conn_id)

# 清理
tcp_disconnect(conn_id)

自动化协议处理

# 预注册IRC PING/PONG触发器
tcp_set_trigger("irc-conn", "ping-handler", "^PING :(.+)", "PONG :$1\r\n")

# 使用预注册触发器连接
tcp_connect("irc.server.com", 6667, connection_id="irc-conn")
# PING响应现在会自动发生！

处理二进制协议

# 使用十六进制编码进行精确字节控制
tcp_send(conn_id, "0001000400000001", encoding="hex")  # 二进制协议头

# 以十六进制格式读取响应以便分析
response = tcp_read_buffer(conn_id, format="hex")

重要注意事项

十六进制编码用于行尾

许多文本协议（HTTP、SMTP、IRC）需要特定的行尾。使用十六进制编码可以避免JSON转义问题：

# 常见的十六进制序列：
# 0D0A     = \r\n (CRLF) - HTTP、SMTP、IRC
# 0A       = \n (LF) - Unix行尾
# 0D0A0D0A = \r\n\r\n - HTTP头部终止符
# 00       = 空字节 - 二进制协议

时间考虑

  • 网络响应不是即时的 - 使用tcp_buffer_info检查数据
  • 考虑实现带有小延迟的重试逻辑
  • 缓冲区累积所有接收的数据 - 在需要时清除

🧪 测试与质量

TcpSocketMCP通过全面测试维持企业级质量：

测试覆盖率

  • 85%覆盖率（超过80%目标）
  • 80多个全面测试涵盖所有组件
  • 跨平台测试（Ubuntu、Windows、macOS）
  • Python 3.10-3.12支持

质量门控

  • GitHub Actions中的自动化CI/CD
  • Bandit和Safety的安全扫描
  • Ruff和MyPy的代码质量分析
  • 性能监控和复杂性分析

本地运行测试

# 安装测试依赖项
uv pip install -e .
uv pip install pytest pytest-asyncio pytest-cov

# 运行完整的测试套件并生成覆盖率报告
uv run pytest tests/ --cov=src/TcpSocketMCP --cov-report=term-missing

# 快速测试运行
uv run pytest

参见TESTING.md以获取全面的测试文档。

许可证

MIT