plurigrid/asi / ies/music-topos/.codex/skills/localsend-mcp
localsend-mcp
VerifiedLocalSend-based P2P transfer with MCP server design for NATS/Tailscale discovery and throughput tuning.
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
- Advertise capabilities over NATS (or Tailscale if LAN multicast is blocked).
- Negotiate transport and parameters (LAN multicast vs direct IP).
- Transfer via LocalSend protocol/CLI.
- 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
- Inputs:
localsend_list_peers:- Inputs:
source=localsend_multicast|nats|tailscale
- Inputs:
Session Negotiation
localsend_negotiate:- Inputs:
peer_id,preferred_transport,max_chunk_bytes,max_parallel - Output:
session_id,transport,target_ip,port
- Inputs:
Transfer
localsend_send:- Inputs:
session_id,file_path,chunk_bytes,parallelism
- Inputs:
localsend_receive:- Inputs:
session_id,dest_dir,accept
- Inputs:
Throughput Tuning
localsend_probe:- Inputs:
session_id,probe_bytes,probe_parallelism - Output:
throughput_bps,rtt_ms,loss_rate
- Inputs:
localsend_session_status:- Inputs:
session_id - Output:
bytes_sent,bytes_received,throughput_bps,spectral_gap
- Inputs:
Spectral Gap Heuristic (Practical)
Define:
spectral_gap = 1.0 - (observed_throughput / target_throughput)
Stop tuning when spectral_gap <= 0.25.
Tuning Loop:
- Start
chunk_bytes = 256KB,parallelism = 1 - Increase parallelism to 2, 4, 8 while loss < 1%
- Increase chunk size up to 1MB while RTT stable
- 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
<<<<<<< HEAD
GitHub GraphQL (GH CLI) Reference
Use gh api graphql for contributor snapshots (limit: history(first: 100)):
gh api graphql \
-F owner=localsend \
-F name=localsend \
-F history=100 \
-f query='query($owner:String!,$name:String!,$history:Int!){
repository(owner:$owner,name:$name){
defaultBranchRef{name target{
... on Commit{
history(first:$history){
nodes{author{user{login} name}}
}
}
}}
}
}'
Aggregate top contributors:
gh api graphql -F owner=localsend -F name=localsend -F history=100 -f query='query($owner:String!,$name:String!,$history:Int!){repository(owner:$owner,name:$name){defaultBranchRef{name target{... on Commit{history(first:$history){nodes{author{user{login} name}}}}}}}}' \
| jq -r '.data.repository.defaultBranchRef.target.history.nodes[].author | if .user then .user.login else .name end' \
| sort | uniq -c | sort -nr | head -20
Duck Lake Snapshots (Feedback + Bidirectional Flow)
Persist LocalSend sessions and GitHub snapshots into DuckDB for time travel:
CREATE TABLE IF NOT EXISTS localsend_sessions (
session_id TEXT,
peer_id TEXT,
direction TEXT, -- send|receive
bytes BIGINT,
throughput_bps DOUBLE,
spectral_gap DOUBLE,
created_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS localsend_contributors_snapshot (
snapshot_at TIMESTAMP,
repo TEXT,
contributor TEXT,
commit_count INT
);
Store snapshots per run and query later with existing DuckDB time-travel commands.
origin/feature/skill-connectivity-hub-20251226
Implementation Notes
- Avoid assuming LocalSend has a stable CLI; verify with
jocalsend --helpif installed. - If multicast discovery fails (Tailscale), use NATS to exchange
target_ip+port. - Keep tool outputs structured; avoid dumping large blobs through MCP.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |