Metadata-Version: 2.4
Name: da2-mcp-socket
Version: 0.2.0
Summary: A Socket TCP/IP MCP Server - enables AI assistants to communicate via TCP/IP sockets
Project-URL: Homepage, https://da2.35g.tw
Project-URL: Repository, https://github.com/anthropics/mcp
Project-URL: Documentation, https://da2.35g.tw
Author-email: Danny <danny@35g.tw>, DA2 Studio <contact@35g.tw>
License: MIT
License-File: LICENSE
Keywords: ai,claude,cursor,ip,llm,mcp,network,socket,tcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Socket MCP Server

A powerful Model Context Protocol (MCP) Server designed for **AI-assisted development**. It enables your AI assistant to communicate via TCP/IP sockets directly.

## Key Features

*   **Easy Integration**: Connect to any TCP/IP device or service
*   **Ready to Use**: Simple `pip` installation with zero complex setup
*   **Multi-Connection**: Manage multiple socket connections simultaneously
*   **Packet Protocol**: Custom start/end delimiter packet parsing
*   **Background Listener**: Auto-receive and buffer packets with drop_oldest overflow policy
*   **Data Transmission**: Send/receive text or binary (hex) data
*   **Dual Execution Modes**: Supports STDIO (default) and HTTP modes

## Installation

Ensure you have Python 3.10 or higher installed.

```bash
pip install da2-mcp-socket
```

## Quick Start

```bash
# STDIO mode (for Cursor/Claude Desktop)
da2-mcp-socket

# HTTP mode (for Antigravity)
da2-mcp-socket --http --port 8000
```

## Client Configuration

### Cursor / Claude Desktop

```json
{
  "mcpServers": {
    "socket": {
      "command": "da2-mcp-socket",
      "args": [],
      "env": { "LOG_LEVEL": "INFO" }
    }
  }
}
```

### Antigravity

```json
{
  "mcpServers": {
    "socket": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}
```

---

## Available Tools (15)

### Connection Management
| Tool | Description |
| :--- | :--- |
| **connect** | Connect to a TCP server (host:port) |
| **disconnect** | Close a specific connection |
| **get_connection_status** | Get status of active connection(s) |

### Data Transmission
| Tool | Description |
| :--- | :--- |
| **send_data** | Send text or hex data through a connection |
| **receive_data** | Receive data from a connection (with timeout) |
| **receive_line** | Receive a line (until newline character) |
| **receive_until** | Receive until a specific terminator |

### Protocol Management
| Tool | Description |
| :--- | :--- |
| **set_protocol** | Configure receive mode (raw/line/packet) with custom delimiters |
| **receive_packet** | Receive complete packet based on configured protocol |
| **get_protocol** | Get current protocol settings for a connection |

### Background Listener
| Tool | Description |
| :--- | :--- |
| **start_listening** | Start background listener thread |
| **stop_listening** | Stop background listener |
| **get_packets** | Get all buffered packets (clears buffer) |
| **get_buffer_status** | Query buffer status (count/overflow) |

### Server Info
| Tool | Description |
| :--- | :--- |
| **get_server_info** | Get server version and default settings |

---

## Usage Examples

### RFID Reader Connection (AL-510)

```python
# 1. Connect to device
connect("192.168.248.70", 1001)

# 2. Set packet protocol: <0x0A>[data]<0x0D0A>
set_protocol("conn_id", mode="packet", 
             start_delimiter_hex="0A", 
             end_delimiter_hex="0D0A")

# 3. Send command (Inventory EPC+TID)
send_data("conn_id", "0A4055322C52322C302C360D", as_hex=True)

# 4. Receive packet
receive_packet("conn_id", timeout=5.0)
# → @2000/01/01 01:31:11.981-Antenna1-U3000E300...,RE28069952...

# 5. Disconnect
disconnect("conn_id")
```

### Background Continuous Listening

```python
# 1. Connect and set protocol
connect("192.168.248.70", 1001, max_buffer_packets=100)
set_protocol("conn_id", mode="packet", start_delimiter_hex="0A", end_delimiter_hex="0D0A")

# 2. Start background listener
start_listening("conn_id")

# 3. Get accumulated packets anytime
get_packets("conn_id")
# → { packets: [{data_hex, data_text, timestamp}, ...], count: 5 }

# 4. Query buffer status
get_buffer_status("conn_id")
# → { buffer: { count: 5, max: 100, overflow_count: 0 } }

# 5. Stop listening
stop_listening("conn_id")
```

### HTTP Request

```python
connect("example.com", 80)
send_data("conn_id", "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
receive_data("conn_id", size=4096, timeout=5.0)
disconnect("conn_id")
```

---

## Default Settings

| Parameter | Default Value |
| :--- | :--- |
| **Connection Timeout** | 10.0 seconds |
| **Read Timeout** | 5.0 seconds |
| **Buffer Size** | 4096 bytes |
| **Max Buffer Packets** | 100 |
| **Overflow Policy** | drop_oldest |

---

## License

MIT License

Copyright (c) 2026 Danny, DA2 Studio (https://da2.35g.tw)

