@ultimat3/mcp 1.0.0

package/src/transport-stdio.ts

@@ -0,0 +1,76 @@
+// stdio transport for `x mcp serve` — newline-delimited JSON-RPC on stdin/stdout.
+//
+// A local agent (Claude Code, an editor) launches the process and speaks over the pipe, so
+// there is no token to resolve: the caller already has the developer's shell. The caller is
+// therefore constructed once from the local developer identity the CLI supplies, and its
+// scopes are whatever that developer is entitled to — no network boundary to defend.
+//
+// stdout is the WIRE. Anything logged there corrupts the protocol, so diagnostics go to
+// stderr and this file never calls `console.log`.
+
+import type { McpCaller } from './registry';
+import type { McpServer } from './server';
+import { errorResponse, PARSE_ERROR } from './wire';
+
+export interface StdioTransportInput {
+  readonly server: McpServer;
+  /** The local developer, already resolved by the CLI. Usually `kind: 'agent'`. */
+  readonly caller: McpCaller;
+  /** Defaults to `Bun.stdin.stream()`; overridable so a test can feed a fixed script. */
+  readonly input?: ReadableStream<Uint8Array>;
+  /** Defaults to writing `Bun.stdout`. */
+  write?(chunk: string): Promise<void> | void;
+}
+
+/**
+ * Serve until stdin closes. Resolves when the peer disconnects, which is the CLI's signal
+ * to exit 0 — a closed pipe is a normal shutdown, not an error.
+ */
+export async function serveStdio(config: StdioTransportInput): Promise<void> {
+  const stream = config.input ?? Bun.stdin.stream();
+  const write = config.write ?? defaultWrite;
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  for await (const chunk of stream) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let newline = buffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      await handleLine(config.server, config.caller, line, write);
+      newline = buffer.indexOf('\n');
+    }
+  }
+  // A trailing message with no newline is still a message.
+  if (buffer.trim().length > 0) {
+    await handleLine(config.server, config.caller, buffer, write);
+  }
+}
+
+async function handleLine(
+  server: McpServer,
+  caller: McpCaller,
+  line: string,
+  write: (chunk: string) => Promise<void> | void,
+): Promise<void> {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return;
+
+  let body: unknown;
+  try {
+    body = JSON.parse(trimmed);
+  } catch {
+    await write(`${JSON.stringify(errorResponse(null, PARSE_ERROR, 'invalid JSON line'))}\n`);
+    return;
+  }
+
+  const response = await server.handle(body, caller);
+  // `null` means notification: emit nothing at all, or the peer sees a phantom reply.
+  if (response === null) return;
+  await write(`${JSON.stringify(response)}\n`);
+}
+
+function defaultWrite(chunk: string): void {
+  Bun.stdout.write(chunk);
+}

package/src/validate-args.ts

