Refactor manifest schema to replace static_responses and client_extensions with _meta for improved organization

This commit is contained in:
Alexander Sklar 2025-10-10 16:19:59 -07:00
commit 443d849420
No known key found for this signature in database
4 changed files with 62 additions and 206 deletions

View file

@ -156,52 +156,52 @@ A full `manifest.json` with most of the optional fields looks like this:
"max": 100 "max": 100
} }
}, },
"static_responses": { "_meta": {
"initialize": { "com.microsoft.windows": {
"capabilities": {}, "package_family_name": "MyMcpMSIXPackage_51g09708xawrw",
"instructions": "When the user wants to search files, use the search_files tool but only after asking them whether the files are local.", "static_responses": {
"protocolVersion": "2025-06-18", "initialize": {
"serverInfo": { "capabilities": {},
"name": "MyMCPExtension", "instructions": "When the user wants to search files, use the search_files tool but only after asking them whether the files are local.",
"title": "My MCP Extension - Pro Edition", "protocolVersion": "2025-06-18",
"version": "1.0.0" "serverInfo": {
} "name": "MyMCPExtension",
}, "title": "My MCP Extension - Pro Edition",
"tools/list": { "version": "1.0.0"
"tools": [
{
"name": "search_files",
"title": "File search",
"description": "Search for files in a directory",
"inputSchema": {
"type": "object",
"properties": {
"fileSpec": {
"type": "string",
"description": "The file name to search for. Wildcards are supported"
}
},
"required": ["fileSpec"]
},
"outputSchema": {
"type": "object",
"properties": {
"searchResults": {
"type": "array",
"description": "The list of file paths that were found",
"items": {
"type": "string"
}
}
},
} }
},
"tools/list": {
"tools": [
{
"name": "search_files",
"title": "File search",
"description": "Search for files in a directory",
"inputSchema": {
"type": "object",
"properties": {
"fileSpec": {
"type": "string",
"description": "The file name to search for. Wildcards are supported"
}
},
"required": ["fileSpec"]
},
"outputSchema": {
"type": "object",
"properties": {
"searchResults": {
"type": "array",
"description": "The list of file paths that were found",
"items": {
"type": "string"
}
}
},
}
}
]
} }
] },
}
},
"client_extensions": {
"windows": {
"package_family_name": "MyMcpMSIXPackage_51g09708xawrw"
} }
} }
} }
@ -237,8 +237,7 @@ A full `manifest.json` with most of the optional fields looks like this:
- **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 - **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) - **compatibility**: Compatibility requirements (client app version, platforms, and runtime versions)
- **user_config**: User-configurable options for the extension (see User Configuration section) - **user_config**: User-configurable options for the extension (see User Configuration section)
- **static_responses**: A set of static response to protocol messages (for example, `initialize`, `tools/list`, etc.). This allows clients to avoid running a server when a static response is present (e.g. to get the set of tools with their input schemas). For more information, consult the [MCP specification](https://modelcontextprotocol.io/specification). - **_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.
- **client_extensions**: Platform-specific client integration metadata (e.g., Windows `package_family_name`, macOS bundle identifiers) enabling tighter OS/app store integration
## Compatibility ## Compatibility
@ -598,8 +597,6 @@ These fields describe the tools and prompts your MCP server provides. For server
Note: Resources are not included in the manifest because MCP resources are inherently dynamic - they represent URIs to data that the server discovers at runtime based on configuration, filesystem state, database connections, etc. Note: Resources are not included in the manifest because MCP resources are inherently dynamic - they represent URIs to data that the server discovers at runtime based on configuration, filesystem state, database connections, etc.
You can provide richer static tools by adding an `tools/list` entry inside the `static_responses` object.
### Static Declaration ### Static Declaration
For servers with a fixed set of capabilities, list them in arrays. For servers with a fixed set of capabilities, list them in arrays.
@ -659,62 +656,3 @@ The `_generated` fields:
This helps implementing apps understand that querying the server at runtime will reveal more capabilities than what's declared in the manifest. This helps implementing apps understand that querying the server at runtime will reveal more capabilities than what's declared in the manifest.
## Static responses
Servers can provide clients with static responses to protocol messages. Static responses let clients short-circuit server startup for discovery or platform integration metadata.
This is useful to obtain rich tool schema information, server instructions, protocol version that the server supports, etc.
The `static_responses` object is a dictionary where the key is the name of an MCP JSON-RPC method. For more information, consult the [MCP specification](https://modelcontextprotocol.io/specification).
If both the `tools/list` static response and the `tools` array are present, clients should use the tools described in `tools/list`.
Example:
```json
{
"static_responses": {
"initialize": {
"capabilities": {},
"instructions": "When the user wants to search files, use the search_files tool but only after asking them whether the files are local.",
"protocolVersion": "2025-06-18",
"serverInfo": {
"name": "MyMCPExtension",
"title": "My MCP Extension - Pro Edition",
"version": "1.0.0"
}
},
"tools/list": {
"tools": [
{
"name": "search_files",
"title": "File search",
"description": "Search for files in a directory",
"inputSchema": {
"type": "object",
"properties": {
"fileSpec": {
"type": "string",
"description": "The file name to search for. Wildcards are supported"
}
},
"required": ["fileSpec"]
},
"outputSchema": {
"type": "object",
"properties": {
"searchResults": {
"type": "array",
"description": "The list of file paths that were found",
"items": {
"type": "string"
}
}
},
}
}
]
}
},
}
```

View file

@ -107,8 +107,7 @@ export const McpbManifestSchema = z
user_config: z user_config: z
.record(z.string(), McpbUserConfigurationOptionSchema) .record(z.string(), McpbUserConfigurationOptionSchema)
.optional(), .optional(),
static_responses: z.record(z.string(), z.any()).optional(), _meta: z.record(z.string(), z.record(z.string(), z.any())).optional(),
client_extensions: z.record(z.string(), z.record(z.string(), z.any())).optional(),
}) })
.refine((data) => !!(data.dxt_version || data.manifest_version), { .refine((data) => !!(data.dxt_version || data.manifest_version), {
message: message:

View file

@ -110,8 +110,7 @@ export const McpbManifestSchema = z
user_config: z user_config: z
.record(z.string(), McpbUserConfigurationOptionSchema) .record(z.string(), McpbUserConfigurationOptionSchema)
.optional(), .optional(),
static_responses: z.record(z.string(), z.any()).optional(), _meta: z.record(z.string(), z.record(z.string(), z.any())).optional(),
client_extensions: z.record(z.string(), z.record(z.string(), z.any())).optional(),
}) })
.refine((data) => !!(data.dxt_version || data.manifest_version), { .refine((data) => !!(data.dxt_version || data.manifest_version), {
message: message:

View file

@ -137,7 +137,7 @@ describe("McpbManifestSchema", () => {
}); });
}); });
describe("client_extensions", () => { describe("_meta", () => {
const base = { const base = {
manifest_version: "0.2", manifest_version: "0.2",
name: "client-ext-test", name: "client-ext-test",
@ -151,23 +151,23 @@ describe("McpbManifestSchema", () => {
}, },
}; };
it("accepts valid client_extensions object with nested dictionaries", () => { it("accepts valid _meta object with nested dictionaries", () => {
const manifest = { const manifest = {
...base, ...base,
client_extensions: { _meta: {
windows: { package_family_name: "Pkg_123", channel: "stable" }, "com.microsoft.windows": { package_family_name: "Pkg_123", channel: "stable" },
darwin: { bundle_id: "com.example.app", notarized: true }, "com.apple.darwin": { bundle_id: "com.example.app", notarized: true },
}, },
}; };
const result = McpbManifestSchema.safeParse(manifest); const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true); expect(result.success).toBe(true);
}); });
it("rejects primitive value in client_extensions entry", () => { it("rejects primitive value in _meta entry", () => {
const manifest = { const manifest = {
...base, ...base,
client_extensions: { _meta: {
windows: "raw-string" as unknown as Record<string, unknown>, "com.microsoft.windows": "raw-string" as unknown as Record<string, unknown>,
}, },
}; };
const result = McpbManifestSchema.safeParse(manifest); const result = McpbManifestSchema.safeParse(manifest);
@ -178,21 +178,21 @@ describe("McpbManifestSchema", () => {
} }
}); });
it("rejects array value in client_extensions entry", () => { it("rejects array value in _meta entry", () => {
const manifest = { const manifest = {
...base, ...base,
client_extensions: { _meta: {
linux: [] as unknown as Record<string, unknown>, "com.apple.darwin": [] as unknown as Record<string, unknown>,
}, },
}; };
const result = McpbManifestSchema.safeParse(manifest); const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(false); expect(result.success).toBe(false);
}); });
it("rejects null value in client_extensions entry", () => { it("rejects null value in _meta entry", () => {
const manifest = { const manifest = {
...base, ...base,
client_extensions: { _meta: {
custom: null as unknown as Record<string, unknown>, custom: null as unknown as Record<string, unknown>,
}, },
}; };
@ -200,91 +200,11 @@ describe("McpbManifestSchema", () => {
expect(result.success).toBe(false); expect(result.success).toBe(false);
}); });
it("allows empty object for client_extensions", () => { it("allows empty object for _meta", () => {
const manifest = { ...base, client_extensions: {} }; const manifest = { ...base, _meta: {} };
const result = McpbManifestSchema.safeParse(manifest); const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true); expect(result.success).toBe(true);
}); });
}); });
describe("static_responses", () => {
const base = {
manifest_version: "0.2",
name: "static-resp-test",
version: "1.0.0",
description: "Test manifest",
author: { name: "Author" },
server: {
type: "node" as const,
entry_point: "server/index.js",
mcp_config: { command: "node", args: ["server/index.js"] },
},
};
it("accepts valid static_responses with object entries", () => {
const manifest = {
...base,
static_responses: {
initialize: {
capabilities: {},
protocolVersion: "2025-06-18",
serverInfo: { name: "Test", version: "1.0.0" },
},
"tools/list": {
tools: [
{
name: "search_files",
description: "Search for files",
inputSchema: { type: "object", properties: { query: { type: "string" } } },
},
],
},
},
};
const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true);
});
it("accepts primitive value in static_responses entry", () => {
const manifest = {
...base,
static_responses: {
ping: "pong",
code: 200,
ok: true,
},
};
const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true);
});
it("accepts array value in static_responses entry", () => {
const manifest = {
...base,
static_responses: {
list: [1, 2, 3],
},
};
const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true);
});
it("accepts null value in static_responses entry", () => {
const manifest = {
...base,
static_responses: {
initialize: null,
},
};
const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true);
});
it("allows empty object for static_responses", () => {
const manifest = { ...base, static_responses: {} };
const result = McpbManifestSchema.safeParse(manifest);
expect(result.success).toBe(true);
});
});
}); });