Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(install-mcp): --flavor pins the schema dialect for any client

Abhishek Sharma4f0401b21443
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f82367a3..85c23588 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- `install-mcp --flavor <moonshot|bedrock|gemini>` pins the tool-schema dialect
+ in the URL written into a client's config. The installer already picks one for
+ the clients whose upstream is fixed — Kimi Code is always Moonshot, Kiro always
+ Bedrock — but a client that fronts several models cannot be pinned by its name
+ alone, and there was no installer path to `?flavor=gemini` for any of them. A
+ Command Code or OpenCode install routed to Vertex needed the marker added by
+ hand or every model call 400'd at `tools/list`; the same client on a non-Google
+ model does not, which is why this is an explicit choice rather than another
+ per-client default. `vertex` is accepted as an alias. `uninstall` now matches
+ every marker on every client, so an entry pinned this way is still removed
+ (#735).
+
## [2.2.1] - 2026-09-12
### Fixed
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index bc442c75..56a8e543 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -1624,6 +1624,41 @@ pub struct FinalizeSessionArgs {
pub json: bool,
}
+/// Tool-schema dialect to pin into the installed MCP URL, as the server's
+/// `?flavor=` marker (docs/mcp-install.md → Schema dialects for strict
+/// upstreams). `install-mcp` already picks one for the clients whose upstream
+/// is fixed — Kimi Code is always Moonshot, Kiro is always Bedrock — but a
+/// client that fronts several models cannot be pinned by its name alone. A
+/// Command Code or OpenCode install routed to Vertex needs `gemini`; the same
+/// client on another model does not, and forcing it there would narrow the
+/// advertised schema for no reason. So this stays an explicit operator choice.
+///
+/// Every variant is at least as permissive as each client's built-in default,
+/// so passing one can only relax the advertised schema further, never tighten
+/// it below what the client already needs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
+pub enum SchemaFlavor {
+ /// Drop root-level `anyOf`/`oneOf`/`allOf` (Moonshot).
+ Moonshot,
+ /// Same rewrite, for Bedrock-backed clients.
+ Bedrock,
+ /// The above, plus nullable unions collapsed to a single `type` plus
+ /// `nullable: true` (Gemini / Vertex).
+ #[value(alias = "vertex")]
+ Gemini,
+}
+
+impl SchemaFlavor {
+ /// The `flavor=` query value the server matches in `restricted_schema_flavor`.
+ pub fn marker(self) -> &'static str {
+ match self {
+ Self::Moonshot => "moonshot",
+ Self::Bedrock => "bedrock",
+ Self::Gemini => "gemini",
+ }
+ }
+}
+
/// MCP client to render configuration for. Includes both the
/// hook-capable agents (Claude Code / Codex / OpenCode — same MCP
/// surface, also covered by `install-hooks`) and the MCP-only
@@ -2202,6 +2237,13 @@ pub struct InstallMcpArgs {
/// `[auto_scope] mode = "per_session"` for concurrent Claude Code sessions.
#[arg(long)]
pub session_aware: bool,
+ /// Pin the tool-schema dialect in the installed MCP URL, for a client
+ /// whose upstream 400s on the schemas ai-memory advertises by default.
+ /// Needed when the client fronts several models and its name alone does
+ /// not say which — a Command Code or OpenCode install routed to Vertex
+ /// wants `gemini`. Kimi Code and Kiro already get theirs; this overrides.
+ #[arg(long, value_enum)]
+ pub flavor: Option<SchemaFlavor>,
}
/// Arguments for the internal Claude Code session-aware MCP bridge.
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index 45e18b9a..d954f53f 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -21,7 +21,7 @@ use jsonc_parser::ParseOptions;
use jsonc_parser::cst::{CstInputValue, CstRootNode};
use serde_json::json;
-use crate::cli::{InstallMcpArgs, McpClient};
+use crate::cli::{InstallMcpArgs, McpClient, SchemaFlavor};
use crate::commands::apply_shared::{ApplyOutcome, apply_atomic, mutate_json, mutate_toml};
use crate::commands::path_util::{claude_config_dir, home_dir};
use crate::commands::render_shared::bearer_header_value;
@@ -665,12 +665,42 @@ fn flavored_mcp_url(server_url: &str, flavor: &str) -> String {
format!("{url}{separator}{marker}")
}
-pub(crate) fn moonshot_flavored_mcp_url(server_url: &str) -> String {
- flavored_mcp_url(server_url, "moonshot")
+/// Every marker `install-mcp` can write. `uninstall` walks this so an entry
+/// installed with `--flavor` is still matched by URL; adding a flavor without
+/// adding it here would leave those entries behind.
+pub(crate) const FLAVOR_MARKERS: [&str; 3] = ["moonshot", "bedrock", "gemini"];
+
+/// [`flavored_mcp_url`] for a marker already in hand — what `uninstall` needs
+/// to rebuild each candidate URL form without knowing the flavor type.
+pub(crate) fn flavored_mcp_url_for_marker(server_url: &str, marker: &str) -> String {
+ flavored_mcp_url(server_url, marker)
}
-pub(crate) fn bedrock_flavored_mcp_url(server_url: &str) -> String {
- flavored_mcp_url(server_url, "bedrock")
+/// The dialect a client always needs, from its name alone. Only clients with a
+/// single fixed upstream appear here — Kimi Code is Moonshot, Kiro is Bedrock.
+/// A client that fronts several models has no answer here and needs `--flavor`.
+fn client_default_flavor(client: McpClient) -> Option<&'static str> {
+ match client {
+ McpClient::KimiCode => Some("moonshot"),
+ McpClient::KiroCli => Some("bedrock"),
+ _ => None,
+ }
+}
+
+/// The URL to write into the client config: the endpoint plus whichever
+/// `?flavor=` marker applies. An explicit `--flavor` wins over the client's
+/// built-in default, which is safe in one direction only by construction —
+/// every flavor is at least as permissive as any default, so an override can
+/// relax the advertised schema but never tighten it past what the client needs.
+pub(crate) fn flavored_url_for(args: &InstallMcpArgs, server_url: &str) -> String {
+ match args
+ .flavor
+ .map(SchemaFlavor::marker)
+ .or_else(|| client_default_flavor(args.client))
+ {
+ Some(marker) => flavored_mcp_url(server_url, marker),
+ None => server_url.to_string(),
+ }
}
/// JSON entry shape used by Claude Code, Claude Desktop, Cursor, and
@@ -680,7 +710,12 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
let bearer = bearer_header_value(args.auth_token.as_deref());
// `run()` resolves the URL before dispatch; the fallback only fires for
// direct callers (tests, uninstall re-render) that skip that step.
- let server_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
+ let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
+ // The flavor marker is a `tools/list` concern, so it belongs on the URL a
+ // client fetches schemas from. `mcp-bridge` is not that: it is our own
+ // process, and it re-derives its endpoint, so it keeps the bare URL.
+ let flavored = flavored_url_for(args, base_url);
+ let server_url = flavored.as_str();
let mut entry = serde_json::Map::new();
match args.client {
McpClient::ClaudeCode => {
@@ -689,7 +724,7 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
entry.insert("command".into(), json!("ai-memory"));
entry.insert(
"args".into(),
- json!(["mcp-bridge", "--server-url", server_url]),
+ json!(["mcp-bridge", "--server-url", base_url]),
);
if let Some(token) = &args.auth_token {
entry.insert("env".into(), json!({"AI_MEMORY_AUTH_TOKEN": token}));
@@ -753,13 +788,13 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
// Kimi Code treats an entry with `url` and no `transport`
// field as streamable-HTTP; `transport` is only for legacy
// SSE endpoints.
- entry.insert("url".into(), json!(moonshot_flavored_mcp_url(server_url)));
+ entry.insert("url".into(), json!(server_url));
if let Some(b) = &bearer {
entry.insert("headers".into(), json!({"Authorization": b}));
}
}
McpClient::KiroCli => {
- entry.insert("url".into(), json!(bedrock_flavored_mcp_url(server_url)));
+ entry.insert("url".into(), json!(server_url));
if let Some(b) = &bearer {
entry.insert("headers".into(), json!({"Authorization": b}));
}
@@ -1442,6 +1477,7 @@ mod tests {
apply: false,
config_file: None,
session_aware: false,
+ flavor: None,
}
}
@@ -1454,6 +1490,7 @@ mod tests {
apply: false,
config_file: None,
session_aware: false,
+ flavor: None,
}
}
@@ -2339,6 +2376,93 @@ mod tests {
/// Pin the append rules: `?` on a bare endpoint, `&` with an existing
/// query, never duplicate an existing marker.
+ #[test]
+ fn an_explicit_flavor_pins_a_client_the_installer_cannot_infer() {
+ // The issue-735 shape: Command Code fronts several models, so its name
+ // says nothing about the upstream. Routed to Vertex it needs the Gemini
+ // dialect, and before --flavor there was no installer path to it.
+ let mut args = args_for(McpClient::CommandCode);
+ args.server_url = Some("https://memory.example/mcp".into());
+ args.flavor = Some(SchemaFlavor::Gemini);
+
+ let entry = build_mcp_entry(&args).unwrap();
+
+ assert_eq!(
+ entry["url"].as_str().unwrap(),
+ "https://memory.example/mcp?flavor=gemini"
+ );
+ }
+
+ #[test]
+ fn a_client_without_a_fixed_upstream_stays_unflavored_by_default() {
+ let mut args = args_for(McpClient::CommandCode);
+ args.server_url = Some("https://memory.example/mcp".into());
+
+ let entry = build_mcp_entry(&args).unwrap();
+
+ assert_eq!(entry["url"].as_str().unwrap(), "https://memory.example/mcp");
+ }
+
+ #[test]
+ fn an_explicit_flavor_replaces_the_clients_built_in_default() {
+ // Kimi Code defaults to moonshot. Asking for gemini must not stack a
+ // second marker: the server maxes over every pair, so both would work,
+ // but the installed URL would carry a dialect the operator did not pick.
+ let mut args = args_for(McpClient::KimiCode);
+ args.server_url = Some("https://memory.example/mcp".into());
+ args.flavor = Some(SchemaFlavor::Gemini);
+
+ let entry = build_mcp_entry(&args).unwrap();
+
+ assert_eq!(
+ entry["url"].as_str().unwrap(),
+ "https://memory.example/mcp?flavor=gemini"
+ );
+ }
+
+ #[test]
+ fn the_session_aware_bridge_keeps_the_unflavored_url() {
+ // `mcp-bridge` is our own process, not a schema consumer. Handing it a
+ // flavored URL would push the marker through to the server on every
+ // bridged request, narrowing schemas for a client that never asked.
+ let mut args = args_for(McpClient::ClaudeCode);
+ args.server_url = Some("https://memory.example/mcp".into());
+ args.session_aware = true;
+ args.flavor = Some(SchemaFlavor::Gemini);
+
+ let entry = build_mcp_entry(&args).unwrap();
+
+ let bridge_args: Vec<&str> = entry["args"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|a| a.as_str().unwrap())
+ .collect();
+ assert_eq!(
+ bridge_args,
+ vec!["mcp-bridge", "--server-url", "https://memory.example/mcp"]
+ );
+ }
+
+ #[test]
+ fn every_flavor_marker_is_one_the_server_recognizes() {
+ // The server matches `flavor=` values exactly. A marker the CLI can
+ // write but the server does not match would install a URL that silently
+ // serves upstream schemas — the exact failure --flavor exists to avoid.
+ for flavor in [
+ SchemaFlavor::Moonshot,
+ SchemaFlavor::Bedrock,
+ SchemaFlavor::Gemini,
+ ] {
+ assert!(
+ FLAVOR_MARKERS.contains(&flavor.marker()),
+ "{:?} writes marker {:?}, which uninstall does not know",
+ flavor,
+ flavor.marker()
+ );
+ }
+ }
+
#[test]
fn moonshot_flavored_mcp_url_appends_marker_idempotently() {
for (input, expected) in [
@@ -2364,22 +2488,26 @@ mod tests {
"http://homelab:49374/mcp?note=flavor=moonshot&flavor=moonshot",
),
] {
- assert_eq!(moonshot_flavored_mcp_url(input), expected, "input: {input}");
+ assert_eq!(
+ flavored_mcp_url_for_marker(input, "moonshot"),
+ expected,
+ "input: {input}"
+ );
}
}
#[test]
fn bedrock_flavored_mcp_url_appends_marker_idempotently() {
assert_eq!(
- bedrock_flavored_mcp_url("https://memory.example/mcp"),
+ flavored_mcp_url_for_marker("https://memory.example/mcp", "bedrock"),
"https://memory.example/mcp?flavor=bedrock"
);
assert_eq!(
- bedrock_flavored_mcp_url("https://memory.example/mcp?token=x"),
+ flavored_mcp_url_for_marker("https://memory.example/mcp?token=x", "bedrock"),
"https://memory.example/mcp?token=x&flavor=bedrock"
);
assert_eq!(
- bedrock_flavored_mcp_url("https://memory.example/mcp?flavor=bedrock"),
+ flavored_mcp_url_for_marker("https://memory.example/mcp?flavor=bedrock", "bedrock"),
"https://memory.example/mcp?flavor=bedrock"
);
}
diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rs
index a178faf9..34e12281 100644
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@ -1159,16 +1159,14 @@ fn mcp_entry_is_ours(key: &str, entry: &serde_json::Value, name: Option<&str>, u
/// for clients whose installer appends a schema flavor, the form
/// `install-mcp` actually writes (`--mcp-url` keeps the unflavored default).
/// Every other client keeps exact-match semantics.
-fn mcp_url_candidates(client: McpClient, url: &str) -> Vec<String> {
+fn mcp_url_candidates(_client: McpClient, url: &str) -> Vec<String> {
let mut candidates = vec![url.to_string()];
- if matches!(client, McpClient::KimiCode) {
- let flavored = install_mcp::moonshot_flavored_mcp_url(url);
- if !candidates.contains(&flavored) {
- candidates.push(flavored);
- }
- }
- if matches!(client, McpClient::KiroCli) {
- let flavored = install_mcp::bedrock_flavored_mcp_url(url);
+ // Every marker, for every client: `install-mcp --flavor` can write any of
+ // them into any client's config, so keying this off the client's built-in
+ // default would strand the entries an operator pinned by hand. Candidates
+ // that do not appear in the file simply match nothing.
+ for marker in install_mcp::FLAVOR_MARKERS {
+ let flavored = install_mcp::flavored_mcp_url_for_marker(url, marker);
if !candidates.contains(&flavored) {
candidates.push(flavored);
}
@@ -2204,31 +2202,48 @@ command = "'/usr/local/bin/ai-memory' hook --event stop --agent kimi-code --serv
}
#[test]
- fn mcp_url_candidates_adds_client_schema_flavors() {
+ fn mcp_url_candidates_covers_every_installable_flavor() {
+ // Was keyed off the client's built-in default. `install-mcp --flavor`
+ // can now write any marker into any client's config, so candidates are
+ // keyed off what the installer can write instead — otherwise an entry
+ // an operator pinned by hand survives `uninstall`.
assert_eq!(
mcp_url_candidates(McpClient::KimiCode, "http://127.0.0.1:49374/mcp"),
vec![
"http://127.0.0.1:49374/mcp".to_string(),
- "http://127.0.0.1:49374/mcp?flavor=moonshot".to_string()
+ "http://127.0.0.1:49374/mcp?flavor=moonshot".to_string(),
+ "http://127.0.0.1:49374/mcp?flavor=bedrock".to_string(),
+ "http://127.0.0.1:49374/mcp?flavor=gemini".to_string(),
]
);
+ // An already-flavored URL is not duplicated into the list.
assert_eq!(
mcp_url_candidates(
McpClient::KimiCode,
"http://127.0.0.1:49374/mcp?flavor=moonshot"
- ),
- vec!["http://127.0.0.1:49374/mcp?flavor=moonshot".to_string()]
+ )[0],
+ "http://127.0.0.1:49374/mcp?flavor=moonshot".to_string()
);
assert_eq!(
- mcp_url_candidates(McpClient::KiroCli, "https://memory.example/mcp"),
- vec![
- "https://memory.example/mcp".to_string(),
- "https://memory.example/mcp?flavor=bedrock".to_string()
- ]
+ mcp_url_candidates(
+ McpClient::KimiCode,
+ "http://127.0.0.1:49374/mcp?flavor=moonshot"
+ )
+ .iter()
+ .filter(|c| c.ends_with("flavor=moonshot"))
+ .count(),
+ 1
);
- assert_eq!(
- mcp_url_candidates(McpClient::Cursor, "http://127.0.0.1:49374/mcp"),
- vec!["http://127.0.0.1:49374/mcp".to_string()]
+ // The case the broadening exists for: Command Code has no default
+ // flavor, but an operator on a Vertex-backed model pins one.
+ assert!(
+ mcp_url_candidates(McpClient::CommandCode, "https://memory.example/mcp")
+ .contains(&"https://memory.example/mcp?flavor=gemini".to_string())
+ );
+ // Kiro's own default is still matched.
+ assert!(
+ mcp_url_candidates(McpClient::KiroCli, "https://memory.example/mcp")
+ .contains(&"https://memory.example/mcp?flavor=bedrock".to_string())
);
}
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index fab39739..a1fc114a 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -1237,6 +1237,21 @@ validation is identical in every dialect — only the advertised schema changes.
| `?flavor=bedrock` | `strip_root_combinators` | Same as above | Kiro CLI (Bedrock); appended by `install-mcp` |
| `?flavor=gemini` (alias `vertex`) | `gemini_safe_schemas` | The above, plus nullable unions collapsed to a single `type` + `nullable: true` | Clients that forward schemas verbatim to Gemini/Vertex, e.g. OpenCode on a Vertex model |
+`install-mcp` appends the first two itself for the clients whose upstream is
+fixed. For any other client, pass the dialect explicitly:
+
+```bash
+ai-memory install-mcp --client command-code --flavor gemini --apply
+```
+
+This is an operator choice rather than another per-client default because a
+client like Command Code or OpenCode fronts several models: it needs the Gemini
+dialect only when routed to Vertex, and pinning it there for everyone would
+narrow the advertised schema for models that never had the problem. `--flavor`
+overrides a client's built-in default rather than stacking a second marker, and
+`uninstall` matches every marker on every client, so an entry pinned this way is
+still removed.
+
The Gemini dialect exists because `schemars` renders every optional tool
argument as a nullable union: