Merge branch 'modelcontextprotocol:main' into dotnet

Author: asklar

.github/workflows/test.yml

@@ -39,3 +39,32 @@ jobs:
         run: yarn build
       - name: Test
         run: yarn lint && yarn test
+
+  validate-schemas:
+    name: Validate JSON Schemas
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22.17.x"
+          cache: "yarn"
+      - name: Install dependencies
+        run: yarn install --immutable
+      - name: Build code (required for schema generation)
+        run: yarn build:code
+      - name: Generate schemas
+        run: yarn build:schema
+      - name: Check for schema changes
+        run: |
+          if ! git diff --exit-code schemas/; then
+            echo "Error: JSON schemas in schemas/ directory are out of sync!"
+            echo "Please run 'yarn build:schema' and commit the changes."
+            echo ""
+            echo "Changes detected:"
+            git diff schemas/
+            exit 1
+          fi
+          echo "✓ All schemas are up to date"

.vscode/settings.json

@@ -6,5 +6,6 @@
   "eslint.validate": ["typescript"],
   "[typescript]": {
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  }
+  },
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

CONTRIBUTING.md

@@ -46,6 +46,7 @@ To set up commit signing, see [GitHub's documentation on commit signature verifi
 ### Bug Reports
 
 When filing a bug report, please include:
+
 - Clear description of the issue
 - Steps to reproduce
 - Expected vs actual behavior
@@ -55,13 +56,15 @@ When filing a bug report, please include:
 ### Feature Requests
 
 We welcome feature suggestions! Please:
+
 - Clearly describe the feature and use case
 - Explain why this would be valuable to users
 - Consider if it aligns with the project's goals
 
 ### Code Contributions
 
 We especially welcome:
+
 - Bug fixes
 - Documentation improvements
 - Test coverage improvements

MANIFEST.md

@@ -1,7 +1,7 @@
 # MCPB Manifest.json Spec
 
-Current version: `0.2`
-Last updated: 2025-09-12
+Current version: `0.3`
+Last updated: 2025-10-24
 
 ## Manifest Schema
 
@@ -11,13 +11,13 @@ A basic `manifest.json` with just the required fields looks like this:
 
 ```jsonc
 {
-  "manifest_version": "0.2", // Manifest spec version this manifest conforms to
+  "manifest_version": "0.3", // Manifest spec version this manifest conforms to
   "name": "my-extension", // Machine-readable name (used for CLI, APIs)
   "version": "1.0.0", // Semantic version of your extension
   "description": "A simple MCP extension", // Brief description of what the extension does
   "author": {
     // Author information (required)
-    "name": "Extension Author" // Author's name (required field)
+    "name": "Extension Author", // Author's name (required field)
   },
   "server": {
     // Server configuration (required)
@@ -28,16 +28,16 @@ A basic `manifest.json` with just the required fields looks like this:
       "command": "node", // Command to run the server
       "args": [
         // Arguments passed to the command
-        "${__dirname}/server/index.js" // ${__dirname} is replaced with the extension's directory
-      ]
-    }
-  }
+        "${__dirname}/server/index.js", // ${__dirname} is replaced with the extension's directory
+      ],
+    },
+  },
 }
 ```
 
 ```json
 {
-  "manifest_version": "0.2",
+  "manifest_version": "0.3",
   "name": "my-extension",
   "version": "1.0.0",
   "description": "A simple MCP extension",
@@ -71,7 +71,7 @@ A full `manifest.json` with most of the optional fields looks like this:
 
 ```json
 {
-  "manifest_version": "0.1",
+  "manifest_version": "0.3",
   "name": "My MCP Extension",
   "display_name": "My Awesome MCP Extension",
   "version": "1.0.0",
@@ -84,16 +84,32 @@ A full `manifest.json` with most of the optional fields looks like this:
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-username/my-mcp-extension"
+    "url": "https://github.com/your-username/my-mcp-extension.git"
   },
   "homepage": "https://example.com/my-extension",
   "documentation": "https://docs.example.com/my-extension",
   "support": "https://github.com/your-username/my-extension/issues",
   "icon": "icon.png",
+  "icons": [
+    {
+      "src": "assets/icons/icon-16-light.png",
+      "size": "16x16",
+      "theme": "light"
+    },
+    {
+      "src": "assets/icons/icon-16-dark.png",
+      "size": "16x16",
+      "theme": "dark"
+    }
+  ],
   "screenshots": [
     "assets/screenshots/screenshot1.png",
     "assets/screenshots/screenshot2.png"
   ],
+  "localization": {
+    "resources": "custom-directory-for-mcpb-resources/${locale}.json",
+    "default_locale": "en-US"
+  },
   "server": {
     "type": "node",
     "entry_point": "server/index.js",
@@ -196,12 +212,12 @@ A full `manifest.json` with most of the optional fields looks like this:
                       "type": "string"
                     }
                   }
