Dual-era server: requests that carry io.modelcontextprotocol/protocolVersion are served statelessly (server/discover
with supportedVersions, capabilities, instructions, ttlMs / cacheScope; resultType complete and serverInfo in every
result's _meta; cacheable tools/list; -32022 UnsupportedProtocolVersion with data { supported, requested }; -32602 when
clientCapabilities is missing). initialize / ping / unannotated requests keep the 2025-11-25 (and older) behaviour.
Tests for both handshakes, including one stdio process serving a modern probe and a legacy client.
155 lines
9.6 KiB
TypeScript
155 lines
9.6 KiB
TypeScript
// `storebound mcp`: a stdio MCP server (tools only) that wraps the CLI, so any agent tool with MCP support (Claude Code,
|
|
// Codex, Gemini CLI, Cursor, VS Code / Copilot, Windsurf, OpenCode, ...) can call it.
|
|
//
|
|
// Dual-era, as the 2026-07-28 spec allows ("Versioning: Backward Compatibility with Initialization-Based Versions"):
|
|
// - modern 2026-07-28: no handshake. Every request carries `_meta["io.modelcontextprotocol/protocolVersion"]` and
|
|
// `_meta["io.modelcontextprotocol/clientCapabilities"]`; `server/discover` answers the supported versions,
|
|
// capabilities and instructions; results carry `resultType: "complete"` and
|
|
// `_meta["io.modelcontextprotocol/serverInfo"]`; tools/list is cacheable (ttlMs, cacheScope). An unknown version
|
|
// gets -32022 (UnsupportedProtocolVersionError, data { supported, requested }), a missing required _meta key -32602.
|
|
// https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
|
|
// https://modelcontextprotocol.io/specification/2026-07-28/server/discover
|
|
// https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio
|
|
// - legacy 2025-11-25 (and 2025-06-18 / 2025-03-26 / 2024-11-05): initialize, notifications/initialized, ping and
|
|
// the results without resultType, as before. Requests without the per-request version are served this way.
|
|
// The server keeps no session state, so both eras can share one process.
|
|
//
|
|
// Why no SDK: newline-delimited JSON-RPC with a handful of methods is a few hundred lines and keeps storebound at
|
|
// zero runtime dependencies (the official SDK pulls in zod, express, ...).
|
|
//
|
|
// Every tool runs the CLI as a child process in the project directory (STOREBOUND_PROJECT or the server's cwd) and
|
|
// returns its output. stdout of this process carries protocol messages only; logs go to stderr.
|
|
// Tool list and safety rules: mcp-tools.ts (write tools default to dry_run, nothing public or irreversible exposed).
|
|
import { join } from 'node:path';
|
|
import pkg from '../package.json' with { type: 'json' };
|
|
import { listTools, TOOLS, toArgv, validateInput } from './mcp-tools';
|
|
|
|
/** Current (modern, stateless) revision. */
|
|
export const PROTOCOL = '2026-07-28';
|
|
export const MODERN = [PROTOCOL];
|
|
/** Handshake-based revisions, answered through `initialize`. */
|
|
export const LEGACY_PROTOCOL = '2025-11-25';
|
|
export const LEGACY = [LEGACY_PROTOCOL, '2025-06-18', '2025-03-26', '2024-11-05'];
|
|
export const SUPPORTED = [...MODERN, ...LEGACY];
|
|
|
|
export const META = {
|
|
protocolVersion: 'io.modelcontextprotocol/protocolVersion',
|
|
clientCapabilities: 'io.modelcontextprotocol/clientCapabilities',
|
|
clientInfo: 'io.modelcontextprotocol/clientInfo',
|
|
serverInfo: 'io.modelcontextprotocol/serverInfo',
|
|
} as const;
|
|
export const UNSUPPORTED_PROTOCOL_VERSION = -32022;
|
|
/** The tool list never changes while the server runs; modern clients may cache it this long. */
|
|
export const TOOLS_TTL_MS = 300_000;
|
|
|
|
export const INSTRUCTIONS = [
|
|
'storebound ships mobile games to Google Play and the App Store.',
|
|
'Write tools default to dry_run: show the dry run to the owner and only call again with dry_run false after they agree.',
|
|
'Nothing here submits for review, releases, cancels, deletes or sends anything public (review replies, tester invitations, price changes, experiment starts): tell the owner which terminal command or console click does that.',
|
|
'Credentials come only from env or .storebound/ in the project; never ask for keys in chat or write them into files.',
|
|
'Run `check` (offline) and `validate` (read-only) before writes. Long uploads (images, screenshots) are better run in a terminal with a log.',
|
|
].join(' ');
|
|
|
|
type Id = string | number;
|
|
interface Msg { jsonrpc: '2.0'; id?: Id; method?: string; params?: Record<string, unknown> }
|
|
|
|
const MAX_OUTPUT = 60_000;
|
|
const CLI = join(import.meta.dir, 'index.ts');
|
|
const serverInfo = () => ({ name: 'storebound', title: 'storebound', version: pkg.version });
|
|
|
|
/** Era of one request: modern when its _meta names a modern (or unknown) protocol version, else legacy. */
|
|
export function eraOf(m: Msg): { era: 'modern' | 'legacy'; version: string | null } {
|
|
const meta = (m.params?._meta ?? {}) as Record<string, unknown>;
|
|
const v = meta[META.protocolVersion];
|
|
if (typeof v !== 'string') return { era: 'legacy', version: null };
|
|
return { era: LEGACY.includes(v) ? 'legacy' : 'modern', version: v };
|
|
}
|
|
|
|
/** Handles one message; returns the response object (or null for notifications). Exported for tests. */
|
|
export async function handle(m: Msg, run: (argv: string[], id: Id) => Promise<{ code: number; out: string }> = runCli): Promise<Record<string, unknown> | null> {
|
|
const err = (code: number, message: string, data?: unknown) => ({ jsonrpc: '2.0', id: m.id ?? null, error: { code, message, ...(data === undefined ? {} : { data }) } });
|
|
if (m.id === undefined) {
|
|
if (m.method === 'notifications/cancelled') cancel(m.params?.requestId as Id);
|
|
return null; // notifications/initialized and any other notification
|
|
}
|
|
if (m.method === 'initialize') {
|
|
const asked = String(m.params?.protocolVersion ?? '');
|
|
return { jsonrpc: '2.0', id: m.id, result: {
|
|
protocolVersion: LEGACY.includes(asked) ? asked : LEGACY_PROTOCOL,
|
|
capabilities: { tools: { listChanged: false } },
|
|
serverInfo: { ...serverInfo(), description: pkg.description },
|
|
instructions: INSTRUCTIONS,
|
|
} };
|
|
}
|
|
|
|
const { era, version } = eraOf(m);
|
|
if (era === 'modern') {
|
|
if (!MODERN.includes(version!)) return err(UNSUPPORTED_PROTOCOL_VERSION, 'Unsupported protocol version', { supported: SUPPORTED, requested: version });
|
|
const caps = ((m.params?._meta ?? {}) as Record<string, unknown>)[META.clientCapabilities];
|
|
if (typeof caps !== 'object' || caps === null) return err(-32602, `Invalid params: _meta["${META.clientCapabilities}"] is required`);
|
|
} else if (m.method === 'server/discover') {
|
|
return err(-32602, `Invalid params: _meta["${META.protocolVersion}"] is required`);
|
|
}
|
|
// Modern results carry resultType and name the server in _meta; legacy results stay as they were.
|
|
const ok = (result: Record<string, unknown>) => ({ jsonrpc: '2.0', id: m.id,
|
|
result: era === 'modern' ? { resultType: 'complete', ...result, _meta: { [META.serverInfo]: serverInfo() } } : result });
|
|
|
|
switch (m.method) {
|
|
case 'server/discover':
|
|
return ok({ supportedVersions: SUPPORTED, capabilities: { tools: {} }, instructions: INSTRUCTIONS, ttlMs: TOOLS_TTL_MS, cacheScope: 'public' });
|
|
case 'ping': return ok({});
|
|
case 'tools/list': return ok({ tools: listTools(), ...(era === 'modern' ? { ttlMs: TOOLS_TTL_MS, cacheScope: 'public' } : {}) });
|
|
case 'tools/call': {
|
|
const name = String(m.params?.name ?? '');
|
|
const tool = TOOLS.find(t => t.name === name);
|
|
if (!tool) return err(-32602, `Unknown tool: ${name}`);
|
|
const input = (m.params?.arguments ?? {}) as Record<string, unknown>;
|
|
const problems = validateInput(tool, input);
|
|
if (problems.length) return ok({ content: [{ type: 'text', text: `Invalid arguments: ${problems.join('; ')}` }], isError: true });
|
|
const { argv, dryRun } = toArgv(tool, input);
|
|
const r = await run(argv, m.id);
|
|
let out = r.out.length > MAX_OUTPUT ? `[... first ${r.out.length - MAX_OUTPUT} characters cut ...]\n` + r.out.slice(-MAX_OUTPUT) : r.out;
|
|
if (dryRun) out += '\n\n(dry run: nothing was changed. Ask the owner before calling again with dry_run: false.)';
|
|
const structured = { exitCode: r.code, dryRun, command: `storebound ${argv.join(' ')}`, output: out };
|
|
return ok({ content: [{ type: 'text', text: `$ storebound ${argv.join(' ')}\n${out}\n[exit ${r.code}]` }], structuredContent: structured, isError: r.code !== 0 });
|
|
}
|
|
default: return err(-32601, `Method not found: ${m.method}`);
|
|
}
|
|
}
|
|
|
|
const running = new Map<Id, ReturnType<typeof Bun.spawn>>();
|
|
function cancel(id: Id | undefined): void { if (id !== undefined) running.get(id)?.kill(); }
|
|
|
|
async function runCli(argv: string[], id: Id): Promise<{ code: number; out: string }> {
|
|
const cwd = process.env.STOREBOUND_PROJECT || process.cwd();
|
|
const p = Bun.spawn([process.execPath, CLI, ...argv], { cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe', env: { ...process.env, NO_COLOR: '1' } });
|
|
running.set(id, p);
|
|
try {
|
|
const [out, errText, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]);
|
|
return { code, out: (out + (errText ? `\n${errText}` : '')).trim() };
|
|
} finally { running.delete(id); }
|
|
}
|
|
|
|
export async function serve(): Promise<void> {
|
|
const send = (o: unknown) => process.stdout.write(JSON.stringify(o) + '\n');
|
|
console.error(`[storebound mcp] ${pkg.version} on stdio (MCP ${PROTOCOL}, legacy ${LEGACY.join(', ')}), project ${process.env.STOREBOUND_PROJECT || process.cwd()}`);
|
|
let buf = '';
|
|
const decoder = new TextDecoder();
|
|
const reader = Bun.stdin.stream().getReader();
|
|
for (;;) {
|
|
const { value, done } = await reader.read();
|
|
if (done) break;
|
|
buf += decoder.decode(value, { stream: true });
|
|
let nl: number;
|
|
while ((nl = buf.indexOf('\n')) >= 0) {
|
|
const line = buf.slice(0, nl).trim();
|
|
buf = buf.slice(nl + 1);
|
|
if (!line) continue;
|
|
let msg: Msg;
|
|
try { msg = JSON.parse(line) as Msg; } catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); continue; }
|
|
if (Array.isArray(msg)) { send({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Batches are not supported' } }); continue; }
|
|
// Calls run concurrently; each answers when its child process ends.
|
|
handle(msg).then(r => { if (r) send(r); }, e => send({ jsonrpc: '2.0', id: msg.id ?? null, error: { code: -32603, message: String((e as Error).message) } }));
|
|
}
|
|
}
|
|
}
|