@modelprofile.com/mcp-crossharness 5.0.0

package/ts/classes.mcpserver.ts

@@ -0,0 +1,363 @@
+import * as plugins from './plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import type * as interfaces from './interfaces.js';
+import { ConnectionRegistry } from './classes.connectionregistry.js';
+import { DispatchRegistry } from './classes.dispatchregistry.js';
+
+const harnessNameSchema = plugins.z.enum(['claudecode', 'opencode', 'codex']);
+
+export class CrossHarnessMcpServer {
+  public readonly connections: ConnectionRegistry;
+  public readonly dispatches: DispatchRegistry;
+  private activeServer: InstanceType<typeof plugins.McpServer> | undefined;
+  private stdinEndHandler: (() => void) | undefined;
+  private stdinEndSource: NodeJS.ReadableStream | undefined;
+  private closePromise: Promise<void> | undefined;
+  private resourceShutdownPromise: Promise<void> | undefined;
+  private startCalled = false;
+
+  constructor(connectionsArg = new ConnectionRegistry(), dispatchesArg = new DispatchRegistry()) {
+    this.connections = connectionsArg;
+    this.dispatches = dispatchesArg;
+  }
+
+  public async start(
+    transportArg: plugins.Transport = new plugins.StdioServerTransport(),
+    stdinArg: NodeJS.ReadableStream = process.stdin,
+  ): Promise<void> {
+    if (this.startCalled) throw new Error('Crossharness MCP server instances are one-shot');
+    this.startCalled = true;
+    const server = new plugins.McpServer({
+      name: 'mcp-crossharness',
+      version: commitinfo.version,
+    });
+
+    server.registerTool(
+      'connect_harness',
+      {
+        title: 'Connect to harness server',
+        description:
+          'Establish an explicit connection to an allowlisted harness web server. The exact origin must be listed in CROSSHARNESS_ALLOWED_SERVER_URLS. OpenCode uses http(s), Codex uses ws(s), and Claude Code is rejected because it exposes no URL-addressable session server. Returns a connectionId required by every connection-scoped operation; list_connections remains global.',
+        inputSchema: {
+          harness: harnessNameSchema,
+          serverUrl: plugins.z.string().max(2048).url().describe('Allowlisted harness server origin'),
+          directory: plugins.z
+            .string()
+            .max(4096)
+            .startsWith('/')
+            .describe('Absolute project directory on the harness server'),
+        },
+      },
+      async (args, extra) =>
+        this.wrapToolCall(async () => {
+          const info = await this.connections.connect(
+           args.harness as interfaces.THarnessName,
+           args.serverUrl,
+           args.directory,
+            extra.signal,
+          );
+          return this.describeConnection(info);
+        }),
+    );
+
+    server.registerTool(
+      'disconnect_harness',
+      {
+        title: 'Disconnect harness server',
+        description:
+          'Close and remove an established harness connection. In-flight requests fail; async dispatch records remain inspectable with check_reply.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+        },
+      },
+      async (args, extra) =>
+        this.wrapToolCall(async () =>
+          this.describeConnection(await this.connections.disconnect(args.connectionId)),
+        ),
+    );
+
+    server.registerTool(
+      'list_connections',
+      {
+        title: 'List harness connections',
+        description: 'List explicit harness web-server connections established in this MCP process.',
+        inputSchema: {},
+      },
+      async () =>
+        this.wrapToolCall(async () => {
+          const connections = this.connections.list();
+          return connections.length > 0
+            ? connections.map((connection) => this.describeConnection(connection)).join('\n\n')
+            : 'No harness server connections established.';
+        }),
+    );
+
+    server.registerTool(
+      'connection_status',
+      {
+        title: 'Check harness connection',
+        description: 'Run the protocol health check for one explicit harness server connection.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+        },
+      },
+      async (args) =>
+        this.wrapToolCall(async () => {
+          const status = await this.connections.get(args.connectionId).getStatus();
+          return `${this.describeConnection(status)}\nhealthy: ${status.healthy ? 'yes' : 'no'}\ndetail: ${status.detail}`;
+        }),
+    );
+
+    server.registerTool(
+      'list_chats',
+      {
+        title: 'List harness chats',
+        description:
+          'List chats from the server and directory bound to an explicit connection. No local session stores are read.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+          limit: plugins.z.number().int().min(1).max(100).optional(),
+        },
+      },
+      async (args) =>
+        this.wrapToolCall(async () => {
+          const chats = await this.connections.get(args.connectionId).listChats(args.limit ?? 10);
+          if (chats.length === 0) return 'No chats found for this connection.';
+          return [
+            'harness\tchatId\tupdatedAt\tactivity\ttitle',
+            ...chats.map(
+              (chat) =>
+                `${chat.harness}\t${chat.chatId}\t${chat.updatedAt}\t${chat.isActive ? 'active' : 'idle'}\t${chat.title.replace(/\s+/g, ' ').slice(0, 120)}`,
+            ),
+          ].join('\n');
+        }),
+    );
+
+    server.registerTool(
+      'read_chat',
+      {
+        title: 'Read harness chat',
+        description:
+          'Read a chat through the harness web server bound to an explicit connection.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+          chatId: plugins.z.string().min(1).max(1024),
+          limit: plugins.z.number().int().min(1).max(500).optional(),
+          maxChars: plugins.z.number().int().min(200).max(50000).optional(),
+        },
+      },
+      async (args) =>
+        this.wrapToolCall(async () => {
+          const transcript = await this.connections
+            .get(args.connectionId)
+            .readChat(args.chatId, args.limit ?? 20, args.maxChars ?? 2000);
+          const header = [
+            `harness: ${transcript.harness}`,
+            `chatId: ${transcript.chatId}`,
+            `title: ${transcript.title}`,
+            `directory: ${transcript.directory}`,
+            transcript.totalMessages === undefined
+              ? `messages: showing ${transcript.messages.length}; server total unavailable`
+              : `messages: showing ${transcript.messages.length} of ${transcript.totalMessages}`,
+          ].join('\n');
+          const body = transcript.messages
+            .map(
+              (message) =>
+                `-- [${message.role}]${message.timestamp ? ` ${message.timestamp}` : ''}\n${message.text}`,
+            )
+            .join('\n');
+          return `${header}\n\n${body}`;
+        }),
+    );
+
+    server.registerTool(
+      'send_message',
+      {
+        title: 'Send message through harness server',
+        description:
+          'Send a message only through the harness web server bound to an explicit connection and wait for the reply. There is no CLI, process, local-store, discovery, or retry fallback.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+          chatId: plugins.z.string().min(1).max(1024),
+          message: plugins.z.string().min(1).max(1024 * 1024),
+          timeoutSeconds: plugins.z.number().int().min(1).max(3600).optional(),
+        },
+      },
+      async (args, extra) =>
+        this.wrapToolCall(async () => {
+          const result = await this.connections
+            .get(args.connectionId)
+            .sendMessage(args.chatId, args.message, args.timeoutSeconds ?? 300, extra.signal);
+          return `${result.reply}\n\n[crossharness transport: ${result.via}]`;
+        }),
+    );
+
+    server.registerTool(
+      'send_message_async',
+      {
+        title: 'Send message through harness server asynchronously',
+        description:
+          'Start a server-only send and return a dispatchId immediately. Both this connectionId and the dispatchId are required by check_reply.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+          chatId: plugins.z.string().min(1).max(1024),
+          message: plugins.z.string().min(1).max(1024 * 1024),
+          timeoutSeconds: plugins.z.number().int().min(1).max(3600).optional(),
+        },
+      },
+      async (args) =>
+        this.wrapToolCall(async () => {
+          const connection = this.connections.get(args.connectionId);
+          const record = this.dispatches.track(
+            args.connectionId,
+            connection.harness,
+            args.chatId,
+            () => connection.sendMessage(args.chatId, args.message, args.timeoutSeconds ?? 900),
+          );
+          return [
+            `connectionId: ${record.connectionId}`,
+            `dispatchId: ${record.dispatchId}`,
+            `harness: ${record.harness}`,
+            `chatId: ${record.chatId}`,
+            `startedAt: ${record.startedAt}`,
+          ].join('\n');
+        }),
+    );
+
+    server.registerTool(
+      'check_reply',
+      {
+        title: 'Check async server send',
+        description:
+          'Check an asynchronous send. The connectionId must own the dispatch. Records remain inspectable after disconnect.',
+        inputSchema: {
+          connectionId: plugins.z.string().max(128).describe('Connection id used for send_message_async'),
+          dispatchId: plugins.z.string().max(128).describe('Dispatch id returned by send_message_async'),
+          waitSeconds: plugins.z.number().int().min(0).max(60).optional(),
+        },
+      },
+      async (args, extra) =>
+        this.wrapToolCall(async () => {
+          const record = await this.dispatches.waitFor(
+            args.connectionId,
+            args.dispatchId,
+            (args.waitSeconds ?? 0) * 1000,
+            extra.signal,
+          );
+          if (!record) throw new Error('unknown dispatchId for this connectionId');
+          const header = [
+            `connectionId: ${record.connectionId}`,
+            `dispatchId: ${record.dispatchId}`,
+            `status: ${record.status}`,
+            `harness: ${record.harness}`,
+            `chatId: ${record.chatId}`,
+            `startedAt: ${record.startedAt}`,
+            ...(record.completedAt ? [`completedAt: ${record.completedAt}`] : []),
+          ].join('\n');
+          if (record.status === 'working') return `${header}\n\nStill working.`;
+          if (record.status === 'failed') return `${header}\n\nError: ${record.error}`;
+          return `${header}\n\n${record.reply}\n\n[crossharness transport: ${record.via}]`;
+        }),
+    );
+
+    this.activeServer = server;
+    this.stdinEndHandler = () => this.triggerClose();
+    this.stdinEndSource = stdinArg;
+    this.stdinEndSource.once('end', this.stdinEndHandler);
+    this.stdinEndSource.once('close', this.stdinEndHandler);
+    this.stdinEndSource.once('error', this.stdinEndHandler);
+    server.server.onclose = () => {
+      this.clearTransportReferences();
+      void this.ensureResourceShutdown().catch(() => undefined);
+    };
+    try {
+      await server.connect(transportArg);
+    } catch (error) {
+      this.clearTransportReferences();
+      await transportArg.close().catch(() => {});
+      await this.ensureResourceShutdown();
+      throw error;
+    }
+  }
+
+  public async close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = (async () => {
+      const server = this.activeServer;
+      let closeError: unknown;
+      try {
+        if (server) await server.close();
+      } catch (error) {
+        closeError = error;
+      } finally {
+        this.clearTransportReferences();
+        await this.ensureResourceShutdown();
+      }
+      if (closeError) throw closeError;
+    })().finally(() => {
+      this.closePromise = undefined;
+    });
+    return this.closePromise;
+  }
+
+  private triggerClose(): void {
+    void this.close().catch(() => {});
+  }
+
+  private ensureResourceShutdown(): Promise<void> {
+    if (this.resourceShutdownPromise) return this.resourceShutdownPromise;
+    let shutdownPromise!: Promise<void>;
+    shutdownPromise = this.connections.closeAll().finally(() => {
+      this.dispatches.dispose();
+    }).catch((errorArg) => {
+      if (this.resourceShutdownPromise === shutdownPromise) {
+        this.resourceShutdownPromise = undefined;
+      }
+      throw errorArg;
+    });
+    this.resourceShutdownPromise = shutdownPromise;
+    return shutdownPromise;
+  }
+
+  private clearTransportReferences(): void {
+    if (this.stdinEndHandler) {
+      this.stdinEndSource?.off('end', this.stdinEndHandler);
+      this.stdinEndSource?.off('close', this.stdinEndHandler);
+      this.stdinEndSource?.off('error', this.stdinEndHandler);
+    }
+    this.stdinEndHandler = undefined;
+    this.stdinEndSource = undefined;
+    this.activeServer = undefined;
+  }
+
+  private describeConnection(infoArg: interfaces.IConnectionInfo): string {
+    return [
+      `connectionId: ${infoArg.connectionId}`,
+      `harness: ${infoArg.harness}`,
+      `serverUrl: ${infoArg.serverUrl}`,
+      `directory: ${infoArg.directory}`,
+      `state: ${infoArg.state}`,
+      `connectedAt: ${infoArg.connectedAt}`,
+      ...(infoArg.serverVersion ? [`serverVersion: ${infoArg.serverVersion}`] : []),
+    ].join('\n');
+  }
+
+  private async wrapToolCall(
+    handlerArg: () => Promise<string>,
+  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
+    try {
+      const text = await handlerArg();
+      return { content: [{ type: 'text', text: text.slice(0, 100000) }] };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`.slice(0, 100000),
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+}

package/ts/helpers.ts

@@ -0,0 +1,20 @@
+export const truncateText = (textArg: string, maxCharsArg: number): string => {
+  if (textArg.length <= maxCharsArg) {
+    return textArg;
+  }
+  return `${textArg.slice(0, maxCharsArg)}\n[truncated ${textArg.length - maxCharsArg} chars]`;
+};
+
+export const parseJson = (valueArg: string): unknown => {
+  try {
+    return JSON.parse(valueArg);
+  } catch {
+    return undefined;
+  }
+};
+
+export const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg);
+
+export const errorMessage = (errorArg: unknown): string =>
+  errorArg instanceof Error ? errorArg.message : String(errorArg);

package/ts/index.ts

@@ -0,0 +1,10 @@
+export * from './interfaces.js';
+export * from './classes.connectionregistry.js';
+export * from './classes.dispatchregistry.js';
+export * from './classes.mcpserver.js';
+
+import { CrossHarnessMcpServer } from './classes.mcpserver.js';
+
+export const runCli = async (): Promise<void> => {
+  await new CrossHarnessMcpServer().start();
+};

package/ts/interfaces.ts

@@ -0,0 +1,71 @@
+export type THarnessName = 'claudecode' | 'opencode' | 'codex';
+
+export type TConnectionState = 'connecting' | 'connected' | 'closing' | 'closed';
+
+export interface IConnectionInfo {
+  connectionId: string;
+  harness: THarnessName;
+  serverUrl: string;
+  directory: string;
+  state: TConnectionState;
+  connectedAt: string;
+  serverVersion?: string;
+}
+
+export interface IConnectionStatus extends IConnectionInfo {
+  healthy: boolean;
+  detail: string;
+}
+
+export interface IChatSummary {
+  harness: THarnessName;
+  chatId: string;
+  title: string;
+  directory: string;
+  updatedAt: string;
+  isActive?: boolean;
+  meta?: Record<string, string>;
+}
+
+export interface IChatMessage {
+  role: string;
+  text: string;
+  timestamp?: string;
+}
+
+export interface IChatTranscript {
+  harness: THarnessName;
+  chatId: string;
+  title: string;
+  directory: string;
+  totalMessages?: number;
+  messages: IChatMessage[];
+}
+
+export interface ISendResult {
+  harness: THarnessName;
+  chatId: string;
+  reply: string;
+  via: string;
+}
+
+export interface IHarnessConnection {
+  readonly connectionId: string;
+  readonly harness: THarnessName;
+  readonly serverUrl: string;
+  readonly directory: string;
+  readonly state: TConnectionState;
+
+  connect(): Promise<void>;
+  getInfo(): IConnectionInfo;
+  getStatus(): Promise<IConnectionStatus>;
+  listChats(limitArg: number): Promise<IChatSummary[]>;
+  readChat(chatIdArg: string, limitArg: number, maxCharsArg: number): Promise<IChatTranscript>;
+  sendMessage(
+    chatIdArg: string,
+    messageArg: string,
+    timeoutSecondsArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<ISendResult>;
+  close(reasonArg?: string): Promise<void>;
+}

package/ts/plugins.ts

@@ -0,0 +1,30 @@
+// Node native modules
+import * as crypto from 'node:crypto';
+import * as http from 'node:http';
+import * as stream from 'node:stream';
+import type { AddressInfo } from 'node:net';
+
+export { crypto, http, stream };
+export type { AddressInfo };
+
+// Third-party modules
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Client as McpClient } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { WebSocket as WsWebSocket, WebSocketServer } from 'ws';
+import type { RawData } from 'ws';
+import { z } from 'zod';
+
+export {
+  InMemoryTransport,
+  McpClient,
+  McpServer,
+  StdioServerTransport,
+  WebSocketServer,
+  WsWebSocket,
+  z,
+};
+export type { RawData };
+export type { Transport };