---
name: localsend-mcp
description: LocalSend-based P2P transfer with MCP server design for NATS/Tailscale discovery and throughput tuning.
source: local
license: UNLICENSED
---

# LocalSend MCP Skill

## Use This Skill When
- The user mentions LocalSend, AirDrop-like transfer, or peer-to-peer file sharing.
- The task asks for an MCP server or tool set around LocalSend.
- Discovery/advertising needs to use NATS or Tailscale before transferring data.

## Reality Check (LocalSend in This Repo)
- `localsend` (Flox package) launches a GUI and does not exit for `--help`.
- Discovery uses UDP multicast `224.0.0.167:53317` (LAN only).
- Transfer runs HTTPS on port `53317`; direct IPs are required across subnets.
- For headless automation, prefer a CLI client (e.g., `jocalsend`) or a small protocol wrapper.

## Architecture: Advertise -> Negotiate -> Transfer -> Tune

1. **Advertise** capabilities over NATS (or Tailscale if LAN multicast is blocked).
2. **Negotiate** transport and parameters (LAN multicast vs direct IP).
3. **Transfer** via LocalSend protocol/CLI.
4. **Tune** throughput until spectral gap <= 0.25 (>= 75% of target throughput).

## MCP Tool Set (Draft)

**Discovery / Advertising**
- `localsend_advertise`:
  - Inputs: `agent_id`, `device_name`, `localsend_port`, `tailscale_ip?`, `capabilities`, `spectral_gap_target`
- `localsend_list_peers`:
  - Inputs: `source` = `localsend_multicast` | `nats` | `tailscale`

**Session Negotiation**
- `localsend_negotiate`:
  - Inputs: `peer_id`, `preferred_transport`, `max_chunk_bytes`, `max_parallel`
  - Output: `session_id`, `transport`, `target_ip`, `port`

**Transfer**
- `localsend_send`:
  - Inputs: `session_id`, `file_path`, `chunk_bytes`, `parallelism`
- `localsend_receive`:
  - Inputs: `session_id`, `dest_dir`, `accept`

**Throughput Tuning**
- `localsend_probe`:
  - Inputs: `session_id`, `probe_bytes`, `probe_parallelism`
  - Output: `throughput_bps`, `rtt_ms`, `loss_rate`
- `localsend_session_status`:
  - Inputs: `session_id`
  - Output: `bytes_sent`, `bytes_received`, `throughput_bps`, `spectral_gap`

## Spectral Gap Heuristic (Practical)

Define:
```
spectral_gap = 1.0 - (observed_throughput / target_throughput)
```
Stop tuning when `spectral_gap <= 0.25`.

**Tuning Loop**:
1. Start `chunk_bytes = 256KB`, `parallelism = 1`
2. Increase parallelism to 2, 4, 8 while loss < 1%
3. Increase chunk size up to 1MB while RTT stable
4. Recompute spectral gap each step

## Integration Points in This Repo
- NATS broadcast helpers: `lib/synadia_broadcast.rb`
- Tailscale patterns: `lib/tailscale_file_transfer_skill.rb`
- MCP server reference: `mcp_unified_server.py`

## Implementation Notes
- Avoid assuming LocalSend has a stable CLI; verify with `jocalsend --help` if installed.
- If multicast discovery fails (Tailscale), use NATS to exchange `target_ip` + `port`.
- Keep tool outputs structured; avoid dumping large blobs through MCP.