fix: separate `codex mcp` into `codex mcp-server` and `codex app-server` (#4471)
This is a very large PR with some non-backwards-compatible changes.
Historically, `codex mcp` (or `codex mcp serve`) started a JSON-RPC-ish
server that had two overlapping responsibilities:
- Running an MCP server, providing some basic tool calls.
- Running the app server used to power experiences such as the VS Code
extension.
This PR aims to separate these into distinct concepts:
- `codex mcp-server` for the MCP server
- `codex app-server` for the "application server"
Note `codex mcp` still exists because it already has its own subcommands
for MCP management (`list`, `add`, etc.)
The MCP logic continues to live in `codex-rs/mcp-server` whereas the
refactored app server logic is in the new `codex-rs/app-server` folder.
Note that most of the existing integration tests in
`codex-rs/mcp-server/tests/suite` were actually for the app server, so
all the tests have been moved with the exception of
`codex-rs/mcp-server/tests/suite/mod.rs`.
Because this is already a large diff, I tried not to change more than I
had to, so `codex-rs/app-server/tests/common/mcp_process.rs` still uses
the name `McpProcess` for now, but I will do some mechanical renamings
to things like `AppServer` in subsequent PRs.
While `mcp-server` and `app-server` share some overlapping functionality
(like reading streams of JSONL and dispatching based on message types)
and some differences (completely different message types), I ended up
doing a bit of copypasta between the two crates, as both have somewhat
similar `message_processor.rs` and `outgoing_message.rs` files for now,
though I expect them to diverge more in the near future.
One material change is that of the initialize handshake for `codex
app-server`, as we no longer use the MCP types for that handshake.
Instead, we update `codex-rs/protocol/src/mcp_protocol.rs` to add an
`Initialize` variant to `ClientRequest`, which takes the `ClientInfo`
object we need to update the `USER_AGENT_SUFFIX` in
`codex-rs/app-server/src/message_processor.rs`.
One other material change is in
`codex-rs/app-server/src/codex_message_processor.rs` where I eliminated
a use of the `send_event_as_notification()` method I am generally trying
to deprecate (because it blindly maps an `EventMsg` into a
`JSONNotification`) in favor of `send_server_notification()`, which
takes a `ServerNotification`, as that is intended to be a custom enum of
all notification types supported by the app server. So to make this
update, I had to introduce a new variant of `ServerNotification`,
`SessionConfigured`, which is a non-backwards compatible change with the
old `codex mcp`, and clients will have to be updated after the next
release that contains this PR. Note that
`codex-rs/app-server/tests/suite/list_resume.rs` also had to be update
to reflect this change.
I introduced `codex-rs/utils/json-to-toml/src/lib.rs` as a small utility
crate to avoid some of the copying between `mcp-server` and
`app-server`.
2025-09-30 00:06:18 -07:00
|
|
|
use std::sync::atomic::AtomicUsize;
|
|
|
|
|
use std::sync::atomic::Ordering;
|
|
|
|
|
|
|
|
|
|
use wiremock::Mock;
|
|
|
|
|
use wiremock::MockServer;
|
|
|
|
|
use wiremock::Respond;
|
|
|
|
|
use wiremock::ResponseTemplate;
|
|
|
|
|
use wiremock::matchers::method;
|
|
|
|
|
use wiremock::matchers::path;
|
|
|
|
|
|
|
|
|
|
/// Create a mock server that will provide the responses, in order, for
|
|
|
|
|
/// requests to the `/v1/chat/completions` endpoint.
|
|
|
|
|
pub async fn create_mock_chat_completions_server(responses: Vec<String>) -> MockServer {
|
|
|
|
|
let server = MockServer::start().await;
|
|
|
|
|
|
|
|
|
|
let num_calls = responses.len();
|
|
|
|
|
let seq_responder = SeqResponder {
|
|
|
|
|
num_calls: AtomicUsize::new(0),
|
|
|
|
|
responses,
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
Mock::given(method("POST"))
|
|
|
|
|
.and(path("/v1/chat/completions"))
|
|
|
|
|
.respond_with(seq_responder)
|
|
|
|
|
.expect(num_calls as u64)
|
|
|
|
|
.mount(&server)
|
|
|
|
|
.await;
|
|
|
|
|
|
|
|
|
|
server
|
|
|
|
|
}
|
|
|
|
|
|
2025-11-05 12:28:43 -08:00
|
|
|
/// Same as `create_mock_chat_completions_server` but does not enforce an
|
|
|
|
|
/// expectation on the number of calls.
|
|
|
|
|
pub async fn create_mock_chat_completions_server_unchecked(responses: Vec<String>) -> MockServer {
|
|
|
|
|
let server = MockServer::start().await;
|
|
|
|
|
|
|
|
|
|
let seq_responder = SeqResponder {
|
|
|
|
|
num_calls: AtomicUsize::new(0),
|
|
|
|
|
responses,
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
Mock::given(method("POST"))
|
|
|
|
|
.and(path("/v1/chat/completions"))
|
|
|
|
|
.respond_with(seq_responder)
|
|
|
|
|
.mount(&server)
|
|
|
|
|
.await;
|
|
|
|
|
|
|
|
|
|
server
|
|
|
|
|
}
|
|
|
|
|
|
fix: separate `codex mcp` into `codex mcp-server` and `codex app-server` (#4471)
This is a very large PR with some non-backwards-compatible changes.
Historically, `codex mcp` (or `codex mcp serve`) started a JSON-RPC-ish
server that had two overlapping responsibilities:
- Running an MCP server, providing some basic tool calls.
- Running the app server used to power experiences such as the VS Code
extension.
This PR aims to separate these into distinct concepts:
- `codex mcp-server` for the MCP server
- `codex app-server` for the "application server"
Note `codex mcp` still exists because it already has its own subcommands
for MCP management (`list`, `add`, etc.)
The MCP logic continues to live in `codex-rs/mcp-server` whereas the
refactored app server logic is in the new `codex-rs/app-server` folder.
Note that most of the existing integration tests in
`codex-rs/mcp-server/tests/suite` were actually for the app server, so
all the tests have been moved with the exception of
`codex-rs/mcp-server/tests/suite/mod.rs`.
Because this is already a large diff, I tried not to change more than I
had to, so `codex-rs/app-server/tests/common/mcp_process.rs` still uses
the name `McpProcess` for now, but I will do some mechanical renamings
to things like `AppServer` in subsequent PRs.
While `mcp-server` and `app-server` share some overlapping functionality
(like reading streams of JSONL and dispatching based on message types)
and some differences (completely different message types), I ended up
doing a bit of copypasta between the two crates, as both have somewhat
similar `message_processor.rs` and `outgoing_message.rs` files for now,
though I expect them to diverge more in the near future.
One material change is that of the initialize handshake for `codex
app-server`, as we no longer use the MCP types for that handshake.
Instead, we update `codex-rs/protocol/src/mcp_protocol.rs` to add an
`Initialize` variant to `ClientRequest`, which takes the `ClientInfo`
object we need to update the `USER_AGENT_SUFFIX` in
`codex-rs/app-server/src/message_processor.rs`.
One other material change is in
`codex-rs/app-server/src/codex_message_processor.rs` where I eliminated
a use of the `send_event_as_notification()` method I am generally trying
to deprecate (because it blindly maps an `EventMsg` into a
`JSONNotification`) in favor of `send_server_notification()`, which
takes a `ServerNotification`, as that is intended to be a custom enum of
all notification types supported by the app server. So to make this
update, I had to introduce a new variant of `ServerNotification`,
`SessionConfigured`, which is a non-backwards compatible change with the
old `codex mcp`, and clients will have to be updated after the next
release that contains this PR. Note that
`codex-rs/app-server/tests/suite/list_resume.rs` also had to be update
to reflect this change.
I introduced `codex-rs/utils/json-to-toml/src/lib.rs` as a small utility
crate to avoid some of the copying between `mcp-server` and
`app-server`.
2025-09-30 00:06:18 -07:00
|
|
|
struct SeqResponder {
|
|
|
|
|
num_calls: AtomicUsize,
|
|
|
|
|
responses: Vec<String>,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl Respond for SeqResponder {
|
|
|
|
|
fn respond(&self, _: &wiremock::Request) -> ResponseTemplate {
|
|
|
|
|
let call_num = self.num_calls.fetch_add(1, Ordering::SeqCst);
|
|
|
|
|
match self.responses.get(call_num) {
|
|
|
|
|
Some(response) => ResponseTemplate::new(200)
|
|
|
|
|
.insert_header("content-type", "text/event-stream")
|
|
|
|
|
.set_body_raw(response.clone(), "text/event-stream"),
|
|
|
|
|
None => panic!("no response for {call_num}"),
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|