Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,81 @@ A Model Context Protocol (MCP) server providing real-time access to Star Citizen
- `sct_search`: Search Star Citizen Tools (starcitizen.tools) for any topic.
- `sct_get_article`: Get the text content of an article from Star Citizen Tools (e.g. for lore, character info, or detailed guides).

## Triggering from a Stream Deck or VoiceAttack

Stream Deck and VoiceAttack can launch a process or hit a URL; neither speaks MCP, which is a stdio protocol owned by the host that spawns it. So alongside the MCP server there is a **local daemon** that puts the same tools behind plain HTTP on `127.0.0.1`.

```bash
npm run build
npm run daemon # http://127.0.0.1:7331
```

Both entry points share one tool registry (`src/tools.ts`); `src/index.ts` is the MCP adapter and `src/http.ts` is the HTTP one.

### Endpoints

| Route | Returns | For |
|---|---|---|
| `GET /health` | JSON status | Checking the daemon is up |
| `GET /tools` | Tool names and schemas | Discovery |
| `GET /presets` | Voice preset names and params | Discovery |
| `GET /q/:tool?args` | Raw JSON | Stream Deck keys, scripts |
| `GET /say/:preset?args` | One plain-English sentence | Text-to-speech |
| `GET/POST /ask?q=...` | One sentence, via the model | Open-ended questions |

`/q/*` is a direct call — no model, no cost, and answers from the 5-minute cache in milliseconds. `/ask` runs the question through Claude with the same tools available and takes a few seconds, so use it only where a preset can't answer.

```bash
curl "http://127.0.0.1:7331/say/sell?commodity=Gold"
# Gold sells highest at Everus Harbor in Stanton, 32,500 per S C U.

curl "http://127.0.0.1:7331/say/route?scu=96&investment=1000000"
# Best route: buy Gold at HDMS-Stanhope, sell at Everus Harbor, for 450,000 profit.

curl "http://127.0.0.1:7331/q/uex_get_commodity_prices?commodity_name=Laranite"
```

Voice presets: `sell`, `buy`, `route`, `top`.

### Stream Deck

Bind a key to **System → Open**, pointing at `powershell.exe` with:

```
-ExecutionPolicy Bypass -File "C:\path\to\SCMCP\integrations\streamdeck\scmcp.ps1" -Preset sell -Arg commodity=Gold
```

The script fetches the answer and speaks it through the Windows synthesiser. Use `-Raw -NoSpeak` to print JSON instead, or `-Ask "..."` for a natural-language question. See `integrations/streamdeck/scmcp.ps1` for all options.

*Not yet built:* a proper Stream Deck plugin (`@elgato/streamdeck`) that renders the answer on the key face rather than only speaking it. The daemon already returns everything such a plugin needs from `/q/*`.

### VoiceAttack

Use the inline C# function in `integrations/voiceattack/SCMCP.cs` rather than shelling out — it avoids flashing a console window over the game. The file's header comments give the exact command layout.

For reliable recognition, prefer a **closed phrase list** over dictation. Generate one from live commodity data:

```bash
npm run voice:grammar # prints the list and suggested commands
npm run voice:grammar -- -o grammar.txt
```

That produces `[Gold;Laranite;Titanium;...]` for pasting into a command phrase, with the matched word exposed as `{TXT:1}`. Dictation mode still has its place — route `{DICTATION}` to `/ask` for open-ended lore and ship questions where the vocabulary isn't known ahead of time.

### Configuration

| Variable | Default | Purpose |
|---|---|---|
| `SCMCP_HTTP_PORT` | `7331` | Daemon port |
| `SCMCP_HTTP_TOKEN` | *(unset)* | Shared secret required on every request |
| `SCMCP_ASK_MODEL` | `claude-opus-5` | Model behind `/ask` |
| `SCMCP_ASK_EFFORT` | `low` | Reasoning effort for `/ask` |
| `ANTHROPIC_API_KEY` | *(unset)* | Required for `/ask`; every other route works without it |

The daemon binds to `127.0.0.1` only. It also rejects requests carrying browser headers (`Origin`, cross-site `Sec-Fetch-Site`), so a web page you happen to visit cannot quietly spend your API credit against `/ask`. Set `SCMCP_HTTP_TOKEN` if you want to gate other local processes too.

`/ask` defaults to `claude-opus-5`. If you'd rather trade some quality for latency and cost while flying, set `SCMCP_ASK_MODEL=claude-haiku-4-5` or `claude-sonnet-5`.

## Installation & Local Development

Create a `.env` file in the root directory and add your UEX API token:
Expand Down
16 changes: 13 additions & 3 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,22 @@ npm install
npm run build

MCP_COMMAND="node $(pwd)/dist/index.js"
MCP_ENV="UEXTOKEN=$UEXTOKEN"

