Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

refactor(mcp): share tool registration and annotations (#1485)

mldangelo-oaifed9fa04d863
diff --git a/plugins/codex-security/mcp-app/server.ts b/plugins/codex-security/mcp-app/server.ts
index 9762fb389..a6f92409e 100644
--- a/plugins/codex-security/mcp-app/server.ts
+++ b/plugins/codex-security/mcp-app/server.ts
@@ -501,11 +501,6 @@ const findingRemediationSchema = {
summary: z.string().trim().max(2400).optional(),
verificationSummary: z.string().trim().max(2400).optional(),
};
-const findingRemediationRequestSchema = {
- actionToken: z.string().uuid(),
- occurrenceId: occurrenceIdSchema,
- requestId: z.string().uuid(),
-};
const findingRemediationActionRequestSchema = {
action: z.enum(["apply", "verify"]),
actionToken: z.string().uuid(),
@@ -783,12 +778,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Fallback for interactive Codex Security workflows when the host-native request_user_input tool is unavailable. Presents one to three non-sensitive multiple-choice questions through standard MCP form elicitation and waits for the user's response. Never call this tool in headless, automation, or other non-interactive sessions.",
inputSchema: requestUserInputSchema,
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: false,
- openWorldHint: false,
- },
+ annotations: { ...readingAnnotations, idempotentHint: false },
_meta: modelActionMeta,
},
async ({ questions }, extra) => {
@@ -1694,7 +1684,7 @@ export function createCodexSecurityServer(): McpServer {
title: "Request Codex Security Finding Remediation",
description:
"App-only. Queue a completed finding for Codex remediation before sending the host a generate or regenerate request.",
- inputSchema: findingRemediationRequestSchema,
+ inputSchema: findingRemediationClaimSchema,
annotations: writingAnnotations,
_meta: appMeta,
},
@@ -1742,105 +1732,69 @@ export function createCodexSecurityServer(): McpServer {
),
);
- server.registerTool(
- "claim_codex_security_finding_remediation_resend",
+ for (const { name, title, description, annotations, command, message } of [
{
+ name: "claim_codex_security_finding_remediation_resend",
title: "Claim Codex Security Finding Remediation Resend",
description:
"App-only. Atomically take ownership of an unowned or stale remediation host request before resending it.",
- inputSchema: findingRemediationClaimSchema,
annotations: writingAnnotations,
- _meta: appMeta,
+ command: "claim-finding-remediation-resend",
+ message: "Claimed the local Codex Security finding remediation resend.",
},
- async ({ occurrenceId, requestId, actionToken }) =>
- scanActionResult(
- await runWorkbench([
- "claim-finding-remediation-resend",
- "--occurrence-id",
- occurrenceId,
- "--request-id",
- requestId,
- "--action-token",
- actionToken,
- ]),
- "Claimed the local Codex Security finding remediation resend.",
- ),
- );
-
- server.registerTool(
- "release_codex_security_finding_remediation_claim",
{
+ name: "release_codex_security_finding_remediation_claim",
title: "Release Codex Security Finding Remediation Claim",
description:
"App-only. Release a locally owned remediation host request after message delivery fails.",
- inputSchema: findingRemediationClaimSchema,
annotations: writingAnnotations,
- _meta: appMeta,
+ command: "release-finding-remediation-claim",
+ message: "Released the local Codex Security finding remediation claim.",
},
- async ({ occurrenceId, requestId, actionToken }) =>
- scanActionResult(
- await runWorkbench([
- "release-finding-remediation-claim",
- "--occurrence-id",
- occurrenceId,
- "--request-id",
- requestId,
- "--action-token",
- actionToken,
- ]),
- "Released the local Codex Security finding remediation claim.",
- ),
- );
-
- server.registerTool(
- "cancel_codex_security_finding_remediation_request",
{
+ name: "cancel_codex_security_finding_remediation_request",
title: "Cancel Codex Security Finding Remediation Request",
description:
"App-only. Roll back an owned remediation request after the user declines its host follow-up.",
- inputSchema: findingRemediationClaimSchema,
annotations: destructiveAnnotations,
- _meta: appMeta,
+ command: "cancel-finding-remediation-request",
+ message: "Canceled the local Codex Security finding remediation request.",
},
- async ({ occurrenceId, requestId, actionToken }) =>
- scanActionResult(
- await runWorkbench([
- "cancel-finding-remediation-request",
- "--occurrence-id",
- occurrenceId,
- "--request-id",
- requestId,
- "--action-token",
- actionToken,
- ]),
- "Canceled the local Codex Security finding remediation request.",
- ),
- );
-
- server.registerTool(
- "mark_codex_security_finding_remediation_delivered",
{
+ name: "mark_codex_security_finding_remediation_delivered",
title: "Mark Codex Security Finding Remediation Delivered",
description:
"App-only. Seal host-message delivery ownership before Codex starts a remediation worker.",
- inputSchema: findingRemediationClaimSchema,
annotations: writingAnnotations,
- _meta: appMeta,
- },
- async ({ occurrenceId, requestId, actionToken }) =>
- scanActionResult(
- await runWorkbench([
- "mark-finding-remediation-delivered",
- "--occurrence-id",
- occurrenceId,
- "--request-id",
- requestId,
- "--action-token",
- actionToken,
- ]),
+ command: "mark-finding-remediation-delivered",
+ message:
"Marked the local Codex Security finding remediation request as delivered.",
- ),
- );
+ },
+ ]) {
+ server.registerTool(
+ name,
+ {
+ title,
+ description,
+ inputSchema: findingRemediationClaimSchema,
+ annotations,
+ _meta: appMeta,
+ },
+ async ({ occurrenceId, requestId, actionToken }) =>
+ scanActionResult(
+ await runWorkbench([
+ command,
+ "--occurrence-id",
+ occurrenceId,
+ "--request-id",
+ requestId,
+ "--action-token",
+ actionToken,
+ ]),
+ message,
+ ),
+ );
+ }
server.registerTool(
"set_codex_security_finding_remediation",
diff --git a/plugins/codex-security/mcp-app/src/server/handoff-tools.ts b/plugins/codex-security/mcp-app/src/server/handoff-tools.ts
index ed9667aaa..1e41ca01c 100644
--- a/plugins/codex-security/mcp-app/src/server/handoff-tools.ts
+++ b/plugins/codex-security/mcp-app/src/server/handoff-tools.ts
@@ -27,111 +27,79 @@ export const handoffClaimTokenSchema = z.union([
z.string().uuid(),
recoveryHandoffClaimTokenSchema,
]);
-const handoffClaimSchema = {
+const handoffClaimSchema = z.object({
claimToken: handoffClaimTokenSchema,
scanId: z.string().uuid(),
-};
-const handoffTakeoverSchema = {
- ...handoffClaimSchema,
+});
+const handoffTakeoverSchema = handoffClaimSchema.extend({
takeOverStale: z.boolean().optional(),
-};
-const scanContinuationThreadSchema = {
- ...handoffClaimSchema,
+});
+const scanContinuationThreadSchema = handoffClaimSchema.extend({
threadId: z.string().trim().min(1).max(512),
-};
+});
export function registerScanHandoffTools(
server: McpServer,
{ appMeta, runWorkbench, workspaceResult }: ScanHandoffToolDependencies,
) {
- server.registerTool(
- "mark_codex_security_scan_handoff_delivered",
+ for (const { name, title, description, inputSchema, command } of [
{
+ name: "mark_codex_security_scan_handoff_delivered",
title: "Record Delivered Codex Security Handoff",
description:
"App-only. Record that the launched scan instructions were delivered to Codex.",
inputSchema: handoffClaimSchema,
- annotations: writingAnnotations,
- _meta: appMeta,
+ command: "mark-handoff-delivered",
},
- async ({ scanId, claimToken }) => {
- const workspace = (await runWorkbench([
- "mark-handoff-delivered",
- "--scan-id",
- scanId,
- "--claim-token",
- claimToken,
- ])) as HandoffWorkspaceState;
- return workspaceResult(workspace);
- },
- );
-
- server.registerTool(
- "claim_codex_security_scan_handoff_delivery",
{
+ name: "claim_codex_security_scan_handoff_delivery",
title: "Claim Codex Security Handoff Delivery",
description:
"App-only. Durably claim scan handoff delivery before sending continuation instructions to Codex.",
inputSchema: handoffTakeoverSchema,
- annotations: writingAnnotations,
- _meta: appMeta,
+ command: "claim-handoff-delivery",
},
- async ({ scanId, claimToken, takeOverStale }) => {
- const workspace = (await runWorkbench([
- "claim-handoff-delivery",
- "--scan-id",
- scanId,
- "--claim-token",
- claimToken,
- ...(takeOverStale ? ["--take-over-stale"] : []),
- ])) as HandoffWorkspaceState;
- return workspaceResult(workspace);
- },
- );
-
- server.registerTool(
- "release_codex_security_scan_handoff_delivery",
{
+ name: "release_codex_security_scan_handoff_delivery",
title: "Release Codex Security Handoff Delivery",
description:
"App-only. Release a failed scan handoff delivery claim so the app can retry it.",
inputSchema: handoffClaimSchema,
- annotations: writingAnnotations,
- _meta: appMeta,
+ command: "release-handoff-delivery",
},
- async ({ scanId, claimToken }) => {
- const workspace = (await runWorkbench([
- "release-handoff-delivery",
- "--scan-id",
- scanId,
- "--claim-token",
- claimToken,
- ])) as HandoffWorkspaceState;
- return workspaceResult(workspace);
- },
- );
-
- server.registerTool(
- "attach_codex_security_scan_continuation_thread",
{
+ name: "attach_codex_security_scan_continuation_thread",
title: "Attach Codex Security Scan Thread",
description:
"App-only. Persist the normal local Codex thread created for a claimed scan handoff.",
inputSchema: scanContinuationThreadSchema,
- annotations: writingAnnotations,
- _meta: appMeta,
+ command: "attach-scan-continuation-thread",
},
- async ({ scanId, claimToken, threadId }) => {
- const workspace = (await runWorkbench([
- "attach-scan-continuation-thread",
- "--scan-id",
- scanId,
- "--claim-token",
- claimToken,
- "--thread-id",
- threadId,
- ])) as HandoffWorkspaceState;
- return workspaceResult(workspace);
- },
- );
+ ] as const) {
+ server.registerTool(
+ name,
+ {
+ title,
+ description,
+ inputSchema,
+ annotations: writingAnnotations,
+ _meta: appMeta,
+ },
+ async (input: z.infer<typeof inputSchema>) => {
+ const arguments_ = [
+ command,
+ "--scan-id",
+ input.scanId,
+ "--claim-token",
+ input.claimToken,
+ ];
+ if ("takeOverStale" in input && input.takeOverStale)
+ arguments_.push("--take-over-stale");
+ if ("threadId" in input) arguments_.push("--thread-id", input.threadId);
+ return workspaceResult(
+ (await runWorkbench(arguments_)) as HandoffWorkspaceState,
+ );
+ },
+ );
+ }
}
diff --git a/plugins/codex-security/mcp-app/src/server/tool-annotations.ts b/plugins/codex-security/mcp-app/src/server/tool-annotations.ts
index 0253fdced..124c601a3 100644
--- a/plugins/codex-security/mcp-app/src/server/tool-annotations.ts
+++ b/plugins/codex-security/mcp-app/src/server/tool-annotations.ts
@@ -6,8 +6,6 @@ export const readingAnnotations = {
};
export const writingAnnotations = {
+ ...readingAnnotations,
readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
};
diff --git a/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts b/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts
index bf7f86456..8384b770c 100644
--- a/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts
+++ b/plugins/codex-security/mcp-app/tests/test_mcp_app_smoke.ts
@@ -2434,15 +2434,22 @@ try {
);
const handoffClaimToken = randomUUID();
- const claimedHandoff = await testServer.callTool(2002, {
- name: "claim_codex_security_scan_handoff_delivery",
- arguments: { claimToken: handoffClaimToken, scanId },
- });
- assertNoError(claimedHandoff);
- assert.equal(
- claimedHandoff.result.structuredContent.workspace.results.handoffClaimToken,
- handoffClaimToken,
- );
+ for (const [index, name] of [
+ "claim_codex_security_scan_handoff_delivery",
+ "release_codex_security_scan_handoff_delivery",
+ "claim_codex_security_scan_handoff_delivery",
+ ].entries()) {
+ const claimedHandoff = await testServer.callTool(200200 + index, {
+ name,
+ arguments: { claimToken: handoffClaimToken, scanId },
+ });
+ assertNoError(claimedHandoff);
+ assert.equal(
+ claimedHandoff.result.structuredContent.workspace.results
+ .handoffClaimToken,
+ index === 1 ? null : handoffClaimToken,
+ );
+ }
const attachedHandoff = await testServer.callTool(20021, {
name: "attach_codex_security_scan_continuation_thread",
arguments: {
@@ -2912,20 +2919,28 @@ try {
},
);
- const requestedPatch = await testServer.callTool(61, {
- name: "request_codex_security_finding_remediation",
- arguments: {
- actionToken: generationActionToken,
- occurrenceId,
- requestId: remediationRequestId,
- },
- });
- assertNoError(requestedPatch);
- assert.equal(
- requestedPatch.result.structuredContent.scan.findings[0].remediationState
- .state,
- "requested",
- );
+ for (const [index, name] of [
+ "request_codex_security_finding_remediation",
+ "release_codex_security_finding_remediation_claim",
+ "claim_codex_security_finding_remediation_resend",
+ ].entries()) {
+ const requestedPatch = await testServer.callTool(6100 + index, {
+ name,
+ arguments: {
+ actionToken: generationActionToken,
+ occurrenceId,
+ requestId: remediationRequestId,
+ },
+ });
+ assertNoError(requestedPatch);
+ const remediation =
+ requestedPatch.result.structuredContent.scan.findings[0].remediationState;
+ assert.equal(remediation.state, "requested");
+ assert.equal(
+ remediation.actionClaimToken,
+ index === 1 ? null : generationActionToken,
+ );
+ }
const rejectedPendingClose = await testServer.callTool(161, {
name: "set_codex_security_finding_triage",
arguments: { occurrenceId, status: "closed", closeReason: "already_fixed" },