@@ -0,0 +1,161 @@
+// Argument validation against a tool's declared JSON Schema — the ONE arg contract.
+//
+// Why not a second validator alongside the schema: `tools/list` hands the agent a JSON
+// Schema, so that document must be the thing enforced. If a tool could also carry a
+// private validator the agent would be judged against a contract it never saw. Actions
+// still re-parse authoritatively inside their own handler; this pass exists so a wrong
+// call comes back as a structured issue list instead of a round trip.
+
+import type { JsonSchema } from './wire';
+
+export interface ArgIssue {
+  /** Dotted path from the arguments root, `''` for the root itself. */
+  readonly path: string;
+  readonly message: string;
+}
+
+export type ArgValidation =
+  | { readonly ok: true; readonly value: Record<string, unknown> }
+  | { readonly ok: false; readonly issues: readonly ArgIssue[] };
+
+/**
+ * Validate `raw` against `schema`, applying declared `default`s. Returns the coerced
+ * record so a handler reads defaults without repeating them.
+ */
+export function validateArgs(schema: JsonSchema, raw: unknown): ArgValidation {
+  const issues: ArgIssue[] = [];
+  const value = walk(schema, raw ?? {}, '', issues);
+  if (issues.length > 0) return { ok: false, issues };
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return { ok: false, issues: [{ path: '', message: 'arguments must be an object' }] };
+  }
+  return { ok: true, value: value as Record<string, unknown> };
+}
+
+function walk(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
+  if (schema.anyOf !== undefined) return anyOf(schema.anyOf, input, path, issues);
+  if (schema.const !== undefined && input !== schema.const) {
+    issues.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
+    return input;
+  }
+  if (schema.enum !== undefined && !schema.enum.includes(input as string)) {
+    issues.push({ path, message: `must be one of ${schema.enum.map(String).join(' | ')}` });
+    return input;
+  }
+  switch (schema.type) {
+    case 'object':
+      return object(schema, input, path, issues);
+    case 'array':
+      return array(schema, input, path, issues);
+    case 'string':
+      return string(schema, input, path, issues);
+    case 'number':
+    case 'integer':
+      return number(schema, input, path, issues);
+    case 'boolean':
+      if (typeof input !== 'boolean') issues.push({ path, message: 'must be a boolean' });
+      return input;
+    case 'null':
+      if (input !== null) issues.push({ path, message: 'must be null' });
+      return input;
+    default:
+      return input;
+  }
+}
+
+function object(
+  schema: JsonSchema,
+  input: unknown,
+  path: string,
+  issues: ArgIssue[],
+): Record<string, unknown> | unknown {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    issues.push({ path, message: 'must be an object' });
+    return input;
+  }
+  const source = input as Record<string, unknown>;
+  const properties = schema.properties ?? {};
+  const out: Record<string, unknown> = {};
+
+  for (const key of Object.keys(source)) {
+    if (properties[key] === undefined) {
+      if (schema.additionalProperties === false) {
+        issues.push({ path: join(path, key), message: 'unknown property' });
+        continue;
+      }
+      out[key] = source[key];
+    }
+  }
+  for (const [key, child] of Object.entries(properties)) {
+    const at = join(path, key);
+    const present = Object.hasOwn(source, key) && source[key] !== undefined;
+    if (!present) {
+      if (child.default !== undefined) out[key] = child.default;
+      else if (schema.required?.includes(key) === true) {
+        issues.push({ path: at, message: 'is required' });
+      }
+      continue;
+    }
+    out[key] = walk(child, source[key], at, issues);
+  }
+  return out;
+}
+
+function array(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
+  if (!Array.isArray(input)) {
+    issues.push({ path, message: 'must be an array' });
+    return input;
+  }
+  const items = schema.items;
+  if (items === undefined) return input;
+  return input.map((item, index) => walk(items, item, `${path}[${index}]`, issues));
+}
+
+function string(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
+  if (typeof input !== 'string') {
+    issues.push({ path, message: 'must be a string' });
+    return input;
+  }
+  if (schema.minLength !== undefined && input.length < schema.minLength) {
+    issues.push({ path, message: `must be at least ${schema.minLength} characters` });
+  }
+  if (schema.maxLength !== undefined && input.length > schema.maxLength) {
+    issues.push({ path, message: `must be at most ${schema.maxLength} characters` });
+  }
+  return input;
+}
+
+function number(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
+  if (typeof input !== 'number' || Number.isNaN(input)) {
+    issues.push({ path, message: 'must be a number' });
+    return input;
+  }
+  if (schema.type === 'integer' && !Number.isInteger(input)) {
+    issues.push({ path, message: 'must be an integer' });
+  }
+  if (schema.minimum !== undefined && input < schema.minimum) {
+    issues.push({ path, message: `must be >= ${schema.minimum}` });
+  }
+  if (schema.maximum !== undefined && input > schema.maximum) {
+    issues.push({ path, message: `must be <= ${schema.maximum}` });
+  }
+  return input;
+}
+
+/** First branch that validates wins; if none does, report the union, not each branch. */
+function anyOf(
+  branches: readonly JsonSchema[],
+  input: unknown,
+  path: string,
+  issues: ArgIssue[],
+): unknown {
+  for (const branch of branches) {
+    const local: ArgIssue[] = [];
+    const value = walk(branch, input, path, local);
+    if (local.length === 0) return value;
+  }
+  issues.push({ path, message: `does not match any of the ${branches.length} allowed shapes` });
+  return input;
+}
+
+const join = (path: string, key: string): string => (path === '' ? key : `${path}.${key}`);

package/src/wire.ts

@@ -0,0 +1,115 @@
+// JSON-RPC 2.0 vocabulary for the Ultimate MCP server: envelope types, the standard
+// error codes, the advertised protocol version, and the two response constructors.
+// Pure data + pure functions so every transport (http, stdio, a test) agrees on the wire
+// without importing the server.
+//
+// Reference: https://modelcontextprotocol.io/specification (2025-06-18).
+
+import { FRAMEWORK_VERSION } from '@ultimat3/core';
+
+/** MCP protocol version advertised on `initialize`. */
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+
+/** Identity advertised on `initialize` unless the host overrides it. */
+export const DEFAULT_SERVER_INFO = { name: 'ultimate', version: FRAMEWORK_VERSION } as const;
+
+export interface ServerInfo {
+  readonly name: string;
+  readonly version: string;
+}
+
+export type JsonRpcId = string | number | null;
+
+/** A request OR a notification — a notification is exactly "no `id`". */
+export interface JsonRpcRequest {
+  readonly jsonrpc: '2.0';
+  readonly method: string;
+  readonly params?: unknown;
+  readonly id?: JsonRpcId;
+}
+
+export interface JsonRpcError {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+export interface JsonRpcResponse {
+  readonly jsonrpc: '2.0';
+  readonly id: JsonRpcId;
+  readonly result?: unknown;
+  readonly error?: JsonRpcError;
+}
+
+// ── standard error codes (jsonrpc.org/spec) ──────────────────────────────────
+//
+// The MCP spec adds no codes of its own, so the two security answers map onto these:
+//   INVALID_REQUEST  (-32600) → Forbidden: the tool exists and you may see it, but your
+//                               token lacks its scope.
+//   METHOD_NOT_FOUND (-32601) → ToolNotFound: the tool is absent OR hidden from your role.
+// Never the other way round — see `registry.ts`.
+
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+
+/**
+ * The JSON Schema subset the framework emits and `validate-args.ts` enforces. Narrow on
+ * purpose: a tool schema an agent cannot fully understand is a tool it will call wrong.
+ */
+export interface JsonSchema {
+  readonly type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
+  readonly title?: string;
+  readonly description?: string;
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean;
+  readonly items?: JsonSchema;
+  readonly enum?: readonly (string | number | boolean | null)[];
+  readonly const?: string | number | boolean | null;
+  readonly default?: unknown;
+  readonly format?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly anyOf?: readonly JsonSchema[];
+}
+
+/** An empty-object schema — the honest shape for a no-argument tool. */
+export const NO_ARGS: JsonSchema = { type: 'object', properties: {}, additionalProperties: false };
+
+export function resultResponse(id: JsonRpcId, result: unknown): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, result };
+}
+
+export function errorResponse(
+  id: JsonRpcId,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  // exactOptionalPropertyTypes: attach `data` only when supplied.
+  const error: JsonRpcError = { code, message, ...(data !== undefined ? { data } : {}) };
+  return { jsonrpc: '2.0', id, error };
+}
+
+/** Minimal envelope check. A body failing this is `-32600`, never a crash. */
+export function isJsonRpcRequest(value: unknown): value is JsonRpcRequest {
+  if (typeof value !== 'object' || value === null) return false;
+  const o = value as Record<string, unknown>;
+  return o['jsonrpc'] === '2.0' && typeof o['method'] === 'string';
+}
+
+/** A notification carries no `id`; the server answers nothing and the transport 202s. */
+export function isNotification(req: JsonRpcRequest): boolean {
+  return req.id === undefined;
+}
+
+/** `params` as a record, or `null` when the caller sent a non-object. */
+export function paramsOf(req: JsonRpcRequest): Record<string, unknown> | null {
+  if (typeof req.params !== 'object' || req.params === null) return null;
+  return req.params as Record<string, unknown>;
+}