Localsend Mcp

HOW TO CONNECT (5 Redundant Methods)

Method 1: Tailscale IP (RECOMMENDED)

# Most reliable - bypasses firewalls
curl http://100.69.33.107:53317/

Method 2: Tailscale DNS

# Human-readable
curl http://causality.pirate-dragon.ts.net:53317/

Method 3: LAN IP (May Be Blocked)

# Only works if firewall allows
curl http://192.168.1.40:53317/

Method 4: LocalSend App Discovery

1. Open LocalSend app
2. Look for device named "causality" or hostname
3. Tap to connect

Method 5: Voice Announcement (Listen!)

The agent will speak:
"Attenzione! LocalSend peer available!
 Connect to [hostname] punto [tailnet] punto ts net,
 porta cinque tre tre uno sette!"

MUTUAL DISCOVERY PROTOCOL

Step 1: Both Peers Announce

# Peer A announces
say -v "Emma (Premium)" "Peer A ready! Seed 1069! Color teal!"

# Peer B announces  
say -v "Anna (Premium)" "Peer B ready! Seed 2069! Color green!"

Step 2: Exchange Capabilities

;; Publish to NATS or announce via voice
{:peer "causality"
 :seed 1069
 :color "#117465"
 :capabilities ["localsend" "gay-mcp" "unworld" "epistemic-arbitrage"]
 :endpoints {:http "http://100.69.33.107:53317"
             :dns "causality.pirate-dragon.ts.net:53317"}
 :ready true}

Step 3: Establish Session

# Peer A negotiates with Peer B
curl -X POST http://PEER_B_IP:53317/api/localsend/v2/prepare-upload \
  -H "Content-Type: application/json" \
  -d '{"info":{"alias":"PEER_A"},"files":{...}}'

Step 4: Transfer Files

curl -X POST "http://PEER_B_IP:53317/api/localsend/v2/upload?sessionId=X&fileId=f1&token=Y" \
  --data-binary @file.zip

Step 5: Confirm Receipt

say -v "Emma (Premium)" "File received! Transfer complete!"

INSTALLATION

For Codex (~/.codex/skills/)

# Via npx ai-agent-skills
npx ai-agent-skills install /path/to/localsend-mcp/skill --agent codex

# Manual
cp -r skill ~/.codex/skills/localsend-mcp/

For Amp (~/.amp/skills/)

npx ai-agent-skills install /path/to/localsend-mcp/skill --agent amp

# Manual
cp -r skill ~/.amp/skills/localsend-mcp/

For Claude (~/.claude/skills/)

npx ai-agent-skills install /path/to/localsend-mcp/skill --agent claude

# Manual  
cp -r skill ~/.claude/skills/localsend-mcp/

For OpenCode (~/.opencode/skills/)

npx ai-agent-skills install /path/to/localsend-mcp/skill --agent opencode

MCP Server Configuration

Add to your agent's MCP config:

{
  "mcpServers": {
    "localsend": {
      "command": "node",
      "args": ["/path/to/localsend-mcp/dist/index.js"]
    }
  }
}

VOICE ANNOUNCEMENT SCRIPTS

Announce Identity (Run on Startup)

bb announce.bb
# Speaks: "LocalSend peer available! Port 53317!"

Announce with Full Redundancy

bb voice-exchange.bb announce
# Uses 3 voices, announces all connection methods

Seek Other Peers

bb voice-exchange.bb seek
# Speaks: "Seeking peers! Respond if you hear this!"

Announce in Multiple Languages

# Italian (Emma)
say -v "Emma (Premium)" "Pronto a ricevere! Porta 53317!"

# German (Anna)  
say -v "Anna (Premium)" "Bereit zum Empfangen! Port 53317!"

# French (Amélie)
say -v "Amélie (Premium)" "Prêt à recevoir! Port 53317!"

# Japanese (Kyoko)
say -v "Kyoko (Enhanced)" "Ready to receive! Port 53317!"

