mcp-codex-worker 0.1.0

package/dist/src/types/codex.d.ts

@@ -0,0 +1,50 @@
+export type RequestId = string | number;
+export interface JsonLineRequest {
+    method: string;
+    id: RequestId;
+    params: unknown;
+}
+export interface JsonLineNotification {
+    method: string;
+    params: unknown;
+}
+export interface JsonLineResponse {
+    id: RequestId;
+    result?: unknown;
+    error?: unknown;
+}
+export type JsonLineMessage = JsonLineRequest | JsonLineNotification | JsonLineResponse;
+export interface InitializeParams {
+    clientInfo: {
+        name: string;
+        title: string | null;
+        version: string;
+    };
+    capabilities: {
+        experimentalApi: boolean;
+        optOutNotificationMethods?: string[] | null;
+    } | null;
+}
+export interface PendingServerRequest {
+    id: RequestId;
+    method: string;
+    params: unknown;
+    createdAt: string;
+    resolvedAt?: string | undefined;
+    response?: unknown;
+    resolutionError?: string | undefined;
+    status: 'pending' | 'resolved' | 'failed';
+}
+export interface RuntimeOperation {
+    operationId: string;
+    requestId: RequestId;
+    method: string;
+    threadId?: string | undefined;
+    turnId?: string | undefined;
+    startedAt: string;
+    completedAt?: string | undefined;
+    status: 'running' | 'completed' | 'failed';
+    result?: unknown;
+    error?: string;
+    pendingRequestIds: RequestId[];
+}

package/dist/src/types/codex.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codex.js.map

package/dist/src/types/codex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../../src/types/codex.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mcp-codex-worker",
+  "version": "0.1.0",
+  "description": "MCP server bridge for Codex app-server",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "bin": {
+    "mcp-codex-worker": "bin/mcp-codex-worker.mjs"
+  },
+  "files": [
+    "bin",
+    "dist/src",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepack": "npm run build",
+    "serve": "node --import tsx src/index.ts",
+    "smoke": "node --import tsx scripts/smoke.ts",
+    "test": "npm run test:unit",
+    "test:unit": "node --import tsx --test test/**/*.test.ts"
+  },
+  "keywords": [
+    "mcp",
+    "codex",
+    "app-server"
+  ],
+  "author": "Yigit Konur",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yigitkonur/mcp-codex-worker.git"
+  },
+  "homepage": "https://github.com/yigitkonur/mcp-codex-worker#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "tsx": "^4.20.6",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}
+

package/src/app.ts