-                },
+                }
               }
             }
           ]
         }
-      },
+      }
     }
   }
 }
@@ -214,30 +230,72 @@ A full `manifest.json` with most of the optional fields looks like this:
 - **manifest_version**: Specification version this extension conforms to
 - **name**: Machine-readable name (used for CLI, APIs)
 - **version**: Semantic version (semver)
-- **description**: Brief description
-- **author**: Author information object with name (required), email (optional), and url (optional)
+- 🌎 **description**: Brief description. This field is localizable.
+- 🌎 **author**: Author information object with name (required, localizable), email (optional), and url (optional)
 - **server**: Server configuration object
 
 ### Optional Fields
 
-- **icon**: Path to a png icon file, either relative in the package or a https:// url.
-- **display_name**: Human-friendly name for UI display
-- **long_description**: Detailed description for extension stores, markdown
-- **repository**: Source code repository information (type and url)
-- **homepage**: Extension homepage URL
-- **documentation**: Documentation URL
-- **support**: Support/issues URL
-- **screenshots**: Array of screenshot paths
-- **tools**: Array of tools the extension provides
-- **tools_generated**: Boolean indicating the server generates additional tools at runtime (default: false)
-- **prompts**: Array of prompts the extension provides
-- **prompts_generated**: Boolean indicating the server generates additional prompts at runtime (default: false)
-- **keywords**: Search keywords
-- **license**: License identifier
-- **privacy_policies**: Array of URLs to privacy policies for external services that handle user data. Required when the extension connects to external services (first- or third-party) that process user data. Each URL should link to the respective service's privacy policy document
-- **compatibility**: Compatibility requirements (client app version, platforms, and runtime versions)
-- **user_config**: User-configurable options for the extension (see User Configuration section)
-- **_meta**: Platform-specific client integration metadata (e.g., Windows `package_family_name`, macOS bundle identifiers) enabling tighter OS/app store integration. The keys in the `_meta` object are reverse-DNS namespaced, and the values are a dictionary of platform-specific metadata.
+- **icon**: Path to a png icon file, either relative in the package or a `https://` url.
+- **icons**: Array of icon descriptors (`src`, `size`, optional `theme`) for light/dark or size-specific assets.
+- 🌎 **display_name**: Human-friendly name for UI display. This field is localizable.
+- 🌎 **long_description**: Detailed description for extension stores, markdown. This field is localizable.
+- **repository**: Source code repository information (type and url).
+- **homepage**: Extension homepage URL.
+- **documentation**: Documentation URL.
+- **support**: Support/issues URL.
+- **screenshots**: Array of screenshot paths.
+- 🌎 **tools**: Array of tools the extension provides. This field is localizable.
+- **tools_generated**: Boolean indicating the server generates additional tools at runtime (default: false).
+- 🌎 **prompts**: Array of prompts the extension provides. This field is localizable.
+- **prompts_generated**: Boolean indicating the server generates additional prompts at runtime (default: false).
+- 🌎 **keywords**: Search keywords. This field is localizable.
+- **license**: License identifier.
+- **privacy_policies**: Array of URLs to privacy policies for external services that handle user data. Required when the extension connects to external services (first- or third-party) that process user data. Each URL should link to the respective service's privacy policy document.
+- **compatibility**: Compatibility requirements (client app version, platforms, and runtime versions).
+- **user_config**: User-configurable options for the extension (see User Configuration section).
+- **\_meta**: Platform-specific client integration metadata (e.g., Windows `package_family_name`, macOS bundle identifiers) enabling tighter OS/app store integration. The keys in the `_meta` object are reverse-DNS namespaced, and the values are a dictionary of platform-specific metadata.
+- **localization**: Location of translated strings for user-facing fields (`resources` path containing a `${locale}` placeholder and `default_locale`).
+
+### Localization
+
+Provide localized strings without bloating the manifest by pointing to external per-locale resource files. A localization entry looks like this:
+
+```jsonc
+"localization": {
+  "resources": "relative-path-to-resources/${locale}.json",
+  "default_locale": "en-US"
+}
+```
+
+- `resources` must include a `${locale}` placeholder. Clients resolve it relative to the server install directory.
+  - This property is optional, and its default value is **`mcpb-resources/${locale}.json`**.
+- `default_locale` must be a valid [BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) identifier such as `en-US` or `zh-Hans`.
+  - This property is optional, and its default value is `en-US`.
+- Values for the default locale stay in the main manifest; localized files only need to contain overrides.
+
+For tools and prompts, the descriptions are also localizable.
+
+#### Client guidelines
+
+- if a client wants to show tool or prompt descriptions in their UI, the client should look for the locale-specific description override in the corresponding per-locale file.
+- clients should only look for tools/prompts present in the manifest.json, i.e. prompts and tools that only exist in the per-locale file should be ignored.
+- Clients should apply locale fallbacks if the client/user locale is not represented by the server. For example, if the user is in the `es-UY` locale but the server does not include that per-locale file, the client should look for an approrpiate fallback, e.g. `es-MX` or `es-ES`, or fall back to the values in the manifest.
+
+### Icons
+
+Use the `icons` array when you need multiple icon variants (different sizes or themes):
+
+```json
+"icons": [
+  { "src": "assets/icons/icon-16-light.png", "size": "16x16", "theme": "light" },
+  { "src": "assets/icons/icon-16-dark.png", "size": "16x16", "theme": "dark" }
+]
+```
+
+- `size` must be in `WIDTHxHEIGHT` form (e.g., `128x128`).
+- `theme` is optional; use values like `light`, `dark`, or platform-specific labels (e.g., `high-contrast`).
+- The legacy `icon` field remains supported for single assets—clients use it when `icons` is omitted.
 
 ## Compatibility
 
