@zigrivers/surface-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ken Allred
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,15 @@
+# Surface MCP
+
+MCP server adapter for Surface audits.
+
+## Install
+
+```bash
+npm install @zigrivers/surface-mcp
+```
+
+See the repository README for usage and release guidance: https://github.com/zigrivers/surface#readme
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+import { AlternativesReportData, Finding, TrackedFinding, Evidence, SurfaceComposition, Result, ValidationCheck, SurfaceCompositionOptions, SurfaceError } from '@zigrivers/surface-core';
+import { Backlog, Capture, IssueExport, Target, GateResult } from '@zigrivers/surface-core/interfaces';
+
+declare const SURFACE_MCP_SERVER_NAME = "surface";
+declare const SURFACE_MCP_SERVER_VERSION = "1.0.0";
+declare const SURFACE_MCP_TOOL_SCHEMA_VERSION = "1.0.0";
+declare const TOOL_ORDER: readonly ["surface_capture", "surface_audit", "surface_explain", "surface_backlog", "surface_gate", "surface_validate", "surface_baseline", "surface_verdict", "surface_diff", "surface_alternatives", "surface_trace", "surface_run", "surface_next", "surface_status"];
+type SurfaceMcpToolName = (typeof TOOL_ORDER)[number];
+type JsonSchema = Record<string, unknown>;
+type SurfaceMcpToolDefinition = {
+    readonly name: SurfaceMcpToolName;
+    readonly title: string;
+    readonly description: string;
+    readonly schemaVersion: string;
+    readonly inputSchema: JsonSchema;
+};
+type SurfaceMcpToolRegistry = {
+    readonly serverInfo: {
+        readonly name: typeof SURFACE_MCP_SERVER_NAME;
+        readonly version: typeof SURFACE_MCP_SERVER_VERSION;
+    };
+    listTools(): readonly SurfaceMcpToolDefinition[];
+    getTool(name: SurfaceMcpToolName): SurfaceMcpToolDefinition | undefined;
+};
+type SurfaceMcpServer = {
+    readonly composition: SurfaceComposition;
+    readonly registry: SurfaceMcpToolRegistry;
+    callTool<TName extends SurfaceMcpToolName>(name: TName, input: unknown): Promise<Result<SurfaceMcpToolOutputMap[TName]>>;
+    listTools(): readonly SurfaceMcpToolDefinition[];
+};
+type SurfaceMcpServerOptions = SurfaceCompositionOptions & {
+    readonly composition?: SurfaceComposition;
+};
+type McpToolSchemaCompatibilityInput = {
+    readonly current: Pick<SurfaceMcpToolDefinition, "inputSchema" | "name" | "schemaVersion">;
+    readonly next: Pick<SurfaceMcpToolDefinition, "inputSchema" | "name" | "schemaVersion">;
+};
+type SurfaceMcpAuditOutput = {
+    readonly runId: string;
+    readonly backlog: Backlog;
+    readonly capture: Capture;
+    readonly findings: readonly Finding[];
+    readonly skippedLenses: readonly {
+        readonly lensId: string;
+        readonly message: string;
+        readonly reason: string;
+    }[];
+};
+type SurfaceMcpExplainOutput = {
+    readonly finding: Finding;
+    readonly rationale: string;
+    readonly evidence: readonly Evidence[];
+};
+type SurfaceMcpStatusOutput = {
+    readonly currentStage: string;
+    readonly progress: {
+        readonly completedRuns: number;
+        readonly failedRuns: number;
+        readonly findings: number;
+    };
+    readonly runHistory: readonly {
+        readonly runId: string;
+        readonly status: "completed" | "failed";
+        readonly target?: Target;
+        readonly findings: number;
+    }[];
+};
+type SurfaceMcpValidationOutput = {
+    readonly checks: readonly {
+        readonly id: string;
+        readonly findingId?: string;
+        readonly passed: boolean;
+        readonly validation: ValidationCheck;
+    }[];
+};
+type SurfaceMcpBaselineOutput = {
+    readonly baselineId: string;
+    readonly count: number;
+    readonly reason?: string;
+};
+type SurfaceMcpVerdictOutput = {
+    readonly findingId: string;
+    readonly decision: "accept" | "reject" | "correct" | "defer";
+    readonly rationale: string;
+};
+type SurfaceMcpDiffOutput = {
+    readonly resolved: readonly SurfaceMcpDiffEntry[];
+    readonly regressed: readonly SurfaceMcpDiffEntry[];
+    readonly introduced: readonly SurfaceMcpDiffEntry[];
+    readonly stillFailing: readonly SurfaceMcpDiffEntry[];
+    readonly identityBroken: readonly SurfaceMcpDiffEntry[];
+};
+type SurfaceMcpDiffEntry = {
+    readonly findingId?: string;
+    readonly identityKey: string;
+    readonly status: TrackedFinding["status"];
+};
+type SurfaceMcpTraceOutput = {
+    readonly trackedFinding: TrackedFinding;
+};
+type SurfaceMcpAlternativesOutput = {
+    readonly alternatives: AlternativesReportData;
+};
+type SurfaceMcpRunOutput = {
+    readonly runId: string;
+    readonly stage: string;
+    readonly status: "completed";
+};
+type SurfaceMcpNextOutput = {
+    readonly eligible: readonly string[];
+};
+type SurfaceMcpToolOutputMap = {
+    readonly surface_capture: Capture;
+    readonly surface_audit: SurfaceMcpAuditOutput;
+    readonly surface_explain: SurfaceMcpExplainOutput;
+    readonly surface_backlog: Backlog | IssueExport;
+    readonly surface_status: SurfaceMcpStatusOutput;
+    readonly surface_gate: GateResult;
+    readonly surface_validate: SurfaceMcpValidationOutput;
+    readonly surface_baseline: SurfaceMcpBaselineOutput;
+    readonly surface_verdict: SurfaceMcpVerdictOutput;
+    readonly surface_diff: SurfaceMcpDiffOutput;
+    readonly surface_alternatives: SurfaceMcpAlternativesOutput;
+    readonly surface_trace: SurfaceMcpTraceOutput;
+    readonly surface_run: SurfaceMcpRunOutput;
+    readonly surface_next: SurfaceMcpNextOutput;
+};
+type SurfaceMcpToolOutput = SurfaceMcpToolOutputMap[SurfaceMcpToolName];
+declare function createSurfaceMcpToolRegistry(): SurfaceMcpToolRegistry;
+declare function createSurfaceMcpServer(options?: SurfaceMcpServerOptions): SurfaceMcpServer;
+declare function createMcpToolSchemaSnapshot(registry?: SurfaceMcpToolRegistry): readonly Pick<SurfaceMcpToolDefinition, "inputSchema" | "name" | "schemaVersion">[];
+declare function assertMcpToolSchemaCompatibility(input: McpToolSchemaCompatibilityInput): Result<true, SurfaceError>;
+declare function createSurfaceSdkMcpServer(options?: SurfaceMcpServerOptions): Promise<unknown>;
+declare function runSurfaceMcpStdioServer(options?: SurfaceMcpServerOptions): Promise<void>;
+
+export { type JsonSchema, type McpToolSchemaCompatibilityInput, SURFACE_MCP_SERVER_NAME, SURFACE_MCP_SERVER_VERSION, SURFACE_MCP_TOOL_SCHEMA_VERSION, type SurfaceMcpAlternativesOutput, type SurfaceMcpAuditOutput, type SurfaceMcpBaselineOutput, type SurfaceMcpDiffEntry, type SurfaceMcpDiffOutput, type SurfaceMcpExplainOutput, type SurfaceMcpNextOutput, type SurfaceMcpRunOutput, type SurfaceMcpServer, type SurfaceMcpServerOptions, type SurfaceMcpStatusOutput, type SurfaceMcpToolDefinition, type SurfaceMcpToolName, type SurfaceMcpToolOutput, type SurfaceMcpToolOutputMap, type SurfaceMcpToolRegistry, type SurfaceMcpTraceOutput, type SurfaceMcpValidationOutput, type SurfaceMcpVerdictOutput, assertMcpToolSchemaCompatibility, createMcpToolSchemaSnapshot, createSurfaceMcpServer, createSurfaceMcpToolRegistry, createSurfaceSdkMcpServer, runSurfaceMcpStdioServer };