# Pass UEXTOKEN through to the MCP registration. The server is spawned by the
# client in the client's working directory, so dotenv will not find this repo's
# .env file — without this the token has to be exported globally.
MCP_ENV_ARGS=()
if [ -n "$UEXTOKEN" ]; then
MCP_ENV_ARGS=(-e "UEXTOKEN=$UEXTOKEN")
else
echo "⚠️ UEXTOKEN is not set in this shell; registering without it."
echo " Set it and re-run, or add it to the MCP config by hand."
fi

echo ""
echo "Attempting to install Star Citizen MCP for Claude Code..."
if command -v claude &> /dev/null; then
claude mcp add scmcp $MCP_COMMAND
claude mcp add scmcp "${MCP_ENV_ARGS[@]}" -- $MCP_COMMAND
echo "✅ Successfully added to Claude Code."
else
echo "⚠️ Claude Code CLI not found. Skipping."
Expand All @@ -22,7 +32,7 @@ echo ""
echo "Attempting to install Star Citizen MCP for Gemini CLI..."
if command -v gemini &> /dev/null; then
# Assuming Gemini uses a similar plugin command or config structure
gemini mcp add scmcp $MCP_COMMAND
gemini mcp add scmcp "${MCP_ENV_ARGS[@]}" -- $MCP_COMMAND
echo "✅ Successfully added to Gemini."
else
echo "⚠️ Gemini CLI not found. To manually add, use the following command:"
Expand Down
121 changes: 121 additions & 0 deletions integrations/streamdeck/scmcp.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
<#
.SYNOPSIS
Query the SCMCP daemon from a Stream Deck key and optionally speak the answer.

.DESCRIPTION
Bind this to a Stream Deck "System > Open" action, or to a Multi Action, with
the App/File set to powershell.exe and the arguments set to:

-ExecutionPolicy Bypass -File "C:\path\to\scmcp.ps1" -Preset sell -Arg commodity=Gold

The daemon must already be running (npm run daemon).

.PARAMETER Preset
A voice preset name: sell, buy, route, top. Returns one spoken sentence.

.PARAMETER Tool
A raw tool name instead of a preset (e.g. uex_get_commodity_prices).
Returns JSON, which is useful with -Raw but not with -Speak.

.PARAMETER Ask
A natural-language question, routed through the model. Slower and costs
API credit; use a preset where one exists.

.PARAMETER Arg
Repeatable key=value query parameters, e.g. -Arg commodity=Gold -Arg system=Stanton

.PARAMETER Speak
Read the answer aloud through the Windows speech synthesiser. On by default
for presets and questions; ignored for -Tool.

.EXAMPLE
.\scmcp.ps1 -Preset sell -Arg commodity=Gold

.EXAMPLE
.\scmcp.ps1 -Preset route -Arg scu=96 -Arg investment=1000000

.EXAMPLE
.\scmcp.ps1 -Ask "what shields does a Carrack come with?"
#>
[CmdletBinding(DefaultParameterSetName = 'Preset')]
param(
[Parameter(ParameterSetName = 'Preset', Mandatory = $true)]
[string]$Preset,

[Parameter(ParameterSetName = 'Tool', Mandatory = $true)]
[string]$Tool,

[Parameter(ParameterSetName = 'Ask', Mandatory = $true)]
[string]$Ask,

[string[]]$Arg = @(),

[string]$BaseUrl = $(if ($env:SCMCP_URL) { $env:SCMCP_URL } else { 'http://127.0.0.1:7331' }),

[string]$Token = $env:SCMCP_HTTP_TOKEN,

[int]$TimeoutSec = 20,

[switch]$Raw,

[switch]$NoSpeak
)

$ErrorActionPreference = 'Stop'

function Get-QueryString {
param([string[]]$Pairs)
if (-not $Pairs -or $Pairs.Count -eq 0) { return '' }
$encoded = foreach ($pair in $Pairs) {
$split = $pair -split '=', 2
if ($split.Count -ne 2) { throw "Argument '$pair' must be in key=value form." }
'{0}={1}' -f [uri]::EscapeDataString($split[0]), [uri]::EscapeDataString($split[1])
}
'?' + ($encoded -join '&')
}

