AgentSkillsCN

localsend-mcp

基于LocalSend的P2P传输方案，结合MCP服务器设计，支持NATS/Tailscale的发现机制与吞吐量调优。

SKILL.md
--- frontmatter
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:

code
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.