[0.3] Add localization/theming

[asklar]

Proposal: Enhance MCPB Manifest Schema for Localization and Theming

Background

The current MCPB manifest schema lacks:

• Scalable localization for user-facing fields.
• Structured support for theme-aware and size-aware icons.
• Mechanisms to avoid manifest bloat when supporting many languages.

Goals

1. Enable multi-language support without inflating the manifest.
2. Support light/dark theme and multiple icon sizes.
3. Maintain backward compatibility and cross-platform flexibility.

---

Fields to Localize

Localizable fields (if present in the manifest):

• display_name
• description
• long_description
• author.name (if surfaced in UI)
• license (if surfaced verbatim in UI; otherwise typically a SPDX identifier and not localized)
• keywords (when rendered as user-visible labels; if used solely for search indexing, localization is optional)

Explicitly NOT in scope (either not user-facing, structured, or out of initial phase):

• Any newly introduced fields (e.g., icons or future classification constructs) unless and until the base spec adopts them and they are recognized as user-visible text.

---

Proposed Changes

1. Localization

Introduce a localization object with per-locale resource discovery:

"localization": {
  "resources": "resources/${locale}.json",
  "default_locale": "en-US"
}

Locale Format:

• Must follow https://www.rfc-editor.org/rfc/bcp/bcp47.txt (e.g., en-US, fr-FR, zh-Hans).
• Case-insensitive matching recommended.

Important:

• The default locale does not require its own resources file because its content is already in the main manifest fields.
• If a field is missing in the locale resources file, the value from the default locale in the main manifest must be used.
• The client resolves the path of the file pointed at by resources relative to the server package's install path (i.e. its __dirname).

---

Main Manifest

{
  "manifest_version": "0.3",
  "name": "sample-mcp-server",
  "display_name": "Sample MCP Server",
  "description": "Provides advanced features",
  "long_description": "Extended description for UI",
  "keywords": ["mcp", "bundle"],
  "localization": {
    "resources": "resources/${locale}.json",
    "default_locale": "en-US"
  },
  "icons": [
    {
      "src": "assets/icons/icon-16-light.png",
      "sizes": "16x16",
      "theme": "light"
    },
    {
      "src": "assets/icons/icon-16-dark.png",
      "sizes": "16x16",
      "theme": "dark"
    }
  ]
}

---

Sample Locale File (fr-FR.json)

{
  "display_name": "Serveur MCP Exemple",
  "description": "Fournit des fonctionnalités avancées",
  "long_description": "Description détaillée pour les utilisateurs",
  "keywords": ["mcp", "bundle"]
}

---

Future Expansion

We can allow explicit placeholder syntax for overrides:

"display_name": "${localization.BundleName}"

This gives developers full control over mapping without relying on conventions.

---

2. Icons

Follow MCP registry’s server.json pattern (array of objects):

"icons": [
  {
    "src": "assets/icons/icon-16-light.png",
    "sizes": "16x16",
    "theme": "light"
  },
  {
    "src": "assets/icons/icon-16-dark.png",
    "sizes": "16x16",
    "theme": "dark"
  }
]

Do icons need localization?
No. Icons are visual assets and typically do not require language-specific variants. Theme and size differentiation is sufficient.

Definitions:

• sizes: String in widthxheight format (e.g., 16x16).
• theme: Optional, values: "light", "dark", or a custom platform-dependent string (this can be used to cater to specific themes such as high contrast).

---

Why This Design?

• Per-locale files prevent manifest bloat and allow clients to fetch only what they need.
• Fallback to default locale ensures robustness when translations are incomplete.
• BCP 47 compliance guarantees interoperability across platforms.
• Theme-aware icons improve UX without introducing unnecessary complexity.
• Future placeholder syntax provides flexibility for advanced scenarios without complicating v1.

---

Trade-offs

Approach	Pros	Cons
Inline all locales	Simple, self-contained	Manifest size explodes
External per-locale	Lightweight, cache-friendly	Requires resource hosting
Explicit placeholders	Flexible, works with existing keys	Slightly more verbose

---

Compatibility

• If localization or icons is missing, fallback to existing display_name, description, and icon.
• Clients should implement graceful degradation.

---

Final Notes