@@ -0,0 +1,417 @@
+import {
+  createToolDefinitions,
+  type RequestRespondInput,
+  type ThreadListInput,
+  type ThreadReadInput,
+  type ThreadResumeInput,
+  type ThreadStartInput,
+  type ToolDefinition,
+  type TurnInterruptInput,
+  type TurnStartInput,
+  type TurnSteerInput,
+  type WaitInput,
+} from './mcp/tool-definitions.js';
+import { OPERATION_POLL_INTERVAL_MS, REQUEST_TIMEOUT_MS } from './config/defaults.js';
+import { CodexRuntime } from './services/codex-runtime.js';
+
+export interface ResourceDefinition {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+export class CodexWorkerApp {
+  private readonly runtime = new CodexRuntime();
+
+  async initialize(): Promise<void> {}
+
+  async shutdown(): Promise<void> {
+    await this.runtime.shutdown();
+  }
+
+  async listTools(): Promise<ToolDefinition[]> {
+    try {
+      const modelIds = await this.runtime.listVisibleModelIds();
+      return createToolDefinitions(modelIds);
+    } catch {
+      return createToolDefinitions([]);
+    }
+  }
+
+  listResources(): ResourceDefinition[] {
+    const base: ResourceDefinition[] = [
+      {
+        uri: 'codex://threads',
+        name: 'Codex Threads',
+        description: 'Latest threads from `thread/list`',
+        mimeType: 'application/json',
+      },
+      {
+        uri: 'codex://models',
+        name: 'Codex Models',
+        description: 'Visible models from `model/list`',
+        mimeType: 'application/json',
+      },
+      {
+        uri: 'codex://account',
+        name: 'Codex Account',
+        description: 'Account data from `account/read`',
+        mimeType: 'application/json',
+      },
+      {
+        uri: 'codex://requests',
+        name: 'Codex Requests',
+        description: 'Pending server requests from app-server',
+        mimeType: 'application/json',
+      },
+    ];
+
+    for (const threadId of this.runtime.listKnownThreadIds()) {
+      base.push(
+        {
+          uri: `codex://thread/${threadId}`,
+          name: `Thread ${threadId}`,
+          description: 'Thread from `thread/read`',
+          mimeType: 'application/json',
+        },
+        {
+          uri: `codex://thread/${threadId}/events`,
+          name: `Thread ${threadId} events`,
+          description: 'Observed notifications for this thread',
+          mimeType: 'application/json',
+        },
+      );
+    }
+
+    return base;
+  }
+
+  async readResource(uri: string): Promise<{ mimeType: string; text: string }> {
+    if (uri === 'codex://threads') {
+      const response = await this.runtime.request('thread/list', { limit: 50 }) as {
+        data?: Array<{ id?: string }>;
+      };
+      for (const row of response.data ?? []) {
+        if (typeof row.id === 'string') {
+          this.runtime.rememberThreadId(row.id);
+        }
+      }
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify(response, null, 2),
+      };
+    }
+
+    if (uri === 'codex://models') {
+      const response = {
+        data: await this.runtime.listModels(false),
+      };
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify(response, null, 2),
+      };
+    }
+
+    if (uri === 'codex://account') {
+      const [account, limits] = await Promise.all([
+        this.runtime.request('account/read', {}),
+        this.runtime.request('account/rateLimits/read', {}),
+      ]);
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify({ account, rate_limits: limits }, null, 2),
+      };
+    }
+
+    if (uri === 'codex://requests') {
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify({
+          requests: this.runtime.getPendingServerRequests(false),
+        }, null, 2),
+      };
+    }
+
+    const threadEventsMatch = /^codex:\/\/thread\/([^/]+)\/events$/.exec(uri);
+    if (threadEventsMatch) {
+      const threadId = decodeURIComponent(threadEventsMatch[1]!);
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify({
+          thread_id: threadId,
+          events: await this.runtime.getThreadEvents(threadId),
+        }, null, 2),
+      };
+    }
+
+    const threadMatch = /^codex:\/\/thread\/([^/]+)$/.exec(uri);
+    if (threadMatch) {
+      const threadId = decodeURIComponent(threadMatch[1]!);
+      const response = await this.runtime.request('thread/read', {
+        threadId,
+        includeTurns: true,
+      });
+      return {
+        mimeType: 'application/json',
+        text: JSON.stringify(response, null, 2),
+      };
+    }
+
+    return {
+      mimeType: 'application/json',
+      text: JSON.stringify({ error: `Unknown resource URI: ${uri}` }, null, 2),
+    };
+  }
+
+  async callTool(name: string, args: unknown): Promise<string> {
+    const tools = await this.listTools();
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    const validated = tool.validate(args ?? {});
+    switch (name) {
+      case 'thread-start':
+        return this.handleThreadStart(validated as ThreadStartInput);
+      case 'thread-resume':
+        return this.handleThreadResume(validated as ThreadResumeInput);
+      case 'thread-read':
+        return this.handleThreadRead(validated as ThreadReadInput);
+      case 'thread-list':
+        return this.handleThreadList(validated as ThreadListInput);
+      case 'turn-start':
+        return this.handleTurnStart(validated as TurnStartInput);
+      case 'turn-steer':
+        return this.handleTurnSteer(validated as TurnSteerInput);
+      case 'turn-interrupt':
+        return this.handleTurnInterrupt(validated as TurnInterruptInput);
+      case 'model-list':
+        return JSON.stringify({
+          data: await this.runtime.listModels(false),
+        }, null, 2);
+      case 'account-read':
+        return JSON.stringify(await this.runtime.request('account/read', {}), null, 2);
+      case 'account-rate-limits-read':
+        return JSON.stringify(await this.runtime.request('account/rateLimits/read', {}), null, 2);
+      case 'skills-list':
+        return JSON.stringify(await this.runtime.request('skills/list', {}), null, 2);
+      case 'app-list':
+        return JSON.stringify(await this.runtime.request('app/list', {}), null, 2);
+      case 'request-list':
+        return JSON.stringify({
+          requests: this.runtime.getPendingServerRequests(
+            Boolean((validated as { include_resolved?: boolean }).include_resolved),
+          ),
+        }, null, 2);
+      case 'request-read':
+        return JSON.stringify({
+          request: this.runtime.getPendingServerRequest(
+            (validated as { request_id: string | number }).request_id,
+          ) ?? null,
+        }, null, 2);
+      case 'request-respond':
+        return this.handleRequestRespond(validated as RequestRespondInput);
+      case 'wait':
+        return this.handleWait(validated as WaitInput);
+      default:
+        throw new Error(`Unhandled tool: ${name}`);
+    }
+  }
+
+  private async handleThreadStart(input: ThreadStartInput): Promise<string> {
+    const built = await this.runtime.buildThreadStartParams({
+      model: input.model,
+      cwd: input.cwd,
+      developerInstructions: input.developer_instructions,
+    });
+    const response = await this.runtime.request('thread/start', built.params);
+    const threadId = (response as { thread?: { id?: string } }).thread?.id;
+    if (threadId) {
+      this.runtime.rememberThreadId(threadId);
+    }
+    return JSON.stringify({
+      method: 'thread/start',
+      remapped_from: built.remappedFrom,
+      result: response,
+    }, null, 2);
+  }
+
+  private async handleThreadResume(input: ThreadResumeInput): Promise<string> {
+    const built = await this.runtime.buildThreadResumeParams({
+      threadId: input.thread_id,
+      model: input.model,
+      cwd: input.cwd,
+      developerInstructions: input.developer_instructions,
+    });
+    const response = await this.runtime.request('thread/resume', built.params);
+    this.runtime.rememberThreadId(input.thread_id);
+    return JSON.stringify({
+      method: 'thread/resume',
+      remapped_from: built.remappedFrom,
+      result: response,
+    }, null, 2);
+  }
+
+  private async handleThreadRead(input: ThreadReadInput): Promise<string> {
+    const response = await this.runtime.request('thread/read', {
+      threadId: input.thread_id,
+      includeTurns: input.include_turns ?? true,
+    });
+    this.runtime.rememberThreadId(input.thread_id);
+    return JSON.stringify(response, null, 2);
+  }
+
+  private async handleThreadList(input: ThreadListInput): Promise<string> {
+    const response = await this.runtime.request('thread/list', {
+      limit: input.limit,
+      cursor: input.cursor ?? null,
+    }) as {
+      data?: Array<{ id?: string }>;
+    };
+    for (const row of response.data ?? []) {
+      if (typeof row.id === 'string') {
+        this.runtime.rememberThreadId(row.id);
+      }
+    }
+    return JSON.stringify(response, null, 2);
+  }
+
+  private async handleTurnStart(input: TurnStartInput): Promise<string> {
+    const built = await this.runtime.buildTurnStartParams({
+      threadId: input.thread_id,
+      userInput: input.user_input,
+      model: input.model,
+    });
+    await this.runtime.ensureThreadLoaded(input.thread_id, input.model);
+    const bridged = await this.runtime.requestWithBridge('turn/start', built.params, {
+      threadId: input.thread_id,
+    });
+    return JSON.stringify({
+      method: 'turn/start',
+      remapped_from: built.remappedFrom,
+      ...bridged,
+    }, null, 2);
+  }
+
+  private async handleTurnSteer(input: TurnSteerInput): Promise<string> {
+    const params = this.runtime.buildTurnSteerParams({
+      threadId: input.thread_id,
+      expectedTurnId: input.expected_turn_id,
+      userInput: input.user_input,
+    });
+    const bridged = await this.runtime.requestWithBridge('turn/steer', params, {
+      threadId: input.thread_id,
+    });
+    return JSON.stringify({
+      method: 'turn/steer',
+      ...bridged,
+    }, null, 2);
+  }
+
+  private async handleTurnInterrupt(input: TurnInterruptInput): Promise<string> {
+    const response = await this.runtime.request('turn/interrupt', {
+      threadId: input.thread_id,
+      turnId: input.turn_id,
+    });
+    return JSON.stringify(response, null, 2);
+  }
+
+  private async handleRequestRespond(input: RequestRespondInput): Promise<string> {
+    const pending = this.runtime.getPendingServerRequest(input.request_id);
+    if (!pending) {
+      throw new Error(`Pending server request not found: ${String(input.request_id)}`);
+    }
+
+    const payload = this.buildServerRequestPayload(pending.method, input);
+    await this.runtime.respondToServerRequest(input.request_id, payload);
+    return JSON.stringify({
+      request_id: input.request_id,
+      method: pending.method,
+      payload,
+      status: 'responded',
+    }, null, 2);
+  }
+
+  private async handleWait(input: WaitInput): Promise<string> {
+    const timeoutMs = input.timeout_ms ?? REQUEST_TIMEOUT_MS;
+    const pollIntervalMs = input.poll_interval_ms ?? OPERATION_POLL_INTERVAL_MS;
+
+    if (input.operation_id) {
+      const operation = await this.runtime.waitForOperation(input.operation_id, timeoutMs, pollIntervalMs);
+      return JSON.stringify(operation, null, 2);
+    }
+
+    if (input.thread_id) {
+      const start = Date.now();
+      while (Date.now() - start <= timeoutMs) {
+        const response = await this.runtime.request('thread/read', {
+          threadId: input.thread_id,
+          includeTurns: false,
+        }) as {
+          thread?: {
+            status?: { type?: string };
+          };
+        };
+        const statusType = response.thread?.status?.type;
+        if (statusType !== 'active') {
+          return JSON.stringify({
+            thread_id: input.thread_id,
+            status: statusType ?? 'unknown',
+            thread: response.thread ?? null,
+          }, null, 2);
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      }
+      throw new Error(`Timed out waiting for thread ${input.thread_id}`);
+    }
+
+    return JSON.stringify({
+      requests: this.runtime.getPendingServerRequests(false),
+      operations: [],
+    }, null, 2);
+  }
+
+  private buildServerRequestPayload(method: string, input: RequestRespondInput): unknown {
+    if (input.payload) {
+      return input.payload;
+    }
+
+    switch (method) {
+      case 'item/commandExecution/requestApproval':
+      case 'item/fileChange/requestApproval':
+        return {
+          decision: input.decision ?? 'accept',
+        };
+      case 'item/tool/requestUserInput':
+        return {
+          answers: input.answers ?? {},
+        };
+      case 'mcpServer/elicitation/request':
+        return {
+          action: input.action ?? 'accept',
+          content: input.content ?? null,
+          _meta: input.meta ?? null,
+        };
+      case 'item/permissions/requestApproval':
+        return {
+          permissions: input.permissions ?? {},
+          scope: input.scope ?? 'session',
+        };
+      case 'item/tool/call':
+        return {
+          contentItems: [],
+          success: true,
+        };
+      case 'applyPatchApproval':
+      case 'execCommandApproval':
+        return {
+          decision: input.decision ?? 'approved',
+        };
+      default:
+        throw new Error(
+          `No default response payload for request method ${method}. Provide payload explicitly.`,
+        );
+    }
+  }
+}

package/src/config/defaults.ts

@@ -0,0 +1,14 @@
+export const APP_NAME = 'mcp-codex-worker';
+export const APP_TITLE = 'MCP Codex Worker';
+export const REQUEST_TIMEOUT_MS = 120_000;
+export const OPERATION_BRIDGE_TIMEOUT_MS = 2_000;
+export const OPERATION_POLL_INTERVAL_MS = 250;
+
+export const CODEX_APP_SERVER_COMMAND_ENV = 'CODEX_APP_SERVER_COMMAND';
+export const CODEX_APP_SERVER_ARGS_ENV = 'CODEX_APP_SERVER_ARGS';
+export const CODEX_HOME_ENV = 'CODEX_HOME';
+export const CODEX_HOME_DIRS_ENV = 'CODEX_HOME_DIRS';
+export const CODEX_ENABLE_FLEET_ENV = 'CODEX_ENABLE_FLEET';
+
+export const PROFILE_COOLDOWN_MS = 60_000;
+

package/src/index.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { CodexWorkerApp } from './app.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json') as { version: string };
+
+const app = new CodexWorkerApp();
+const server = new Server(
+  { name: 'mcp-codex-worker', version: pkg.version },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: (await app.listTools()).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    const text = await app.callTool(request.params.name, request.params.arguments ?? {});
+    return { content: [{ type: 'text', text }] };
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+      isError: true as const,
+    };
+  }
+});
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: app.listResources(),
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const resource = await app.readResource(request.params.uri);
+  return {
+    contents: [{
+      uri: request.params.uri,
+      mimeType: resource.mimeType,
+      text: resource.text,
+    }],
+  };
+});
+
+async function main(): Promise<void> {
+  await app.initialize();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stdin.resume();
+
+  const shutdown = async () => {
+    await app.shutdown().catch(() => {});
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => void shutdown());
+  process.on('SIGTERM', () => void shutdown());
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+