fix: includes workspace mcp in legacy mcp (#2516)

* legacy mcp json also sources from workspace

* updates doc

Author: dingfeli

crates/chat-cli/src/cli/agent/legacy/mod.rs

@@ -77,7 +77,7 @@ pub async fn migrate(os: &mut Os, force: bool) -> eyre::Result<Option<Vec<Agent>
     };
 
     let mcp_servers = {
-        let config_path = directories::chat_legacy_mcp_config(os)?;
+        let config_path = directories::chat_legacy_global_mcp_config(os)?;
         if os.fs.exists(&config_path) {
             match McpServerConfig::load_from_file(os, config_path).await {
                 Ok(mut config) => {

crates/chat-cli/src/cli/agent/mod.rs

@@ -208,14 +208,14 @@ impl Agent {
     /// This function mutates the agent to a state that is usable for runtime.
     /// Practically this means to convert some of the fields value to their usable counterpart.
     /// For example, converting the mcp array to actual mcp config and populate the agent file path.
-    fn thaw(&mut self, path: &Path, global_mcp_config: Option<&McpServerConfig>) -> Result<(), AgentConfigError> {
+    fn thaw(&mut self, path: &Path, legacy_mcp_config: Option<&McpServerConfig>) -> Result<(), AgentConfigError> {
         let Self { mcp_servers, .. } = self;
 
         self.path = Some(path.to_path_buf());
 
-        if let (true, Some(global_mcp_config)) = (self.use_legacy_mcp_json, global_mcp_config) {
+        if let (true, Some(legacy_mcp_config)) = (self.use_legacy_mcp_json, legacy_mcp_config) {
             let mut stderr = std::io::stderr();
-            for (name, legacy_server) in &global_mcp_config.mcp_servers {
+            for (name, legacy_server) in &legacy_mcp_config.mcp_servers {
                 if mcp_servers.mcp_servers.contains_key(name) {
                     let _ = queue!(
                         stderr,
@@ -269,16 +269,13 @@ impl Agent {
             Ok(config_path) => {
                 let content = os.fs.read(&config_path).await?;
                 let mut agent = serde_json::from_slice::<Agent>(&content)?;
-
-                let global_mcp_path = directories::chat_legacy_mcp_config(os)?;
-                let global_mcp_config = match McpServerConfig::load_from_file(os, global_mcp_path).await {
-                    Ok(config) => Some(config),
-                    Err(e) => {
-                        tracing::error!("Error loading global mcp json path: {e}.");
-                        None
-                    },
+                let legacy_mcp_config = if agent.use_legacy_mcp_json {
+                    load_legacy_mcp_config(os).await.unwrap_or(None)
+                } else {
+                    None
                 };
-                agent.thaw(&config_path, global_mcp_config.as_ref())?;
+
+                agent.thaw(&config_path, legacy_mcp_config.as_ref())?;
                 Ok((agent, config_path))
             },
             _ => bail!("Agent {agent_name} does not exist"),
@@ -288,27 +285,22 @@ impl Agent {
     pub async fn load(
         os: &Os,
         agent_path: impl AsRef<Path>,
-        global_mcp_config: &mut Option<McpServerConfig>,
+        legacy_mcp_config: &mut Option<McpServerConfig>,
     ) -> Result<Agent, AgentConfigError> {
         let content = os.fs.read(&agent_path).await?;
         let mut agent = serde_json::from_slice::<Agent>(&content).map_err(|e| AgentConfigError::InvalidJson {
             error: e,
             path: agent_path.as_ref().to_path_buf(),
         })?;
 
-        if agent.use_legacy_mcp_json && global_mcp_config.is_none() {
-            let global_mcp_path = directories::chat_legacy_mcp_config(os)?;
-            let legacy_mcp_config = if global_mcp_path.exists() {
-                McpServerConfig::load_from_file(os, global_mcp_path)
-                    .await
-                    .map_err(AgentConfigError::BadLegacyMcpConfig)?
-            } else {
-                McpServerConfig::default()
-            };
-            global_mcp_config.replace(legacy_mcp_config);
+        if agent.use_legacy_mcp_json && legacy_mcp_config.is_none() {
+            let config = load_legacy_mcp_config(os).await.unwrap_or_default();
+            if let Some(config) = config {
+                legacy_mcp_config.replace(config);
+            }
         }
 
-        agent.thaw(agent_path.as_ref(), global_mcp_config.as_ref())?;
+        agent.thaw(agent_path.as_ref(), legacy_mcp_config.as_ref())?;
         Ok(agent)
     }
 }
@@ -611,7 +603,7 @@ impl Agents {
                 let mut agent = Agent::default();
                 'load_legacy_mcp_json: {
                     if global_mcp_config.is_none() {
-                        let Ok(global_mcp_path) = directories::chat_legacy_mcp_config(os) else {
+                        let Ok(global_mcp_path) = directories::chat_legacy_global_mcp_config(os) else {
                             tracing::error!("Error obtaining legacy mcp json path. Skipping");
                             break 'load_legacy_mcp_json;
                         };
@@ -769,6 +761,42 @@ async fn load_agents_from_entries(
     res
 }
 
+/// Loads legacy mcp config by combining workspace and global config.
+/// In case of a server naming conflict, the workspace config is prioritized.
+async fn load_legacy_mcp_config(os: &Os) -> eyre::Result<Option<McpServerConfig>> {
+    let global_mcp_path = directories::chat_legacy_global_mcp_config(os)?;
+    let global_mcp_config = match McpServerConfig::load_from_file(os, global_mcp_path).await {
+        Ok(config) => Some(config),
+        Err(e) => {
+            tracing::error!("Error loading global mcp json path: {e}.");
+            None
+        },
+    };
+
+    let workspace_mcp_path = directories::chat_legacy_workspace_mcp_config(os)?;
+    let workspace_mcp_config = match McpServerConfig::load_from_file(os, workspace_mcp_path).await {
+        Ok(config) => Some(config),
+        Err(e) => {
+            tracing::error!("Error loading global mcp json path: {e}.");
+            None
+        },
+    };
+
+    Ok(match (workspace_mcp_config, global_mcp_config) {
+        (Some(mut wc), Some(gc)) => {
+            for (server_name, config) in gc.mcp_servers {
+                // We prioritize what is in the workspace
+                wc.mcp_servers.entry(server_name).or_insert(config);
+            }
+
+            Some(wc)
+        },
+        (None, Some(gc)) => Some(gc),
+        (Some(wc), None) => Some(wc),
+        _ => None,
+    })
+}
+
 fn default_schema() -> String {
     "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json".into()
 }

crates/chat-cli/src/cli/mcp.rs

@@ -90,6 +90,9 @@ pub struct AddArgs {
     /// Name for the server
     #[arg(long)]
     pub name: String,
+    /// Scope. This parameter is only meaningful in the absence of agent name.
+    #[arg(long)]
+    pub scope: Option<Scope>,
     /// The command used to launch the server
     #[arg(long)]
     pub command: String,
@@ -145,14 +148,17 @@ impl AddArgs {
                 writeln!(output, "✓ Added MCP server '{}' to agent {}\n", self.name, agent_name)?;
             },
             None => {
-                let global_config_path = directories::chat_legacy_mcp_config(os)?;
-                let mut mcp_servers = McpServerConfig::load_from_file(os, &global_config_path).await?;
+                let legacy_mcp_config_path = match self.scope {
+                    Some(Scope::Workspace) => directories::chat_legacy_workspace_mcp_config(os)?,
+                    _ => directories::chat_legacy_global_mcp_config(os)?,
+                };
+                let mut mcp_servers = McpServerConfig::load_from_file(os, &legacy_mcp_config_path).await?;
 
                 if mcp_servers.mcp_servers.contains_key(&self.name) && !self.force {
                     bail!(
                         "\nMCP server '{}' already exists in global config (path {}). Use --force to overwrite.",
                         self.name,
-                        &global_config_path.display(),
+                        &legacy_mcp_config_path.display(),
                     );
                 }
 
@@ -166,12 +172,12 @@ impl AddArgs {
                 }))?;
 
                 mcp_servers.mcp_servers.insert(self.name.clone(), tool);
-                mcp_servers.save_to_file(os, &global_config_path).await?;
+                mcp_servers.save_to_file(os, &legacy_mcp_config_path).await?;
                 writeln!(
                     output,
                     "✓ Added MCP server '{}' to global config in {}\n",
                     self.name,
-                    global_config_path.display()
+                    legacy_mcp_config_path.display()
                 )?;
             },
         };
@@ -184,6 +190,9 @@ impl AddArgs {
 pub struct RemoveArgs {
     #[arg(long)]
     pub name: String,
+    /// Scope. This parameter is only meaningful in the absence of agent name.
+    #[arg(long)]
+    pub scope: Option<Scope>,
     #[arg(long, value_enum)]
     pub agent: Option<String>,
 }
@@ -221,25 +230,28 @@ impl RemoveArgs {
                 }
             },
             None => {
-                let global_config_path = directories::chat_legacy_mcp_config(os)?;
-                let mut config = McpServerConfig::load_from_file(os, &global_config_path).await?;
+                let legacy_mcp_config_path = match self.scope {
+                    Some(Scope::Workspace) => directories::chat_legacy_workspace_mcp_config(os)?,
+                    _ => directories::chat_legacy_global_mcp_config(os)?,
+                };
+                let mut config = McpServerConfig::load_from_file(os, &legacy_mcp_config_path).await?;
 
                 match config.mcp_servers.remove(&self.name) {
                     Some(_) => {
-                        config.save_to_file(os, &global_config_path).await?;
+                        config.save_to_file(os, &legacy_mcp_config_path).await?;
                         writeln!(
                             output,
                             "\n✓ Removed MCP server '{}' from global config (path {})\n",
                             self.name,
-                            &global_config_path.display(),
+                            &legacy_mcp_config_path.display(),
                         )?;
                     },
                     None => {
                         writeln!(
                             output,
                             "\nNo MCP server named '{}' found in global config (path {})\n",
                             self.name,
-                            &global_config_path.display(),
+                            &legacy_mcp_config_path.display(),
                         )?;
                     },
                 }
@@ -540,6 +552,7 @@ mod tests {
         // 1. add
         AddArgs {
             name: "local".into(),
+            scope: None,
             command: "echo hi".into(),
             args: vec![
                 "awslabs.eks-mcp-server".to_string(),
@@ -564,6 +577,7 @@ mod tests {
         // 2. remove
         RemoveArgs {
             name: "local".into(),
+            scope: None,
             agent: None,
         }
         .execute(&os, &mut vec![])
@@ -591,6 +605,7 @@ mod tests {
             ],
             RootSubcommand::Mcp(McpSubcommand::Add(AddArgs {
                 name: "test_server".to_string(),
+                scope: None,
                 command: "test_command".to_string(),
                 args: vec![
                     "awslabs.eks-mcp-server".to_string(),
@@ -619,6 +634,7 @@ mod tests {
             ["mcp", "remove", "--name", "old"],
             RootSubcommand::Mcp(McpSubcommand::Remove(RemoveArgs {
                 name: "old".into(),
+                scope: None,
                 agent: None,
             }))
         );

crates/chat-cli/src/util/directories.rs

@@ -144,10 +144,16 @@ pub fn example_agent_config(os: &Os) -> Result<PathBuf> {
 }
 
 /// Legacy global MCP server config path
-pub fn chat_legacy_mcp_config(os: &Os) -> Result<PathBuf> {
+pub fn chat_legacy_global_mcp_config(os: &Os) -> Result<PathBuf> {
     Ok(home_dir(os)?.join(".aws").join("amazonq").join("mcp.json"))
 }
 
+/// Legacy workspace MCP server config path
+pub fn chat_legacy_workspace_mcp_config(os: &Os) -> Result<PathBuf> {
+    let cwd = os.env.current_dir()?;
+    Ok(cwd.join(".amazonq").join("mcp.json"))
+}
+
 /// The directory to the directory containing global agents
 pub fn chat_global_agent_path(os: &Os) -> Result<PathBuf> {
     Ok(home_dir(os)?.join(GLOBAL_AGENT_DIR_RELATIVE_TO_HOME))

docs/agent-format.md

@@ -225,7 +225,7 @@ Available hook triggers:
 
 ## UseLegacyMcpJson Field
 
-The `useLegacyMcpJson` field determines whether to include MCP servers defined in the legacy global MCP configuration file (`~/.aws/amazonq/mcp.json`).
+The `useLegacyMcpJson` field determines whether to include MCP servers defined in the legacy MCP configuration files (`~/.aws/amazonq/mcp.json` for global and `cwd/.amazonq/mcp.json` for workspace).
 
 ```json
 {