• Locale identifiers must follow BCP 47.
• Default locale content lives in the main manifest.
• Placeholder syntax is a future enhancement, not required in v1.
• Icons do not require localization.
• Missing localized fields must fall back to default locale values.

Fixes #98

[joan-anthropic]

Thanks so much for opening this proposal! Overall aligned with the high-level approach. cc'ing @domdomegg @MarshallOfSound @loc for input

A few qs:

• Should we enforce localization files in a single, named location (e.g. locales/)? it's possible the spec might want to lay claim to specific named directories in the future
• "Must follow https://www.rfc-editor.org/rfc/bcp/bcp47.txt" - it looks like this spec supports an effectively unlimited number of locale names?
  • Should we consider restricting this to a set of known locales we know we want to support (these are ours) and applying validation rules against those?
• it's worth noting I don't think MCP servers themselves are localized - so a MCPB that's been localized to one language may still have an MCP whose underlying tools/tool descriptions are in another

[joan-anthropic]

I have a PR open here to rename 0.3 -> vNext, but I think we want to avoid publicizing / documenting 0.3 until it's finalized (unless we think this PR captures all of the remaining requirements- i think we still have folder tokens?)

[asklar]

@joan-anthropic re: folder tokens - after thinking about it more, I think we don't need that just yet (we may in the future, but I wouldn't want to hold 0.3 for that). Are there other changes in 0.3 you would like to get in? happy to snap to whatever y'all need and rebase this on top of your 0.3->vNext PR

[joan-anthropic]

sounds good! v0.3 sounds good then

[joan-anthropic]

Ditto re: comment above

[domdomegg]

LGTM from my side, happy to defer to @joan-anthropic on the details she's picked up :)

[asklar]

Thanks so much for opening this proposal! Overall aligned with the high-level approach. cc'ing @domdomegg @MarshallOfSound @loc for input

A few qs:

• Should we enforce localization files in a single, named location (e.g. locales/)? it's possible the spec might want to lay claim to specific named directories in the future

• "Must follow https://www.rfc-editor.org/rfc/bcp/bcp47.txt" - it looks like this spec supports an effectively unlimited number of locale names?

  • Should we consider restricting this to a set of known locales we know we want to support (these are ours) and applying validation rules against those?

• it's worth noting I don't think MCP servers themselves are localized - so a MCPB that's been localized to one language may still have an MCP whose underlying tools/tool descriptions are in another

@joan-anthropic thanks for the thoughtful questions :)

• I debated myself on whether to mandate a single location; I think we can definitely document the default (resources/${locale}.json) but leave the option open for overriding that. My rationale is to enable the server implementation to use that folder path for other purposes if it needs to; the alternative to that, if we mandate a folder, would be for the whole server implementation to go into a subfolder, i.e. have app/mymcp.js, app/resources/* separate from /resources/*). I think having the default location plus allowing the folder override is a good compromise, what do you think?

• Different clients will support different sets of locales (some may not support anything but en-US!). I've added a note about client locale fallback to clarify.

• I think tool and prompt descriptions for display should be localized (e.g. see VSCode which shows the tool descriptions:

• The developer is responsible for ensuring their MCPB matches the MCP server they are writing the manifest for, so I'd expect the manifest localization capabilities to match what the server supports.

[joan-anthropic]

My rationale is to enable the server implementation to use that folder path for other purposes if it needs to; the alternative to that, if we mandate a folder, would be for the whole server implementation to go into a subfolder, i.e. have app/mymcp.js, app/resources/* separate from /resources/*). I think having the default location plus allowing the folder override is a good compromise, what do you think?

open to documenting default! my concern is mostly if we or the server spec wants to lay claim to our named default, we're still in a bad world and would need to figure out some path towards reconciliation - does that seem like a legitimate concern, or potentially overblown? Perhaps with a tighter namespace (e.g. mcpb-locale/, manifest-locale/) we could mitigate some of your concern? Only feel ~30% strongly about this.

[asklar]

@joan-anthropic I've added the default value of mcpb-resources/${locale}.json, that way it's clear that this folder is specific to mcpb resources.

[joan-anthropic]

@asklar one more request - can you fix the prettier warnings you'll see on yarn lint? it's on our list to make this a required check

[asklar]

@joan-anthropic gladly :) pushed an update with the lint changes