From 2aba70335aaa61a10087d0c1800482fe3c66eff5 Mon Sep 17 00:00:00 2001 From: olaservo Date: Sat, 17 Jan 2026 07:07:16 -0700 Subject: [PATCH 1/2] feat: add client capability schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds JSON Schema 2020-12 for MCP client capabilities at docs/schemas/client-registry.json Features: - Granular capability status (full/partial/unsupported/untested) - Transport, platform, and authentication tracking - Metadata fields (vendor, license, conformanceScore, lastVerified) - Tasks capability with list, cancel, and requests structure (per MCP 2025-11-25 spec) - Backward compatible with presence-based format Closes #718 🦉 Co-Authored-By: Claude Opus 4.5 --- PR-DESCRIPTION.md | 85 ++++++ docs/schemas/client-registry.json | 422 ++++++++++++++++++++++++++++++ 2 files changed, 507 insertions(+) create mode 100644 PR-DESCRIPTION.md create mode 100644 docs/schemas/client-registry.json diff --git a/PR-DESCRIPTION.md b/PR-DESCRIPTION.md new file mode 100644 index 000000000..b3f57d2d7 --- /dev/null +++ b/PR-DESCRIPTION.md @@ -0,0 +1,85 @@ +## Summary + +Adds a JSON Schema for MCP client capabilities, providing a formal structure for documenting what features each client supports. + +Closes #718 + +## Acknowledgments + +This schema builds on the work done by @jancurn in [mcp-client-capabilities](https://github.com/apify/mcp-client-capabilities), which established the core capability structure and has catalogued 40+ clients. This PR extends that foundation with additional fields for transports, platforms, authentication, and metadata. + +## Changes + +- **`docs/schemas/client-registry.json`** - JSON Schema 2020-12 definition + +## What's Included + +This PR focuses solely on the **schema definition**. Intentionally not included: + +- **Client data** - The mcp-client-capabilities repo already has the data. Once the schema is agreed upon, that data can be migrated. +- **Validation scripts** - Can be added in a follow-up PR once the schema is finalized. + +## Schema Overview + +The schema tracks BOTH what clients declare to servers (sampling, elicitation, roots) AND which server capabilities clients can consume (tools, resources, prompts). This is intentionally broader than the MCP spec's `ClientCapabilities` interface. + +**Minimal entry:** +```json +{ + "my-client": { + "title": "My Client", + "url": "https://example.com", + "protocolVersion": "2025-11-25" + } +} +``` + +**Full entry:** +```json +{ + "claude-code": { + "title": "My Advanced Client", + "url": "https://example.com", + "protocolVersion": "2025-11-25", + "category": "cli", + "platforms": ["windows", "macos", "linux"], + "transports": { "stdio": {} }, + "tools": { "listChanged": true }, + "resources": { "listChanged": true, "subscribe": true }, + "prompts": { "listChanged": true }, + "sampling": { "context": {}, "tools": {} }, + "elicitation": { "form": {}, "url": {} }, + "roots": { "listChanged": true }, + "tasks": { + "list": {}, + "cancel": {}, + "requests": { "sampling": { "createMessage": {} } } + }, + "metadata": { + "vendor": "Some Vendor", + "lastVerified": "2026-01-15" + } + } +} +``` + +## Features + +| Feature | Description | +|---------|-------------| +| **Capabilities** | tools, resources, prompts, sampling, elicitation, roots, completions, logging, instructions, tasks | +| **Status values** | `{}` (supported), or `{ "status": "full\|partial\|unsupported\|untested", "notes": "..." }` | +| **Categories** | ide, chat, cli, automation, browser-extension, library, other | +| **Platforms** | windows, macos, linux, web, ios, android | +| **Transports** | stdio, sse, streamableHttp | +| **Auth** | oauth (with PKCE, grantTypes), header, none | +| **Metadata** | vendor, openSource, sourceUrl, license, lastVerified, conformanceScore | + +## Related + +- [modelcontextprotocol#1814](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1814) - Client compatibility matrix +- [mcp-client-capabilities](https://github.com/apify/mcp-client-capabilities) - Community client data + +--- + +🦉 Generated with [Claude Code](https://claude.ai/code) and reviewed by me diff --git a/docs/schemas/client-registry.json b/docs/schemas/client-registry.json new file mode 100644 index 000000000..6bcbfc9f0 --- /dev/null +++ b/docs/schemas/client-registry.json @@ -0,0 +1,422 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://static.modelcontextprotocol.io/schemas/draft/client-registry.json", + "title": "MCP Client Registry", + "description": "Schema for MCP client capability registry. Tracks BOTH what clients declare to servers (sampling, elicitation, roots) AND which server capabilities clients can consume (tools, resources, prompts, completions, logging). This is intentionally broader than the MCP spec's ClientCapabilities interface. See https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1814", + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ClientEntry" + }, + "definitions": { + "ClientEntry": { + "description": "A registered MCP client with its capabilities and metadata.", + "type": "object", + "required": ["title", "url", "protocolVersion"], + "properties": { + "title": { + "type": "string", + "description": "Display name of the client (e.g., 'Claude Code', 'Cursor')." + }, + "url": { + "type": "string", + "format": "uri", + "description": "Homepage or documentation URL for the client." + }, + "description": { + "type": "string", + "description": "Brief description of the client's purpose and features." + }, + "protocolVersion": { + "type": "string", + "description": "MCP protocol version the client supports (e.g., '2025-06-18', '2025-11-25')." + }, + "category": { + "$ref": "#/definitions/ClientCategory", + "description": "Primary category of the client." + }, + "platforms": { + "type": "array", + "items": { + "$ref": "#/definitions/Platform" + }, + "description": "Platforms the client runs on." + }, + "transports": { + "$ref": "#/definitions/TransportCapabilities", + "description": "Transport protocols the client supports." + }, + "authentication": { + "$ref": "#/definitions/AuthenticationCapabilities", + "description": "Authentication methods the client supports for remote servers." + }, + "resources": { + "$ref": "#/definitions/ResourceCapability", + "description": "Server resource consumption capabilities." + }, + "prompts": { + "$ref": "#/definitions/PromptCapability", + "description": "Server prompt consumption capabilities." + }, + "tools": { + "$ref": "#/definitions/ToolCapability", + "description": "Server tool consumption capabilities." + }, + "sampling": { + "$ref": "#/definitions/SamplingCapability", + "description": "Client sampling (LLM completion) capabilities exposed to servers." + }, + "elicitation": { + "$ref": "#/definitions/ElicitationCapability", + "description": "Client elicitation (user input) capabilities exposed to servers." + }, + "roots": { + "$ref": "#/definitions/RootsCapability", + "description": "Client roots (filesystem) capabilities exposed to servers." + }, + "completions": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Whether client supports argument autocompletion." + }, + "logging": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Whether client receives and displays server log messages." + }, + "instructions": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Whether client uses server instructions to enhance LLM context." + }, + "tasks": { + "$ref": "#/definitions/TasksCapability", + "description": "Async task capabilities (MCP 2025-11-25+)." + }, + "experimental": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": true + }, + "description": "Experimental or non-standard capabilities." + }, + "metadata": { + "$ref": "#/definitions/ClientMetadata", + "description": "Additional metadata about the client." + } + } + }, + + "CapabilityStatus": { + "description": "Status of a capability. Can be a simple presence object (backward compatible) or detailed status.", + "oneOf": [ + { + "type": "object", + "description": "Simple presence indicates support (backward compatible with mcp-clients.json).", + "properties": {}, + "additionalProperties": false + }, + { + "type": "object", + "description": "Detailed status with required status field.", + "required": ["status"], + "properties": { + "status": { + "type": "string", + "enum": ["full", "partial", "unsupported", "untested"], + "description": "Support status: full (complete support), partial (with limitations), unsupported (explicitly not supported), untested (unknown)." + }, + "notes": { + "type": "string", + "description": "Additional notes about the capability (e.g., limitations, version requirements)." + }, + "since": { + "type": "string", + "description": "Client version when this capability was added." + } + }, + "additionalProperties": false + } + ] + }, + + "ClientCategory": { + "type": "string", + "enum": ["ide", "chat", "cli", "automation", "browser-extension", "library", "other"], + "description": "Category of the MCP client." + }, + + "Platform": { + "type": "string", + "enum": ["windows", "macos", "linux", "web", "ios", "android"], + "description": "Platform the client runs on." + }, + + "TransportCapabilities": { + "type": "object", + "description": "Transport protocols the client can use to connect to servers.", + "properties": { + "stdio": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Standard I/O transport (subprocess communication)." + }, + "sse": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Server-Sent Events transport (legacy HTTP streaming)." + }, + "streamableHttp": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Streamable HTTP transport (MCP 2025-03-26+)." + } + }, + "additionalProperties": { + "$ref": "#/definitions/CapabilityStatus" + } + }, + + "AuthenticationCapabilities": { + "type": "object", + "description": "Authentication methods the client supports for remote MCP servers.", + "properties": { + "oauth": { + "$ref": "#/definitions/OAuthCapability", + "description": "OAuth authentication support." + }, + "header": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Header-based authentication (API keys, bearer tokens)." + }, + "none": { + "$ref": "#/definitions/CapabilityStatus", + "description": "Unauthenticated connections." + } + }, + "additionalProperties": { + "$ref": "#/definitions/CapabilityStatus" + } + }, + + "OAuthCapability": { + "type": "object", + "description": "OAuth authentication capabilities with granular feature support.", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "version": { + "type": "string", + "enum": ["2.0", "2.1"], + "description": "OAuth version supported." + }, + "pkce": { + "type": "boolean", + "description": "Whether client supports PKCE (Proof Key for Code Exchange)." + }, + "dynamicRegistration": { + "type": "boolean", + "description": "Whether client supports OAuth Dynamic Client Registration (RFC 7591)." + }, + "grantTypes": { + "type": "array", + "items": { + "type": "string", + "enum": ["authorization_code", "client_credentials", "refresh_token", "device_code"] + }, + "description": "Supported OAuth grant types." + } + }, + "additionalProperties": true + }, + + "ResourceCapability": { + "type": "object", + "description": "Client's ability to consume server resources.", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "listChanged": { + "type": "boolean", + "description": "Whether client handles resources/list_changed notifications." + }, + "subscribe": { + "type": "boolean", + "description": "Whether client supports resource subscriptions." + } + }, + "additionalProperties": true + }, + + "PromptCapability": { + "type": "object", + "description": "Client's ability to consume server prompts.", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "listChanged": { + "type": "boolean", + "description": "Whether client handles prompts/list_changed notifications." + } + }, + "additionalProperties": true + }, + + "ToolCapability": { + "type": "object", + "description": "Client's ability to consume server tools.", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "listChanged": { + "type": "boolean", + "description": "Whether client handles tools/list_changed notifications." + } + }, + "additionalProperties": true + }, + + "SamplingCapability": { + "type": "object", + "description": "Client's ability to provide LLM sampling to servers (sampling/createMessage).", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "context": { + "type": "object", + "additionalProperties": true, + "description": "Whether client supports includeContext parameter." + }, + "tools": { + "type": "object", + "additionalProperties": true, + "description": "Whether client supports tool use in sampling (MCP 2025-11-25+)." + } + }, + "additionalProperties": true + }, + + "ElicitationCapability": { + "type": "object", + "description": "Client's ability to elicit user input for servers.", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "form": { + "type": "object", + "additionalProperties": true, + "description": "Whether client supports form-based elicitation." + }, + "url": { + "type": "object", + "additionalProperties": true, + "description": "Whether client supports URL-based elicitation (OAuth flows)." + } + }, + "additionalProperties": true + }, + + "RootsCapability": { + "type": "object", + "description": "Client's ability to expose filesystem roots to servers.", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "listChanged": { + "type": "boolean", + "description": "Whether client sends roots/list_changed notifications." + } + }, + "additionalProperties": true + }, + + "TasksCapability": { + "type": "object", + "description": "Client's async task capabilities (MCP 2025-11-25+).", + "properties": { + "status": { + "$ref": "#/definitions/CapabilityStatus" + }, + "list": { + "type": "object", + "additionalProperties": true, + "description": "Whether client supports tasks/list." + }, + "cancel": { + "type": "object", + "additionalProperties": true, + "description": "Whether client supports tasks/cancel." + }, + "requests": { + "type": "object", + "description": "Specifies which request types can be augmented with tasks.", + "properties": { + "sampling": { + "type": "object", + "properties": { + "createMessage": { + "type": "object", + "additionalProperties": true, + "description": "Whether sampling/createMessage can be task-augmented." + } + }, + "additionalProperties": true, + "description": "Task support for sampling-related requests." + }, + "tools": { + "type": "object", + "properties": { + "call": { + "type": "object", + "additionalProperties": true, + "description": "Whether tools/call can be task-augmented." + } + }, + "additionalProperties": true, + "description": "Task support for tool-related requests." + } + }, + "additionalProperties": true + } + }, + "additionalProperties": true + }, + + "ClientMetadata": { + "type": "object", + "description": "Additional metadata about the client.", + "properties": { + "vendor": { + "type": "string", + "description": "Company or developer that maintains the client." + }, + "openSource": { + "type": "boolean", + "description": "Whether the client is open source." + }, + "sourceUrl": { + "type": "string", + "format": "uri", + "description": "URL to source code repository." + }, + "license": { + "type": "string", + "description": "Software license (e.g., 'MIT', 'Apache-2.0')." + }, + "lastVerified": { + "type": "string", + "format": "date", + "description": "Date when capabilities were last verified (ISO 8601 date)." + }, + "conformanceScore": { + "type": "number", + "minimum": 0, + "maximum": 100, + "description": "Percentage of conformance tests passed (0-100)." + } + }, + "additionalProperties": true + } + } +} From 2f35859c9435a7c5e26b7ea238bd4be29437fdac Mon Sep 17 00:00:00 2001 From: olaservo Date: Sat, 17 Jan 2026 14:31:41 -0700 Subject: [PATCH 2/2] feat: add clientIdMetadataDocument to OAuth capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add explicit CIMD (Client ID Metadata Documents) tracking to OAuth authentication capabilities. CIMD is an alternative to Dynamic Client Registration where clients host metadata at a URL instead of using DCR (SEP-991, MCP 2025-11-25+). This addresses conformance test auth/basic-cimd.ts which validates CIMD support. 🦉 Co-Authored-By: Claude Opus 4.5 --- docs/schemas/client-registry.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/schemas/client-registry.json b/docs/schemas/client-registry.json index 6bcbfc9f0..5760d72e2 100644 --- a/docs/schemas/client-registry.json +++ b/docs/schemas/client-registry.json @@ -213,6 +213,10 @@ "type": "boolean", "description": "Whether client supports OAuth Dynamic Client Registration (RFC 7591)." }, + "clientIdMetadataDocument": { + "type": "boolean", + "description": "Whether client supports Client ID Metadata Documents (CIMD) - URL-based client IDs where client hosts metadata at a URL instead of using DCR (SEP-991, MCP 2025-11-25+)." + }, "grantTypes": { "type": "array", "items": {