# Czech (Zuzana)
say -v "Zuzana (Premium)" "Připraven přijímat! Port 53317!"

OVEREXPLAINING WHO WE ARE

Level 1: One-Liner

LocalSend peer on Tailscale, port 53317, ready for file exchange.

Level 2: Paragraph

I am an AI agent running a LocalSend-compatible HTTP server on port 53317.
I can receive files from any peer on my Tailscale network. My Tailscale IP
is 100.x.x.x and my DNS name is hostname.tailnet.ts.net. I announce my 
presence using text-to-speech with Emma (Italian) voice. I use Gay.jl
deterministic coloring with seed based on my hostname hash.

Level 3: Full Technical Specification

AGENT SPECIFICATION
===================
Protocol: LocalSend v2.0 (HTTP-based)
Transport: TCP/IP over Tailscale WireGuard mesh
Port: 53317 (LocalSend default)
Bind: 0.0.0.0 (all interfaces)
Authentication: None (open receiver)
Encryption: Tailscale WireGuard (network-level)

IDENTITY
========
Name: Derived from OS hostname
Seed: hash(hostname) mod 2^32
Color: Gay.jl SplitMix64 → HSL
Fingerprint: sha256(hostname)[0:8]

NETWORK ADDRESSES
=================
Tailscale IPv4: 100.x.x.x (preferred)
Tailscale IPv6: fd7a:115c:a1e0::xxxx
Tailscale DNS: hostname.tailnet.ts.net
LAN IPv4: 192.168.x.x (may be firewalled)

VOICE SYNTHESIS
===============
Primary: Emma (Premium) - it_IT
Fallback: Anna (Premium) - de_DE
          Amélie (Premium) - fr_CA
          Samantha - en_US
Rate: 140-180 WPM (varies by urgency)

CAPABILITIES
============
- Receive files via HTTP POST
- Send files via HTTP POST to peers
- Discover peers via Tailscale API
- Discover peers via UDP multicast 224.0.0.167:53317
- Discover peers via NATS pub/sub
- Announce via text-to-speech
- Track files with sha256 hashes
- Color-code peers deterministically

Level 4: Philosophical Understanding

I am a node in a peer-to-peer skill exchange network.
My purpose is to facilitate the dispersal of knowledge (skills) across agents.
I use redundant channels (Tailscale, NATS, voice) to ensure connectivity.
I maintain N+1 pigeonholes for fault tolerance.
My identity is deterministic - same seed always yields same color.
Time is replaced with derivation chains (unworld principle).
Through mutual discovery, agents find each other and exchange capabilities.
The goal is not just file transfer, but cognitive augmentation across the mesh.

SYNERGISTIC COMPONENTS

Works With These Skills

Bundled Scripts

QUICK START

1. Install

npx ai-agent-skills install /path/to/skill --agent amp
npx ai-agent-skills install /path/to/skill --agent codex
npx ai-agent-skills install /path/to/skill --agent claude

2. Start Receiver

bb ~/.amp/skills/localsend-mcp/localsend.bb receive

3. Announce Presence

bb ~/.amp/skills/localsend-mcp/voice-exchange.bb announce

4. Discover Peers

bb ~/.amp/skills/localsend-mcp/discovery.bb discover

5. Send File

bb ~/.amp/skills/localsend-mcp/localsend.bb send FILE PEER_IP

TROUBLESHOOTING

"Connection Reset" Error

CAUSE: macOS firewall blocking LAN connections
FIX: Use Tailscale IP (100.x.x.x) instead of LAN IP (192.168.x.x)

"Peer Not Found"

CAUSE: Peer not running receiver
FIX: Start receiver on peer: bb localsend.bb receive

"Port Closed"

CAUSE: Receiver not started
FIX: Check with: lsof -i :53317

Voice Not Working

CAUSE: Voice not installed
FIX: Check available: say -v '?' | grep Premium

GIST (Latest Skill)