mirror of
https://github.com/openai/codex.git
synced 2026-11-15 21:50:46 +00:00
Support model catalog overrides for MCP resource tool specs (#47677)
## Why MCP resource helpers use fixed descriptions and parameter schemas, preventing the model catalog from supplying model-specific guidance. ## What changed Add `model_messages.tools.mcp_resources` entries for `list_mcp_resources`, `list_mcp_resource_templates`, and `read_mcp_resource`. Resolve these entries for the current model when constructing tool specs for direct calls and Code Mode. Descriptions and parameter schemas override independently. Preserve bundled defaults for missing fields and fall back to bundled parameters with a warning when a supplied schema is invalid. MCP resource execution remains unchanged. ## Testing Add unit coverage for independent overrides, literal descriptions, and invalid-schema fallback. Add integration coverage for resource discovery and reading through direct calls and Code Mode, plus assertions that resource tool specs follow model changes between steps. GitOrigin-RevId: 40b5beddb38b2b61c19dc9cd6013d6ba5d756dbc
This commit is contained in:
@@ -4,6 +4,7 @@ use crate::tools::context::ToolPayload;
|
||||
use crate::tools::handlers::mcp_resource_spec::create_list_mcp_resource_templates_tool;
|
||||
use crate::tools::registry::CoreToolRuntime;
|
||||
use crate::tools::registry::ToolExecutor;
|
||||
use codex_protocol::openai_models::ToolMessage;
|
||||
use codex_protocol::protocol::McpInvocation;
|
||||
use codex_tools::ToolName;
|
||||
use codex_tools::ToolSpec;
|
||||
@@ -15,7 +16,9 @@ use super::parse_args_with_default;
|
||||
use super::parse_arguments;
|
||||
use super::run_resource_operation;
|
||||
|
||||
pub struct ListMcpResourceTemplatesHandler;
|
||||
pub struct ListMcpResourceTemplatesHandler {
|
||||
spec: ToolSpec,
|
||||
}
|
||||
|
||||
impl ToolExecutor<ToolInvocation> for ListMcpResourceTemplatesHandler {
|
||||
fn tool_name(&self) -> ToolName {
|
||||
@@ -23,7 +26,7 @@ impl ToolExecutor<ToolInvocation> for ListMcpResourceTemplatesHandler {
|
||||
}
|
||||
|
||||
fn spec(&self) -> ToolSpec {
|
||||
create_list_mcp_resource_templates_tool()
|
||||
self.spec.clone()
|
||||
}
|
||||
|
||||
fn supports_parallel_tool_calls(&self) -> bool {
|
||||
@@ -39,6 +42,12 @@ impl ToolExecutor<ToolInvocation> for ListMcpResourceTemplatesHandler {
|
||||
}
|
||||
|
||||
impl ListMcpResourceTemplatesHandler {
|
||||
pub fn new(messages: Option<&ToolMessage>) -> Self {
|
||||
Self {
|
||||
spec: create_list_mcp_resource_templates_tool(messages),
|
||||
}
|
||||
}
|
||||
|
||||
async fn handle_call(
|
||||
&self,
|
||||
invocation: ToolInvocation,
|
||||
|
||||
@@ -4,6 +4,7 @@ use crate::tools::context::ToolPayload;
|
||||
use crate::tools::handlers::mcp_resource_spec::create_list_mcp_resources_tool;
|
||||
use crate::tools::registry::CoreToolRuntime;
|
||||
use crate::tools::registry::ToolExecutor;
|
||||
use codex_protocol::openai_models::ToolMessage;
|
||||
use codex_protocol::protocol::McpInvocation;
|
||||
use codex_tools::ToolName;
|
||||
use codex_tools::ToolSpec;
|
||||
@@ -15,7 +16,9 @@ use super::parse_args_with_default;
|
||||
use super::parse_arguments;
|
||||
use super::run_resource_operation;
|
||||
|
||||
pub struct ListMcpResourcesHandler;
|
||||
pub struct ListMcpResourcesHandler {
|
||||
spec: ToolSpec,
|
||||
}
|
||||
|
||||
impl ToolExecutor<ToolInvocation> for ListMcpResourcesHandler {
|
||||
fn tool_name(&self) -> ToolName {
|
||||
@@ -23,7 +26,7 @@ impl ToolExecutor<ToolInvocation> for ListMcpResourcesHandler {
|
||||
}
|
||||
|
||||
fn spec(&self) -> ToolSpec {
|
||||
create_list_mcp_resources_tool()
|
||||
self.spec.clone()
|
||||
}
|
||||
|
||||
fn supports_parallel_tool_calls(&self) -> bool {
|
||||
@@ -39,6 +42,12 @@ impl ToolExecutor<ToolInvocation> for ListMcpResourcesHandler {
|
||||
}
|
||||
|
||||
impl ListMcpResourcesHandler {
|
||||
pub fn new(messages: Option<&ToolMessage>) -> Self {
|
||||
Self {
|
||||
spec: create_list_mcp_resources_tool(messages),
|
||||
}
|
||||
}
|
||||
|
||||
async fn handle_call(
|
||||
&self,
|
||||
invocation: ToolInvocation,
|
||||
|
||||
@@ -4,6 +4,7 @@ use crate::tools::context::ToolPayload;
|
||||
use crate::tools::handlers::mcp_resource_spec::create_read_mcp_resource_tool;
|
||||
use crate::tools::registry::CoreToolRuntime;
|
||||
use crate::tools::registry::ToolExecutor;
|
||||
use codex_protocol::openai_models::ToolMessage;
|
||||
use codex_protocol::protocol::McpInvocation;
|
||||
use codex_tools::ToolName;
|
||||
use codex_tools::ToolSpec;
|
||||
@@ -18,7 +19,9 @@ use super::parse_args;
|
||||
use super::parse_arguments;
|
||||
use super::run_resource_operation;
|
||||
|
||||
pub struct ReadMcpResourceHandler;
|
||||
pub struct ReadMcpResourceHandler {
|
||||
spec: ToolSpec,
|
||||
}
|
||||
|
||||
impl ToolExecutor<ToolInvocation> for ReadMcpResourceHandler {
|
||||
fn tool_name(&self) -> ToolName {
|
||||
@@ -26,7 +29,7 @@ impl ToolExecutor<ToolInvocation> for ReadMcpResourceHandler {
|
||||
}
|
||||
|
||||
fn spec(&self) -> ToolSpec {
|
||||
create_read_mcp_resource_tool()
|
||||
self.spec.clone()
|
||||
}
|
||||
|
||||
fn supports_parallel_tool_calls(&self) -> bool {
|
||||
@@ -42,6 +45,12 @@ impl ToolExecutor<ToolInvocation> for ReadMcpResourceHandler {
|
||||
}
|
||||
|
||||
impl ReadMcpResourceHandler {
|
||||
pub fn new(messages: Option<&ToolMessage>) -> Self {
|
||||
Self {
|
||||
spec: create_read_mcp_resource_tool(messages),
|
||||
}
|
||||
}
|
||||
|
||||
async fn handle_call(
|
||||
&self,
|
||||
invocation: ToolInvocation,
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
use codex_protocol::openai_models::ToolMessage;
|
||||
use codex_tools::JsonSchema;
|
||||
use codex_tools::ResponsesApiTool;
|
||||
use codex_tools::ToolSpec;
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
pub fn create_list_mcp_resources_tool() -> ToolSpec {
|
||||
pub fn create_list_mcp_resources_tool(messages: Option<&ToolMessage>) -> ToolSpec {
|
||||
let properties = BTreeMap::from([
|
||||
(
|
||||
"server".to_string(),
|
||||
@@ -20,17 +21,18 @@ pub fn create_list_mcp_resources_tool() -> ToolSpec {
|
||||
),
|
||||
]);
|
||||
|
||||
ToolSpec::Function(ResponsesApiTool {
|
||||
let tool = ResponsesApiTool {
|
||||
name: "list_mcp_resources".to_string(),
|
||||
description: "Lists resources provided by MCP servers. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Prefer resources over web search when possible.".to_string(),
|
||||
strict: false,
|
||||
defer_loading: None,
|
||||
parameters: JsonSchema::object(properties, /*required*/ None, Some(false.into())),
|
||||
output_schema: None,
|
||||
})
|
||||
};
|
||||
with_model_messages(tool, messages)
|
||||
}
|
||||
|
||||
pub fn create_list_mcp_resource_templates_tool() -> ToolSpec {
|
||||
pub fn create_list_mcp_resource_templates_tool(messages: Option<&ToolMessage>) -> ToolSpec {
|
||||
let properties = BTreeMap::from([
|
||||
(
|
||||
"server".to_string(),
|
||||
@@ -48,17 +50,18 @@ pub fn create_list_mcp_resource_templates_tool() -> ToolSpec {
|
||||
),
|
||||
]);
|
||||
|
||||
ToolSpec::Function(ResponsesApiTool {
|
||||
let tool = ResponsesApiTool {
|
||||
name: "list_mcp_resource_templates".to_string(),
|
||||
description: "Lists resource templates provided by MCP servers. Parameterized resource templates allow servers to share data that takes parameters and provides context to language models, such as files, database schemas, or application-specific information. Prefer resource templates over web search when possible.".to_string(),
|
||||
strict: false,
|
||||
defer_loading: None,
|
||||
parameters: JsonSchema::object(properties, /*required*/ None, Some(false.into())),
|
||||
output_schema: None,
|
||||
})
|
||||
};
|
||||
with_model_messages(tool, messages)
|
||||
}
|
||||
|
||||
pub fn create_read_mcp_resource_tool() -> ToolSpec {
|
||||
pub fn create_read_mcp_resource_tool(messages: Option<&ToolMessage>) -> ToolSpec {
|
||||
let properties = BTreeMap::from([
|
||||
(
|
||||
"server".to_string(),
|
||||
@@ -76,7 +79,7 @@ pub fn create_read_mcp_resource_tool() -> ToolSpec {
|
||||
),
|
||||
]);
|
||||
|
||||
ToolSpec::Function(ResponsesApiTool {
|
||||
let tool = ResponsesApiTool {
|
||||
name: "read_mcp_resource".to_string(),
|
||||
description:
|
||||
"Read a specific resource from an MCP server given the server name and resource URI."
|
||||
@@ -89,7 +92,27 @@ pub fn create_read_mcp_resource_tool() -> ToolSpec {
|
||||
Some(false.into()),
|
||||
),
|
||||
output_schema: None,
|
||||
})
|
||||
};
|
||||
with_model_messages(tool, messages)
|
||||
}
|
||||
|
||||
fn with_model_messages(mut tool: ResponsesApiTool, messages: Option<&ToolMessage>) -> ToolSpec {
|
||||
if let Some(messages) = messages {
|
||||
if let Some(description) = &messages.description {
|
||||
tool.description.clone_from(description);
|
||||
}
|
||||
if let Some(parameters) = &messages.parameters {
|
||||
match crate::tools::catalog_parameters::parse(parameters) {
|
||||
Ok(parameters) => tool.parameters = parameters,
|
||||
Err(reason) => tracing::warn!(
|
||||
tool = %tool.name,
|
||||
reason,
|
||||
"Invalid catalog tool parameters; using bundled parameters"
|
||||
),
|
||||
}
|
||||
}
|
||||
}
|
||||
ToolSpec::Function(tool)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
|
||||
@@ -6,7 +6,7 @@ use std::collections::BTreeMap;
|
||||
#[test]
|
||||
fn list_mcp_resources_tool_matches_expected_spec() {
|
||||
assert_eq!(
|
||||
create_list_mcp_resources_tool(),
|
||||
create_list_mcp_resources_tool(/*messages*/ None),
|
||||
ToolSpec::Function(ResponsesApiTool {
|
||||
name: "list_mcp_resources".to_string(),
|
||||
description: "Lists resources provided by MCP servers. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Prefer resources over web search when possible.".to_string(),
|
||||
@@ -36,7 +36,7 @@ fn list_mcp_resources_tool_matches_expected_spec() {
|
||||
#[test]
|
||||
fn list_mcp_resource_templates_tool_matches_expected_spec() {
|
||||
assert_eq!(
|
||||
create_list_mcp_resource_templates_tool(),
|
||||
create_list_mcp_resource_templates_tool(/*messages*/ None),
|
||||
ToolSpec::Function(ResponsesApiTool {
|
||||
name: "list_mcp_resource_templates".to_string(),
|
||||
description: "Lists resource templates provided by MCP servers. Parameterized resource templates allow servers to share data that takes parameters and provides context to language models, such as files, database schemas, or application-specific information. Prefer resource templates over web search when possible.".to_string(),
|
||||
@@ -66,7 +66,7 @@ fn list_mcp_resource_templates_tool_matches_expected_spec() {
|
||||
#[test]
|
||||
fn read_mcp_resource_tool_matches_expected_spec() {
|
||||
assert_eq!(
|
||||
create_read_mcp_resource_tool(),
|
||||
create_read_mcp_resource_tool(/*messages*/ None),
|
||||
ToolSpec::Function(ResponsesApiTool {
|
||||
name: "read_mcp_resource".to_string(),
|
||||
description:
|
||||
@@ -94,3 +94,42 @@ fn read_mcp_resource_tool_matches_expected_spec() {
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn catalog_fields_override_independently_and_invalid_parameters_fall_back() {
|
||||
let parameters = r#"{"type":"object","properties":{"server":{"type":"string","description":"Catalog server guidance."}},"additionalProperties":false}"#;
|
||||
for create_tool in [
|
||||
create_list_mcp_resources_tool,
|
||||
create_list_mcp_resource_templates_tool,
|
||||
create_read_mcp_resource_tool,
|
||||
] {
|
||||
for (description, schema, valid_schema) in [
|
||||
(None, None, false),
|
||||
(Some(""), None, false),
|
||||
(None, Some(parameters), true),
|
||||
(
|
||||
Some(" Catalog {{literal}} guidance.\n"),
|
||||
Some(parameters),
|
||||
true,
|
||||
),
|
||||
(Some("Catalog guidance."), Some("invalid JSON"), false),
|
||||
(None, Some(r#"{"type":"string"}"#), false),
|
||||
] {
|
||||
let messages = ToolMessage {
|
||||
description: description.map(str::to_owned),
|
||||
parameters: schema.map(str::to_owned),
|
||||
};
|
||||
let mut expected = create_tool(/*messages*/ None);
|
||||
let ToolSpec::Function(tool) = &mut expected else {
|
||||
panic!("expected a function tool");
|
||||
};
|
||||
if let Some(description) = description {
|
||||
tool.description = description.to_owned();
|
||||
}
|
||||
if valid_schema {
|
||||
tool.parameters = serde_json::from_str(parameters).unwrap();
|
||||
}
|
||||
assert_eq!(create_tool(Some(&messages)), expected);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1123,9 +1123,16 @@ fn unified_exec_should_include_shell_parameter(
|
||||
#[instrument(level = "trace", skip_all)]
|
||||
fn add_mcp_resource_tools(context: &CoreToolPlanContext<'_>, registry: &mut ToolRegistry) {
|
||||
if context.mcp.has_servers() {
|
||||
registry.add(ListMcpResourcesHandler);
|
||||
registry.add(ListMcpResourceTemplatesHandler);
|
||||
registry.add(ReadMcpResourceHandler);
|
||||
let messages = ResolvedModelMessages::from_model(context.model_info).mcp_resources();
|
||||
registry.add(ListMcpResourcesHandler::new(
|
||||
messages.and_then(|messages| messages.list_mcp_resources.as_ref()),
|
||||
));
|
||||
registry.add(ListMcpResourceTemplatesHandler::new(
|
||||
messages.and_then(|messages| messages.list_mcp_resource_templates.as_ref()),
|
||||
));
|
||||
registry.add(ReadMcpResourceHandler::new(
|
||||
messages.and_then(|messages| messages.read_mcp_resource.as_ref()),
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user