function Invoke-Scmcp {
param([string]$Path)
$headers = @{}
if ($Token) { $headers['X-SCMCP-Token'] = $Token }
# -UseBasicParsing keeps this working on hosts without Internet Explorer,
# and the loopback address is never proxied.
$response = Invoke-WebRequest -Uri ($BaseUrl + $Path) -Headers $headers `
-TimeoutSec $TimeoutSec -UseBasicParsing
return $response.Content
}

function Out-Speech {
param([string]$Text)
Add-Type -AssemblyName System.Speech
$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
try { $synth.Speak($Text) } finally { $synth.Dispose() }
}

$query = Get-QueryString -Pairs $Arg

switch ($PSCmdlet.ParameterSetName) {
'Preset' { $path = "/say/$([uri]::EscapeDataString($Preset))$query"; $speakable = $true }
'Tool' { $path = "/q/$([uri]::EscapeDataString($Tool))$query"; $speakable = $false }
'Ask' { $path = "/ask?q=$([uri]::EscapeDataString($Ask))"; $speakable = $true }
}

try {
$answer = Invoke-Scmcp -Path $path
}
catch {
# A dead daemon or a timeout should still tell you something out loud rather
# than opening a red console window you cannot read mid-flight.
$answer = 'The Star Citizen daemon did not respond.'
if (-not $NoSpeak -and $speakable) { Out-Speech -Text $answer }
Write-Error $_
exit 1
}

if ($Raw -or -not $speakable) {
Write-Output $answer
}

if ($speakable -and -not $NoSpeak) {
Out-Speech -Text $answer
}
125 changes: 125 additions & 0 deletions integrations/voiceattack/SCMCP.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
// VoiceAttack inline C# — query the SCMCP daemon and hand the answer back for TTS.
//
// Why inline C# rather than "Run an application": shelling out to curl or
// PowerShell flashes a console window over the game every time you speak. This
// runs in-process and is silent.
//
// SETUP
// 1. In VoiceAttack, edit a command and add:
// Other > Advanced > Execute an Inline Function > C# Code
// Paste this whole file in.
// 2. Before that action, add "Set a Text Value":
// ~path = /say/sell?commodity={TXT:~commodity}
// 3. After it, add:
// Other > Sounds > Say something with text-to-speech -> {TXT:~answer}
//
// A worked command, "where should I sell [Gold;Laranite;Titanium]":
// Set Text ~commodity to {TXT:1} (from the dynamic phrase list)
// Set Text ~path to /say/sell?commodity={TXT:~commodity}
// Inline C# (this file)
// Say with TTS {TXT:~answer}
//
// Optional text variables, all with sensible defaults:
// ~scmcpUrl base URL (default http://127.0.0.1:7331)
// ~scmcpToken shared secret (only if you set SCMCP_HTTP_TOKEN)
// ~timeoutMs request timeout (default 20000)
//
// Run integrations/voiceattack/generate-grammar.mjs to produce the
// [Gold;Laranite;...] phrase list from live commodity data.

using System;
using System.IO;
using System.Net;
using System.Text;

public class VAInline
{
public void main()
{
string answer;

try
{
string baseUrl = VA.GetText("~scmcpUrl");
if (string.IsNullOrEmpty(baseUrl)) baseUrl = "http://127.0.0.1:7331";

string path = VA.GetText("~path");
if (string.IsNullOrEmpty(path))
{
VA.SetText("~answer", "No request path was set.");
VA.WriteToLog("SCMCP: ~path is empty; nothing to request.", "red");
return;
}

int timeoutMs = 20000;
string timeoutText = VA.GetText("~timeoutMs");
if (!string.IsNullOrEmpty(timeoutText)) int.TryParse(timeoutText, out timeoutMs);

answer = Get(baseUrl.TrimEnd('/') + path, VA.GetText("~scmcpToken"), timeoutMs);
}
catch (WebException ex)
{
// Distinguish "daemon isn't running" from "daemon said no", because
// the fix is completely different and you can't read a log in flight.
if (ex.Status == WebExceptionStatus.ConnectFailure)
{
answer = "The Star Citizen daemon is not running.";
}
else if (ex.Status == WebExceptionStatus.Timeout)
{
answer = "That lookup timed out.";
}
else
{
answer = ReadErrorBody(ex);
}
VA.WriteToLog("SCMCP: " + ex.Message, "red");
}
catch (Exception ex)
{
answer = "That lookup failed.";
VA.WriteToLog("SCMCP: " + ex.Message, "red");
}

VA.SetText("~answer", answer);
}

private string Get(string url, string token, int timeoutMs)
{
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
request.Method = "GET";
request.Timeout = timeoutMs;
request.ReadWriteTimeout = timeoutMs;
// The daemon rejects anything that looks browser-originated, so send no
// Origin header. Loopback should never go through a configured proxy.
request.Proxy = null;
request.UserAgent = "SCMCP-VoiceAttack";
if (!string.IsNullOrEmpty(token)) request.Headers.Add("X-SCMCP-Token", token);

using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
using (StreamReader reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8))
{
return reader.ReadToEnd().Trim();
}
}

private string ReadErrorBody(WebException ex)
{
// /say and /ask return speakable text even on 4xx, so prefer the body.
try
{
if (ex.Response != null)
{
using (StreamReader reader =
new StreamReader(ex.Response.GetResponseStream(), Encoding.UTF8))
{
string body = reader.ReadToEnd().Trim();
if (!string.IsNullOrEmpty(body) && !body.StartsWith("{")) return body;
}
}
}
catch { /* fall through to the generic message */ }

return "That lookup failed.";
}
}
Loading
Loading