@@ -606,9 +664,9 @@ For servers with a fixed set of capabilities, list them in arrays.
 Each prompt in the `prompts` array must include:
 
 - **name**: The identifier for the prompt
-- **description** (optional): Explanation of what the prompt does
+- 🌎 **description** (optional): Explanation of what the prompt does
 - **arguments** (optional): Array of argument names that can be used in the prompt text
-- **text**: The actual prompt text that uses template variables like `${arguments.topic}` or `${arguments.aspect}` as placeholders for MCP Client-supplied arguments. If your argument is named `language`, you'd add `${arguments.language} where you expect it to show up in the prompt.
+- 🌎 **text**: The actual prompt text that uses template variables like `${arguments.topic}` or `${arguments.aspect}` as placeholders for MCP Client-supplied arguments. If your argument is named `language`, you'd add `${arguments.language}` where you expect it to show up in the prompt.
 
 Example:
 
@@ -655,4 +713,3 @@ The `_generated` fields:
 - **prompts_generated**: Server generates additional prompts beyond those listed (default: false)
 
 This helps implementing apps understand that querying the server at runtime will reveal more capabilities than what's declared in the manifest.
-

examples/hello-world-node/manifest.json

@@ -1,6 +1,6 @@
 {
   "$schema": "../../dist/mcpb-manifest.schema.json",
-  "manifest_version": "0.1",
+  "manifest_version": "0.3",
   "name": "hello-world-node",
   "display_name": "Hello World MCP Server (Reference Extension)",
   "version": "0.1.0",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anthropic-ai/mcpb",
   "description": "Tools for building MCP Bundles",
-  "version": "1.1.1",
+  "version": "2.0.2",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -26,14 +26,34 @@
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js",
       "require": "./dist/cli.js"
+    },
+    "./mcpb-manifest-v0.1.schema.json": "./dist/mcpb-manifest-v0.1.schema.json",
+    "./mcpb-manifest-v0.2.schema.json": "./dist/mcpb-manifest-v0.2.schema.json",
+    "./mcpb-manifest-v0.3.schema.json": "./dist/mcpb-manifest-v0.3.schema.json",
+    "./mcpb-manifest-latest.schema.json": "./dist/mcpb-manifest-latest.schema.json",
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js",
+      "require": "./dist/schemas/index.js"
+    },
+    "./schemas/*": {
+      "types": "./dist/schemas/*.d.ts",
+      "import": "./dist/schemas/*.js",
+      "require": "./dist/schemas/*.js"
+    },
+    "./schemas-loose": {
+      "types": "./dist/schemas-loose.d.ts",
+      "import": "./dist/schemas-loose.js",
+      "require": "./dist/schemas-loose.js"
     }
   },
   "bin": "dist/cli/cli.js",
   "files": [
-    "dist"
+    "dist",
+    "schemas"
   ],
   "scripts": {
-    "build": "yarn run build:code",
+    "build": "yarn run build:code && yarn run build:schema",
     "build:code": "tsc",
     "build:schema": "node ./scripts/build-mcpb-schema.js",
     "dev": "tsc --watch",
@@ -71,11 +91,12 @@
     "ignore": "^7.0.5",
     "node-forge": "^1.3.1",
     "pretty-bytes": "^5.6.0",
-    "zod": "^3.25.67"
+    "zod": "^3.25.67",
+    "zod-to-json-schema": "^3.24.6"
   },
   "resolutions": {
     "@babel/helpers": "7.27.1",
     "@babel/parser": "7.27.3"
   },
   "packageManager": "yarn@4.10.3+sha512.c38cafb5c7bb273f3926d04e55e1d8c9dfa7d9c3ea1f36a4868fa028b9e5f72298f0b7f401ad5eb921749eb012eb1c3bb74bf7503df3ee43fd600d14a018266f"
-}
+}