feat: codex-shell-tool-mcp

[bolinfest]

This adds a GitHub workflow for building a new npm module we are experimenting with that contains an MCP server for running Bash commands. The new workflow, shell-tool-mcp, is a dependency of the general release workflow so that we continue to use one version number for all artifacts across the project in one GitHub release.

.github/workflows/shell-tool-mcp.yml is the primary workflow introduced by this PR, which does the following:

• builds the codex-exec-mcp-server and codex-execve-wrapper executables for both arm64 and x64 versions of Mac and Linux (preferring the MUSL version for Linux)
• builds Bash (dynamically linked) for a [comically] large number of platforms (both x64 and arm64 for most) with a small patch specified by shell-tool-mcp/patches/bash-exec-wrapper.patch:
  • debian-11
  • debian-12
  • ubuntu-20.04
  • ubuntu-22.04
  • ubuntu-24.04
  • centos-9
  • macos-13 (x64 only)
  • macos-14 (arm64 only)
  • macos-15 (arm64 only)
• builds the TypeScript for the [new] Node module declared in the shell-tool-mcp/ folder, which creates bin/mcp-server.js
• adds all of the native binaries to shell-tool-mcp/vendor/ folder; bin/mcp-server.js does a runtime check to determine which ones to execute
• uses npm pack to create the .tgz for the module
• if publish: true is set, invokes the npm publish call with the .tgz

The justification for building Bash for so many different operating systems is because, since it is dynamically linked, we want to increase our confidence that the version we build is compatible with the glibc whatever OS we end up running on. (Note this is less of a concern with codex-exec-mcp-server and codex-execve-wrapper on Linux, as they are statically linked.)

This PR also introduces the code for the npm module in shell-tool-mcp/ (the proposed module name is @openai/codex-shell-tool-mcp). Initially, I intended the module to be a single file of vanilla JavaScript (like codex-cli/bin/codex.js), but some of the logic seemed a bit tricky, so I decided to port it to TypeScript and add unit tests.

shell-tool-mcp/src/index.ts defines the main() function for the module, which performs runtime checks to determine the clang triple to find the path to the Rust executables within the vendor/ folder (resolveTargetTriple()). It uses a combination of readOsRelease() and resolveBashPath() to determine the correct Bash executable to run in the environment. Ultimately, it spawns a command like the following:

codex-exec-mcp-server \
    --execve codex-execve-wrapper \
    --bash custom-bash "$@"

Note .github/workflows/shell-tool-mcp-ci.yml defines a fairly standard CI job for the module (format/build/test).

To test this PR, I pushed this branch to my personal fork of Codex and ran the CI job there:

https://github.com/bolinfest/codex/actions/runs/19564311320

Admittedly, the graph looks a bit wild now:

But when it finished, I was able to download codex-shell-tool-mcp-npm from the Artifacts for the workflow in an empty temp directory, unzip the .zip and then the .tgz inside it, followed by xattr -rc . to remove the quarantine bits. Then I ran:

npx @modelcontextprotocol/inspector node /private/tmp/foobar4/package/bin/mcp-server.js

which launched the MCP Inspector and I was able to use it as expected! This bodes well that this should work once the package is published to npm:

npx @modelcontextprotocol/inspector npx @openai/codex-shell-tool-mcp

Also, to verify the package contains what I expect:

/tmp/foobar4/package$ tree
.
├── bin
│   └── mcp-server.js
├── package.json
├── README.md
└── vendor
    ├── aarch64-apple-darwin
    │   ├── bash
    │   │   ├── macos-14
    │   │   │   └── bash
    │   │   └── macos-15
    │   │       └── bash
    │   ├── codex-exec-mcp-server
    │   └── codex-execve-wrapper
    ├── aarch64-unknown-linux-musl
    │   ├── bash
    │   │   ├── centos-9
    │   │   │   └── bash
    │   │   ├── debian-11
    │   │   │   └── bash
    │   │   ├── debian-12
    │   │   │   └── bash
    │   │   ├── ubuntu-20.04
    │   │   │   └── bash
    │   │   ├── ubuntu-22.04
    │   │   │   └── bash
    │   │   └── ubuntu-24.04
    │   │       └── bash
    │   ├── codex-exec-mcp-server
    │   └── codex-execve-wrapper
    ├── x86_64-apple-darwin
    │   ├── bash
    │   │   └── macos-13
    │   │       └── bash
    │   ├── codex-exec-mcp-server
    │   └── codex-execve-wrapper
    └── x86_64-unknown-linux-musl
        ├── bash
        │   ├── centos-9
        │   │   └── bash
        │   ├── debian-11
        │   │   └── bash
        │   ├── debian-12
        │   │   └── bash
        │   ├── ubuntu-20.04
        │   │   └── bash
        │   ├── ubuntu-22.04
        │   │   └── bash
        │   └── ubuntu-24.04
        │       └── bash
        ├── codex-exec-mcp-server
        └── codex-execve-wrapper

26 directories, 26 files

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

macOS 13 arm64 Bash artifact missing

The reusable build only produces a macOS 13 Bash binary for x86_64-apple-darwin (matrix lines 239-241). However the launcher uses selectDarwinBash to pick the macos-13 variant whenever os.release() reports Darwin 22 (macOS 13) regardless of CPU, and resolveTargetTriple returns aarch64-apple-darwin on Apple Silicon. On macOS 13 arm64 hosts this workflow never builds vendor/aarch64-apple-darwin/bash/macos-13/bash, so mcp-server.js will throw “Required binary missing” at startup on that platform. Please add an arm64 macOS 13 build or adjust selection to avoid targeting an absent binary.

Useful? React with 👍 / 👎.