melchizedek-agents 1.2.0 → 1.3.0

package/dist/lib/mcp/server.d.ts

@@ -0,0 +1,195 @@
+/**
+ * lib/mcp/server.ts — syndicates served as MCP tools (ADR 0125).
+ *
+ * `createMcpServer(options)` makes each loaded syndicate one MCP tool, so an
+ * MCP client (Claude Code, Codex, a custom connector) asks a syndicate the way
+ * it calls any other tool: `{ message, session_id? }` in, the turn's answer
+ * out, with the session id it can pass back to continue the conversation.
+ * One more tool, `melch_resume`, answers a turn that paused: an approval
+ * (`adk_request_confirmation`), a workflow question (`ask_user`), or an OAuth
+ * consent.
+ *
+ * WHY it drives the A2A executor: every turn semantic the A2A server applies
+ * (budgets, the concurrency caps, one turn at a time per conversation, the
+ * approval answer read from the stored events, the deadline, cancellation,
+ * guards and the ledger inside `runSyndicateTurn`, the task record and audit
+ * event, memory ingestion after the reply) lives in `SyndicateExecutor`
+ * (lib/a2a/executor.ts). This module hands it one task per tool call through
+ * a collecting event bus and reads the final status back, so the MCP surface
+ * cannot drift from the A2A one. Nothing here calls the turn runner itself.
+ *
+ * Transports: `serveMcpStdio` (one local client over stdin/stdout) and
+ * `mcpHttpApp` (Streamable HTTP, stateful sessions, behind the bearer rule
+ * the A2A server applies). `mcpBindProblem` is the refusal the bin applies
+ * before listening: a bind beyond loopback without a secret never starts.
+ *
+ * Logging: the executor's lines (task ids by prefix, tool names, counts) and
+ * this module's own (tool names, session ids by prefix). A user's message,
+ * an answer, a secret or a model key is never logged here.
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { Express } from 'express';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { CompileOptions } from '../compile.ts';
+import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
+import type { SessionService } from '../runtime/sessions.ts';
+import type { MemoryService } from '../runtime/memoryService.ts';
+import type { TurnLock } from '../a2a/turnLock.ts';
+import type { Policy } from '../a2a/policy.ts';
+import type { TaskRecord } from '../observability/metrics.ts';
+import type { AuditSink } from '../observability/audit.ts';
+import type { ToolCredentials } from '../tools/oauthConsent.ts';
+/** The tool that answers a paused turn. Never a syndicate's tool name. */
+export declare const RESUME_TOOL = "melch_resume";
+/** A session id a caller hands back: what this server issues, and A2A context ids. Linear, no nesting. */
+export declare const SESSION_ID_PATTERN: RegExp;
+/** One syndicate this server exposes. */
+export interface McpSyndicate {
+    /** The tool name: the file id (`research_desk` for research_desk.yaml), [A-Za-z0-9_-]{1,64}. */
+    id: string;
+    config: SyndicateYamlConfig;
+}
+/** Who is calling: what the A2A identity middleware would have resolved. */
+export interface McpCaller {
+    /** The scope the caller's sessions and memory are stored under. */
+    scopeKey: string;
+    /** The caller's name for logs, budgets and the per-caller cap ('local', 'shared-secret', …). */
+    caller: string;
+    /** The request's source address, for the audit trail only. */
+    sourceIp?: string;
+}
+/** The stdio caller: this machine's own user. */
+export declare const LOCAL_CALLER: McpCaller;
+export interface McpServerOptions {
+    /** THE DELIBERATE ACT OF EXPOSURE: only these syndicates are tools. */
+    syndicates: McpSyndicate[];
+    /** The MCP server name in the handshake. Default `melchizedek`. */
+    name?: string;
+    /** The version in the handshake. */
+    version?: string;
+    /** The conversation store. Default: in process (lost on exit). */
+    sessionService?: SessionService;
+    /** Long-term memory, for syndicates whose memory_system is long-term. */
+    memoryService?: MemoryService;
+    /** Model resolution; default the registry on the server's own environment. */
+    resolveModel?: CompileOptions['resolveModel'];
+    /** Wall-clock budget per turn, ms. 0 or undefined = none. */
+    taskTimeoutMs?: number;
+    /** Concurrent turns across every syndicate. 0 = unlimited. */
+    maxConcurrentTasks?: number;
+    /** Concurrent turns for one scope. Default 4 (the A2A default); 0 = unlimited. */
+    maxConcurrentPerScope?: number;
+    /** Concurrent turns for one caller. Default 0 (unlimited). */
+    maxConcurrentPerCaller?: number;
+    /** Budgets: admit each turn, record what it spent (lib/a2a/policy.ts). */
+    policy?: Policy;
+    /** One turn at a time per conversation. Default: a lock in this process. */
+    turnLock?: TurnLock;
+    turnLockWaitMs?: number;
+    /** The sealed per-user tool credentials and the consent step (ADR 0072, ADR 0085). */
+    toolCredentials?: ToolCredentials;
+    onTaskEnd?: (record: TaskRecord) => void;
+    audit?: AuditSink;
+    log?: (message: string) => void;
+    warn?: (message: string) => void;
+}
+/** What one paused turn waits for, as the executor published it. */
+export type McpPause = {
+    kind: 'approval';
+    id: string;
+    agent: string;
+    tool: string;
+    args: Record<string, unknown>;
+    path?: string[];
+} | {
+    kind: 'input';
+    id: string;
+    node: string;
+    message: string;
+    options?: unknown[];
+} | {
+    kind: 'consent';
+    id: string;
+    agent: string;
+    provider: string;
+    authorizationUrl: string;
+    scopes?: unknown;
+};
+/** The outcome of one tool call, before it becomes an MCP result. */
+export interface McpTurnOutcome {
+    status: 'completed' | 'input-required' | 'failed' | 'canceled' | 'rejected';
+    sessionId: string;
+    text: string;
+    pause?: McpPause;
+}
+export interface MelchMcpServer {
+    /** The tools/list entries: one per syndicate, then melch_resume. */
+    tools(): Tool[];
+    /** A low-level MCP Server for one connection, bound to its caller. */
+    connect(caller: McpCaller): Server;
+    /** Answers one tools/call; the transports go through `connect`, tests may call it directly. */
+    call(caller: McpCaller, name: string, args: unknown, extra?: {
+        signal?: AbortSignal;
+        onProgress?: (message: string) => void;
+    }): Promise<CallToolResult>;
+    /** Stop admitting turns; resolve when running ones finish or graceMs passes. Returns how many were canceled. */
+    shutdown(graceMs: number): Promise<number>;
+    /** Turns running now. */
+    readonly inFlight: number;
+}
+/** A syndicate's tool name from its file id: anything outside [A-Za-z0-9_-] becomes `_`. */
+export declare function toolNameFor(fileId: string): string;
+export declare function createMcpServer(options: McpServerOptions): MelchMcpServer;
+/**
+ * Serve one local client over stdio. stdout carries the protocol and nothing
+ * else: the bin sends every console line to stderr before anything loads.
+ */
+export declare function serveMcpStdio(mcp: MelchMcpServer, opts?: {
+    caller?: McpCaller;
+    stdin?: Readable;
+    stdout?: Writable;
+}): Promise<Server>;
+/**
+ * Why a Streamable HTTP bind must not start, or undefined. The A2A server's
+ * rule (ADR 0039), without its opt-out: beyond loopback a secret is required.
+ */
+export declare function mcpBindProblem(opts: {
+    host: string;
+    secret?: string;
+    minSecretLength?: number;
+}): string | undefined;
+export interface McpHttpOptions {
+    /** The bind address; decides the Host-header check. Default 127.0.0.1. */
+    host?: string;
+    /** The bound port, for the loopback Host-header check. */
+    port?: number;
+    /** The bearer every request must present. Required beyond loopback (mcpBindProblem). */
+    secret?: string;
+    /** Host names a non-loopback bind answers to (the Host header), e.g. ['mcp.example.com']. */
+    allowedHosts?: string[];
+    /** Requests per minute per client IP (240, as the contract servers). */
+    rateLimitPerMinute?: number;
+    /** Failed authentications per 15 minutes per IP before the IP is blocked (30, as A2A). */
+    authFailureMax?: number;
+    /** Express trust proxy (false). */
+    trustProxy?: number | boolean | string;
+    /** JSON body limit ("1mb"). */
+    bodyLimit?: string;
+    /** Open MCP sessions at once (256); a new one past it is refused. */
+    maxSessions?: number;
+    /** A session idle this long is closed (30 minutes). */
+    sessionIdleMs?: number;
+    /** Mounted before the bearer check (the OAuth consent callback, which a browser reaches). */
+    beforeAuth?: (app: Express) => void;
+    warn?: (message: string) => void;
+}
+/**
+ * Streamable HTTP at POST/GET/DELETE /mcp, stateful (Mcp-Session-Id), so a
+ * cancellation reaches the request it names. Order: the Host check (DNS
+ * rebinding on loopback), the request rate limit, the failed-auth limiter,
+ * the constant-time bearer check, the body parser, then the transport.
+ */
+export declare function mcpHttpApp(mcp: MelchMcpServer, opts?: McpHttpOptions): Express & {
+    closeSessions: () => Promise<void>;
+};