Skip to content

feat: local HTTP daemon for Stream Deck and VoiceAttack triggers - #20

Draft
NyleGarcia wants to merge 1 commit into
mainfrom
claude/mcp-streamdeck-voice-attack-nxalpy
Draft

NyleGarcia wants to merge 1 commit into
mainfrom
claude/mcp-streamdeck-voice-attack-nxalpy

Conversation

@NyleGarcia

Copy link
Copy Markdown
Collaborator

Why

Stream Deck and VoiceAttack can launch a process or hit a URL. Neither speaks MCP — it's a stdio JSON-RPC protocol owned by the host that spawns the server, so there's no port to hit and no way for a button press to complete a handshake, list tools, and call one.

Rather than shelling out to claude -p (a full agent boot and two model round trips to run what is fundamentally a parameterised HTTP GET, while you're flying), this adds a second adapter over the same tools.

What changed

The tool handlers were welded into the CallToolRequestSchema closure, so nothing else could call them. They now live in a shared registry:

File Role
src/tools.ts Tool registry — clients, cache, all 11 handlers
src/index.ts MCP stdio adapter (behaviour unchanged)
src/http.ts New localhost daemon
src/voice.ts TTS-shaped output presets
src/ask.ts Natural-language path

Endpoints

Route Returns Cost
GET /q/:tool?args Raw JSON Free, ~ms from cache
GET /say/:preset?args One plain-English sentence Free
GET|POST /ask?q=... One sentence, via the model API credit, seconds
GET /health, /tools, /presets Discovery Free

Presets: sell, buy, route, top.

Design notes

Voice needs its own formatter, not just its own transport. Piping trade-route JSON into a speech synthesiser produces nothing usable, so /say renders a sentence and writes numbers and "S C U" the way TTS reads them correctly.

Presets degrade instead of throwing. UEX field names vary by endpoint and have moved between API revisions, so every field read goes through a candidate-key lookup and each preset falls back to a speakable diagnostic. I could not verify the price and route field names against live UEX from the build environment (egress policy blocks api.uexcorp.space), which is exactly why this is defensive — worth one check against /q/uex_get_trade_routes on a machine with a token.

/ask skips MCP entirely. MCP is the adapter Claude Code needs to spawn this project as a subprocess; in-process the registry goes straight to the SDK tool runner. It also caps tool output at 8k characters rather than 40k — an unfiltered trade-routes response is ~10k tokens and dominates the bill on that path.

Security. The daemon binds to 127.0.0.1 and rejects requests carrying browser headers (Origin, cross-site Sec-Fetch-Site), so a page you happen to visit can't quietly spend API credit against /ask. SCMCP_HTTP_TOKEN gates other local processes.

Bugs found and fixed along the way

  • dotenv v17 printed a startup banner to stdout, corrupting the MCP JSON-RPC stream. This affected every MCP session on main, not just the new code. Now dotenv.config({ quiet: true }).
  • install.sh computed MCP_ENV and never used it, so UEXTOKEN never reached the MCP registration — it only worked if the variable happened to be exported globally.
  • axios 1.14 mishandles HTTPS proxies; upgraded to 1.19 (the existing ^1.14.0 range already permitted it).

Testing

57 tests across 4 files, up from 1 placeholder.

src/mcp.test.ts spawns the built server and asserts every stdout line parses as JSON-RPC. It has to be a subprocess test — I first wrote this in-process and it passed with the dotenv bug reintroduced, because the test runner replaces stdout before any import runs. The subprocess version fails 4 tests with the bug present and passes with it fixed; I verified both directions. pretest compiles first, since CI runs tests before build.

The rest covers arg coercion, optimizeData/formatOutput budgets, every voice preset including its degradation paths, and daemon routing and the request guard. All offline.

Integrations

  • integrations/streamdeck/scmcp.ps1 — bind to System → Open; fetches and speaks the answer
  • integrations/voiceattack/SCMCP.cs — inline C#, avoids the console-window flash of shelling out mid-game
  • integrations/voiceattack/generate-grammar.mjs — builds a closed [Gold;Laranite;...] phrase list from live commodity data; dictation mis-hears "Laranite" far more often than a fixed grammar does

Not included

A proper Stream Deck plugin (@elgato/streamdeck) that renders answers on the key face rather than only speaking them. The daemon already returns everything one would need from /q/* — happy to add it as a follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HcVUQaPfMoyAhj94KM5ZDf


Generated by Claude Code

Stream Deck and VoiceAttack can launch a process or hit a URL, but neither
speaks MCP — it is a stdio protocol owned by the host that spawns the server.
This adds a second adapter over the same tools so both devices can reach them.

Extract the tool handlers out of the MCP request-handler closure into a shared
registry (src/tools.ts). src/index.ts is now a thin stdio adapter with identical
behaviour; src/http.ts is a new localhost daemon exposing:

  GET /q/:tool      raw JSON, no model, answers from cache in milliseconds
  GET /say/:preset  one plain-English sentence shaped for text-to-speech
  GET|POST /ask     natural language via the Anthropic API, for open-ended
                    questions no preset can answer

The voice presets need their own formatter, not just their own transport —
piping trade-route JSON into a speech synthesiser is useless. UEX field names
vary by endpoint, so each preset reads through candidate key lists and degrades
to a speakable diagnostic rather than throwing.

/ask goes straight to the SDK tool runner rather than back through MCP, and
caps tool output at 8k characters instead of 40k: an unfiltered trade-routes
response is the dominant cost driver on that path.

The daemon binds to 127.0.0.1 and rejects browser-originated requests, so a page
you happen to visit cannot spend API credit against /ask. SCMCP_HTTP_TOKEN gates
other local processes.

Also included:

- fix: silence the dotenv v17 startup banner, which printed to stdout and
  corrupted the MCP JSON-RPC stream on every session. Added subprocess contract
  tests against the built server that catch it; in-process assertions cannot,
  because the test runner replaces stdout before any import runs.
- fix: install.sh computed MCP_ENV but never passed it, so UEXTOKEN never
  reached the MCP registration.
- chore: upgrade axios to 1.19 (1.14 mishandles HTTPS proxies).

Integrations: a PowerShell script for Stream Deck keys, a VoiceAttack inline C#
function (avoids the console-window flash of shelling out), and a generator that
builds a closed VoiceAttack phrase list from live commodity data — dictation
mis-hears "Laranite" far more often than a fixed grammar does.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HcVUQaPfMoyAhj94KM5ZDf
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants