Skip to content

feat(persona-kit): translate codex mcpServers into launch args#85

Merged
khaliqgant merged 2 commits into
mainfrom
feat/codex-mcpservers-translation
May 11, 2026
Merged

feat(persona-kit): translate codex mcpServers into launch args#85
khaliqgant merged 2 commits into
mainfrom
feat/codex-mcpservers-translation

Conversation

@khaliqgant
Copy link
Copy Markdown
Member

@khaliqgant khaliqgant commented May 11, 2026

Summary

  • wire persona-kit codex harness to translate persona mcpServers into codex --config mcp_servers.... args at launch
  • map stdio servers to command/args/env and remote servers to url/http_headers
  • keep codex permission injection as warning-only (unchanged)
  • add focused tests for codex HTTP + stdio translation and SSE warning behavior
  • update docs/comments that previously said codex MCP was unsupported

Relay alignment

  • mirrors the codex MCP arg pattern already used in relay (repeated --config TOML overrides)
  • keeps output deterministic by sorting server keys and inline-table keys

Validation

  • corepack pnpm --filter @agentworkforce/persona-kit test

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 11, 2026

Review Change Stack
No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0ea59fc7-c64a-4dc2-8300-4b5ad1a15f57

📥 Commits

Reviewing files that changed from the base of the PR and between 1a814da and 9bac2c2.

📒 Files selected for processing (2)
  • packages/persona-kit/src/interactive-spec.test.ts
  • packages/persona-kit/src/interactive-spec.ts
✅ Files skipped from review due to trivial changes (1)
  • packages/persona-kit/src/interactive-spec.test.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • packages/persona-kit/src/interactive-spec.ts

📝 Walkthrough

Walkthrough

This PR extends the persona-kit to wire MCP servers for the Codex harness by translating persona mcpServers into TOML config override arguments. Type documentation, integration logic, unit tests, and CLI README guidance are updated to reflect Codex support alongside existing Claude and Opencode behavior.

Changes

Codex MCP Server Support

Layer / File(s) Summary
Type Documentation
packages/persona-kit/src/types.ts
PersonaSpec.mcpServers JSDoc updated to document behavior across harnesses: Claude via --mcp-config, Codex via --config mcp_servers.<name>..., and Opencode warning-only.
Codex TOML Serialization Helpers
packages/persona-kit/src/interactive-spec.ts
Added internal helpers to serialize TOML basic strings/arrays/inline tables, build --config arguments, and construct mcp_servers.<name> entries from persona mcpServers with support for stdio and sse transports (emitting warnings for sse).
MCP Wiring in buildInteractiveSpec
packages/persona-kit/src/interactive-spec.ts
buildInteractiveSpec JSDoc updated to document Codex MCP support; Codex branch now injects mcpServers into command arguments via TOML config overrides instead of emitting an unsupported warning.
Unit Tests
packages/persona-kit/src/interactive-spec.test.ts
Added tests for HTTP and stdio MCP server translation to Codex config args, TOML key quoting test, updated warning test expectations for unsupported permissions and sse transport hints, and adjusted test inputs in an existing warning assertion.
CLI README
packages/cli/README.md
MCP capability table updated to document Codex support; tier selection guidance revised to recommend Claude or Codex for MCP-using personas; Opencode warning case added to troubleshooting section.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • AgentWorkforce/workforce#78: Both PRs modify packages/persona-kit/src/interactive-spec.ts; this PR changes Codex MCP wiring where the other PR added buildNonInteractiveSpec.
  • AgentWorkforce/workforce#73: Related changes to interactive-spec implementation and exports that overlap with this PR's edits.

Poem

🐰 I nibble TOML keys in moonlit code,

Codex now learns the MCP road.
Claude keeps its path, Opencode will warn,
Tests hop along at the break of dawn.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: adding codex mcpServers translation into launch arguments, which is the core feature implemented across the changeset.
Description check ✅ Passed The description is clearly related to the changeset, detailing the MCP server translation implementation, mapping logic, test additions, and documentation updates that match the file changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/codex-mcpservers-translation

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/persona-kit/src/interactive-spec.ts`:
- Around line 119-120: The dotted-key prefix construction in the loop using
mcpServers and the local variable prefix (mcp_servers.${name}) can produce
invalid TOML keys if name contains dots or other special chars; update the code
in packages/persona-kit/src/interactive-spec.ts to either validate server names
against an allowed charset (e.g., /^[A-Za-z0-9_-]+$/) before using them or
escape/quote the segment when building the dotted key (e.g., produce
mcp_servers."escapedName" by adding a small helper escapeTomlKey(name) that
returns a properly backslash-escaped quoted key, and use that helper when
setting prefix inside the for (const [name, server] ...) loop).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 626e0e00-e681-4d6f-b39d-eb790b754e14

📥 Commits

Reviewing files that changed from the base of the PR and between 7c5549c and 1a814da.

📒 Files selected for processing (4)
  • packages/cli/README.md
  • packages/persona-kit/src/interactive-spec.test.ts
  • packages/persona-kit/src/interactive-spec.ts
  • packages/persona-kit/src/types.ts

Comment thread packages/persona-kit/src/interactive-spec.ts Outdated
Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 potential issue.

View 3 additional findings in Devin Review.

Open in Devin Review

warnings: string[]
): void {
for (const [name, server] of Object.entries(mcpServers).sort(([a], [b]) => a.localeCompare(b))) {
const prefix = `mcp_servers.${name}`;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 MCP server name not quoted in TOML dotted-key path, producing invalid or mis-parsed TOML

In appendCodexMcpServerArgs, the MCP server name is interpolated directly into the TOML key path as a bare key: const prefix = \mcp_servers.${name}`. TOML bare keys only support [A-Za-z0-9_-]. If the server name contains dots (e.g. "foo.bar"), TOML interprets mcp_servers.foo.bar.urlas a 4-level nested path instead of the intendedmcp_servers."foo.bar".url. If the name contains spaces or other special characters, the TOML is syntactically invalid. No upstream validation in parseMcpServers (packages/persona-kit/src/parse.ts:400`) constrains MCP server names to bare-key-safe characters, so any JSON object key flows through unchecked.

Suggested change
const prefix = `mcp_servers.${name}`;
const prefix = `mcp_servers.${toTomlBasicString(name)}`;
Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

@khaliqgant
Copy link
Copy Markdown
Member Author

Addressed CodeRabbit feedback in commit 9bac2c2.

  • Added TOML-safe key segment handling for codex MCP server names via toTomlDottedKeySegment().
  • This prevents invalid mcp_servers.... paths when a server name contains dots/special chars (now emitted as quoted segments when needed).
  • Added a regression test covering a dotted server name (nango.docs) and asserting mcp_servers."nango.docs".url=...

Validation: corepack pnpm --filter @agentworkforce/persona-kit test (pass).

@khaliqgant khaliqgant merged commit c17ff02 into main May 11, 2026
2 checks passed
@khaliqgant khaliqgant deleted the feat/codex-mcpservers-translation branch May 11, 2026 18:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant