### Tool Definition Example Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines a tool with its name, description, input and output schemas, annotations, execution settings, icons, and examples. Only 'name' and 'inputSchema' are required. ```yaml tools: - name: "create_tool" # REQUIRED. Unique. 1-128 chars, [A-Za-z0-9_.-]. title: "Create Tool" # OPTIONAL. Human label. description: | # RECOMMENDED. Prompt context for the LLM. Add a new tool definition to the working spec. Use when the user wants to expose a new capability. Returns the updated tool list. inputSchema: # REQUIRED. JSON Schema 2020-12, object. type: object properties: name: type: string pattern: "^[a-z0-9_]+$" description: "Unique tool identifier." description: type: string description: "Human + model facing description." inputSchema: type: object description: "JSON Schema for the tool's parameters." required: ["name", "description"] additionalProperties: false outputSchema: # OPTIONAL. JSON Schema for structured result. type: object properties: toolCount: { type: integer } tool: type: object properties: name: { type: string } title: { type: string } required: ["name"] required: ["toolCount"] annotations: # OPTIONAL. Behavioral hints for clients. title: "Create Tool" readOnlyHint: false destructiveHint: false idempotentHint: true openWorldHint: false execution: # OPTIONAL. Task-augmented execution (rev. 2025-11-25). taskSupport: "optional" # "forbidden" (default) | "optional" | "required" icons: # OPTIONAL. src REQUIRED URI per entry. - src: "https://example.org/tools/create.svg" mimeType: "image/svg+xml" examples: # OPTIONAL. Sample calls for docs/tests. - name: "Add an echo tool" input: name: "echo" description: "Echo the input back." output: toolCount: 1 tool: { name: "echo" } meta: {} # OPTIONAL -> _meta ``` -------------------------------- ### Install and Use Global MCPDS Spec CLI Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Install the MCPDS spec package globally to make the `mcpds-spec` binary available system-wide. This allows you to run the CLI commands from any directory. ```bash npm install -g @mcpds/spec mcpds-spec --help ``` -------------------------------- ### Install AI Skills for Specific Project Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Install MCPDS AI skills for Claude Code, Cursor, and GitHub Copilot specifically for the current project. This limits the AI assistance to the context of this repository. ```bash npx skills add mcpdesignorg/mcpds -a claude-code -a cursor -a github-copilot -y ``` -------------------------------- ### Tool Definition Example Source: https://github.com/mcpdesignorg/mcpds/blob/main/schemas/mcpds-1.0.0.md This YAML snippet demonstrates the structure of a tool definition in MCPDS. It includes required fields like 'name' and 'inputSchema', and optional fields such as 'description', 'outputSchema', 'annotations', 'execution', 'icons', and 'examples'. ```yaml tools: - name: "create_tool" # REQUIRED. Unique. 1-128 chars, [A-Za-z0-9_.-]. title: "Create Tool" # OPTIONAL. Human label. description: | Add a new tool definition to the working spec. Use when the user wants to expose a new capability. Returns the updated tool list. inputSchema: # REQUIRED. JSON Schema 2020-12, object. type: object properties: name: type: string pattern: "^[a-z0-9_]+$" description: "Unique tool identifier." description: type: string description: "Human + model facing description." inputSchema: type: object description: "JSON Schema for the tool's parameters." required: ["name", "description"] additionalProperties: false outputSchema: # OPTIONAL. JSON Schema for structured result. type: object properties: toolCount: { type: integer } tool: type: object properties: name: { type: string } title: { type: string } required: ["name"] required: ["toolCount"] annotations: # OPTIONAL. Behavioral hints for clients. title: "Create Tool" readOnlyHint: false destructiveHint: false idempotentHint: true openWorldHint: false execution: # OPTIONAL. Task-augmented execution (rev. 2025-11-25). taskSupport: "optional" # "forbidden" (default) | "optional" | "required" icons: # OPTIONAL. src REQUIRED URI per entry. - src: "https://example.org/tools/create.svg" mimeType: "image/svg+xml" examples: # OPTIONAL. Sample calls for docs/tests. - name: "Add an echo tool" input: name: "echo" description: "Echo the input back." output: toolCount: 1 tool: { name: "echo" } meta: {} # OPTIONAL -> _meta ``` -------------------------------- ### Install AI Skills Globally Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Install MCPDS AI skills for Claude Code, Cursor, and GitHub Copilot globally for all projects. This command enables AI assistance across your development environment. ```bash npx skills add mcpdesignorg/mcpds -g -a claude-code -a cursor -a github-copilot -y ``` -------------------------------- ### Minimal MCPDS Server Definition Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md A basic example of an MCPDS YAML file defining a server, its transport, and a single tool. This serves as a starting point for describing an MCP server. ```yaml mcpds: "1.0" server: name: cz.restapi/mcp title: REST API Design Guide description: Provides documentation for REST API design. version: 1.0.0 websiteUrl: https://www.restapi.cz authors: - name: Miroslav Holec url: https://holec.ai license: MIT transports: - type: streamable-http url: https://www.restapi.cz/mcp headers: - name: x-api-key description: Authentication using an API key (token). isRequired: true isSecret: true - type: stdio tools: - name: fetch title: Fetch Documentation description: Returns relevant snippets for a given prompt via semantic search. inputSchema: type: object properties: phrase: type: string description: Search phrase. minLength: 3 maxLength: 20 required: [phrase] ``` -------------------------------- ### Install MCPDS Spec Package Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Install the official MCPDS specification package using npm. This package includes the schema and TypeScript types for building tools. ```bash npm install @mcpds/spec ``` -------------------------------- ### MCPDS Transport Configuration Example Source: https://github.com/mcpdesignorg/mcpds/blob/main/schemas/mcpds-1.0.0.md Defines server transports, specifying connection methods and locations. Supports 'stdio' for local and 'streamable-http'/'sse' for remote connections with detailed configuration options. ```yaml transports: - type: stdio # stdio | streamable-http | sse(legacy) - type: streamable-http url: "https://api.example.org/mcp/{tenant}" # may use {var} templates variables: tenant: description: "Tenant identifier" isRequired: true default: "public" sessions: true # Stateful sessions via Mcp-Session-Id sse: true # Server may stream via SSE on this transport cors: # OPTIONAL, HTTP only allowedOrigins: ["https://app.example.org"] headers: # OPTIONAL static/required request headers - name: "MCP-Protocol-Version" isRequired: true - name: "X-API-Key" description: "API key header for deployments that require one." isRequired: true isSecret: true ``` -------------------------------- ### MCP Packaging Configuration for Distribution Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Specifies local, installable distribution artifacts for a server. Includes package details like registry type, identifier, version, and transport configuration. ```yaml packaging: packages: - registryType: "npm" # npm | pypi | cargo | nuget | oci | mcpb | ... (open set) registryBaseUrl: "https://registry.npmjs.org" identifier: "@org/my-server" version: "1.0.0" # OPTIONAL. 1-255 chars; MUST NOT be "latest". transport: { type: "stdio" } # REQUIRED. Local runtime transport (see 10.3). runtimeHint: "npx" # OPTIONAL launcher hint runtimeArguments: # args to the runtime - type: "named" name: "-y" packageArguments: # args to the package itself - type: "positional" valueHint: "target_dir" value: "/project" environmentVariables: - name: "LOG_LEVEL" description: "debug | info | warn | error" default: "info" isSecret: false isRequired: false meta: "io.modelcontextprotocol.registry/publisher-provided": tool: "mcp-designer" version: "1.0.0" ``` -------------------------------- ### Minimal Conforming MCPDS Document Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md An example of a minimal MCPDS document adhering to the 1.0 specification, including server details and transport configuration. ```yaml mcpds: "1.0" server: name: "org.example/hello" description: "Minimal MCP server." version: "1.0.0" transports: - type: stdio tools: - name: "echo" description: "Echo a message back to the caller." inputSchema: type: object properties: message: { type: string } required: ["message"] additionalProperties: false ``` -------------------------------- ### Check MCPDS Package and Schema Version (CLI) Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Use npx to run the MCPDS spec package directly for quick checks of package and schema versions. This is a convenient way to verify your installation. ```bash npx @mcpds/spec --help ``` ```bash npx @mcpds/spec --version ``` -------------------------------- ### MCPDS Transports Configuration Example Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md This snippet shows the configuration for `stdio` and `streamable-http` transports. The `streamable-http` transport includes URL templating, variable definitions, session support, SSE enablement, CORS settings, and required headers. ```yaml transports: - type: stdio # stdio | streamable-http | sse(legacy) - type: streamable-http url: "https://api.example.org/mcp/{tenant}" # may use {var} templates variables: tenant: description: "Tenant identifier" isRequired: true default: "public" sessions: true # Stateful sessions via Mcp-Session-Id sse: true # Server may stream via SSE on this transport cors: # OPTIONAL, HTTP only allowedOrigins: ["https://app.example.org"] headers: # OPTIONAL static/required request headers - name: "MCP-Protocol-Version" isRequired: true - name: "X-API-Key" description: "API key header for deployments that require one." isRequired: true isSecret: true ``` -------------------------------- ### Import MCPDS Schema and Types Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Import the MCPDS schema and document types from the installed package into your TypeScript project. This allows for type-safe validation and development. ```typescript import { mcpdsSchema, type McpdsDocument } from "@mcpds/spec"; ``` -------------------------------- ### Update or Remove AI Skills Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Manage installed MCPDS AI skills by updating them to the latest version or removing them entirely. Use these commands to maintain your AI tool integrations. ```bash npx skills update mcpds npx skills remove mcpds ``` -------------------------------- ### MCPDS Package Transport Configuration Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines the local runtime transport for an installed MCPDS package. Supports 'stdio', 'streamable-http', and 'sse' types. For HTTP/SSE, a URL and optional headers are required. ```yaml transport: type: "stdio" # REQUIRED. stdio | streamable-http | sse # For streamable-http / sse packages: # url: "http://localhost:{port}/mcp" # REQUIRED. http(s) URL or {variable} template. # headers: # OPTIONAL. Named inputs (10.1). # - name: "X-API-Key" # isSecret: true # isRequired: true ``` -------------------------------- ### Resolve MCPDS JSON Schema from Package Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Import the MCPDS JSON Schema directly from the installed package in your code. This allows programmatic access to the schema for validation or introspection purposes. ```typescript import schema from "@mcpds/spec/schema"; // schema.$id === "https://mcpds.org/schema/1.0" ``` -------------------------------- ### Define MCPDS Resources and Resource Templates Source: https://github.com/mcpdesignorg/mcpds/blob/main/schemas/mcpds-1.0.0.md Use `resources` to define static resources with concrete URIs and `resourceTemplates` to define resources using RFC 6570 URI templates. Both require a `name` and either a `uri` or `uriTemplate` respectively. ```yaml resources: - uri: "spec://current" # REQUIRED. name: "current-spec" # REQUIRED. Programmatic id. title: "Current Working Spec" # OPTIONAL. description: "The MCPDS document being edited." mimeType: "application/yaml" # OPTIONAL. size: null # OPTIONAL. Bytes, if known. icons: # OPTIONAL. src REQUIRED URI per entry. - src: "https://example.org/resources/spec.svg" mimeType: "image/svg+xml" annotations: audience: ["assistant", "user"] # Who is this for? priority: 0.8 # 0..1 importance. lastModified: "2025-11-25T10:00:00Z" resourceTemplates: - uriTemplate: "spec://tools/{toolName}" # REQUIRED. name: "tool-by-name" title: "Tool Definition" description: "Fetch a single tool definition by name." mimeType: "application/json" icons: - src: "https://example.org/resources/tool.svg" mimeType: "image/svg+xml" annotations: audience: ["assistant"] priority: 0.5 lastModified: "2025-11-25T10:00:00Z" parameters: # MCPDS: documents template vars. - name: "toolName" description: "The tool's unique name." required: true completion: true # Server offers completion for this arg. ``` -------------------------------- ### Server Identity and Metadata Configuration Source: https://github.com/mcpdesignorg/mcpds/blob/main/schemas/mcpds-1.0.0.md Defines the identity and metadata for a server. Required fields include name, description, and version. Optional fields like title, websiteUrl, repository, icons, authors, license, and meta can also be provided. ```yaml server: name: "org.example/my-server" # REQUIRED. Reverse-DNS namespaced ID. # MUST begin/end alphanumeric; may contain - _ . title: "My Server" # OPTIONAL. Human display name. description: "What the server does." # REQUIRED. version: "1.0" # REQUIRED. websiteUrl: "https://example.org" # OPTIONAL. repository: # OPTIONAL. When present, url + source are REQUIRED. url: "https://github.com/org/repo" source: "github" # github | gitlab | ... id: "optional-vcs-id" icons: # OPTIONAL. Per MCP icon spec. src REQUIRED URI per entry. - src: "https://example.org/icon.svg" mimeType: "image/svg+xml" sizes: ["any"] theme: "dark" # light | dark authors: # OPTIONAL. (MCPDS extension.) - name: "Author Name" url: "https://example.org" license: "MIT" # OPTIONAL. SPDX identifier. meta: {} # OPTIONAL. -> _meta ``` -------------------------------- ### MCPDS Server Instructions and Capabilities Configuration Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines server-wide guidance and supported features like tool subscriptions, resource updates, prompt management, logging, and task execution. Used to configure server behavior and inform clients about available functionalities. ```yaml instructions: | Server-wide guidance injected into the model's system prompt. capabilities: tools: listChanged: true # Server may emit notifications/tools/list_changed resources: subscribe: true # Clients may subscribe to resource updates listChanged: true prompts: listChanged: true logging: true # Supports logging/setLevel + log notifications completions: true # Supports argument completion tasks: # Task-augmented execution (rev. 2025-11-25) list: true # Supports tasks/list cancel: true # Supports tasks/cancel requests: tools: call: true # tools/call may be task-augmented experimental: myFeature: true ``` -------------------------------- ### MCP Prompt Template Definition Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines a reusable, parameterized prompt template for scaffolding server code. Requires a name and can include optional title, description, arguments, and icons. ```yaml prompts: - name: "scaffold_server" # REQUIRED. title: "Scaffold MCP Server" # OPTIONAL. description: "Generate server code from the current spec." arguments: - name: "language" # REQUIRED per argument. title: "Language" # OPTIONAL. description: "Target language." # OPTIONAL. required: true # OPTIONAL. - name: "includeTests" title: "Include tests" description: "Emit a test suite too." required: false icons: - src: "https://example.org/prompts/scaffold.svg" meta: {} ``` -------------------------------- ### MCPDS Resources and Resource Templates Configuration Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines static resources with concrete URIs and templated resources using RFC 6570 URI templates. Ensure required fields like 'uri', 'name', 'uriTemplate', and 'parameters.name' are provided. 'annotations.priority' must be between 0 and 1. ```yaml resources: - uri: "spec://current" # REQUIRED. name: "current-spec" # REQUIRED. Programmatic id. title: "Current Working Spec" # OPTIONAL. description: "The MCPDS document being edited." mimeType: "application/yaml" # OPTIONAL. size: null # OPTIONAL. Bytes, if known. icons: # OPTIONAL. src REQUIRED URI per entry. - src: "https://example.org/resources/spec.svg" mimeType: "image/svg+xml" annotations: audience: ["assistant", "user"] # Who is this for? priority: 0.8 # 0..1 importance. lastModified: "2025-11-25T10:00:00Z" resourceTemplates: - uriTemplate: "spec://tools/{toolName}" # REQUIRED. name: "tool-by-name" title: "Tool Definition" description: "Fetch a single tool definition by name." mimeType: "application/json" icons: - src: "https://example.org/resources/tool.svg" mimeType: "image/svg+xml" annotations: audience: ["assistant"] priority: 0.5 lastModified: "2025-11-25T10:00:00Z" parameters: # MCPDS: documents template vars. - name: "toolName" description: "The tool's unique name." required: true completion: true # Server offers completion for this arg. ``` -------------------------------- ### Run Local MCPDS Spec CLI after Build Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md After building the project locally, you can run the MCPDS spec CLI using npm exec. This is useful for testing changes or using the CLI from a local checkout. ```bash npm run build npm exec -- mcpds-spec --help ``` -------------------------------- ### MCPDS Authentication Schemes Configuration Source: https://github.com/mcpdesignorg/mcpds/blob/main/schemas/mcpds-1.0.0.md Defines 'none', 'oauth2', and 'env' authentication schemes for MCPDS. The 'none' scheme is for no authentication, 'oauth2' supports OAuth 2.1 flows, and 'env' uses environment variables for secrets. All schemes are server-wide. ```yaml auth: schemes: none: type: none # No auth (typical for stdio local) oauth: type: oauth2 # OAuth 2.1 / Protected Resource Metadata flows: authorizationCode: authorizationUrl: "https://auth.example.org/authorize" tokenUrl: "https://auth.example.org/token" scopes: "tools:read": "List and read tool metadata" "tools:write": "Create and modify tools" resourceMetadataUrl: "https://api.example.org/.well-known/oauth-protected-resource" env: type: env # Secrets supplied as environment variables variables: - name: "API_TOKEN" description: "Personal access token" isSecret: true isRequired: true ``` -------------------------------- ### MCPDS Server Identity and Metadata Schema Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines the identity and metadata for a server, mirroring the registry server.json. Ensure required fields like name, description, and version are non-empty. When 'repository' is present, 'url' and 'source' are also required. ```yaml server: name: "org.example/my-server" # REQUIRED. Reverse-DNS namespaced ID. # MUST begin/end alphanumeric; may contain - _ . title: "My Server" # OPTIONAL. Human display name. description: "What the server does." # REQUIRED. version: "1.0" # REQUIRED. websiteUrl: "https://example.org" # OPTIONAL. repository: # OPTIONAL. When present, url + source are REQUIRED. url: "https://github.com/org/repo" source: "github" # github | gitlab | ... id: "optional-vcs-id" icons: # OPTIONAL. Per MCP icon spec. src REQUIRED URI per entry. - src: "https://example.org/icon.svg" mimeType: "image/svg+xml" sizes: ["any"] theme: "dark" # light | dark authors: # OPTIONAL. (MCPDS extension.) - name: "Author Name" url: "https://example.org" license: "MIT" # OPTIONAL. SPDX identifier. meta: {} # OPTIONAL. -> _meta ``` -------------------------------- ### MCPDS Authentication Schemes Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Defines the 'none', 'oauth2', and 'env' authentication schemes for MCPDS. Use this configuration at the server level to specify how clients authenticate. ```yaml auth: schemes: none: type: none # No auth (typical for stdio local) oauth: type: oauth2 # OAuth 2.1 / Protected Resource Metadata flows: authorizationCode: authorizationUrl: "https://auth.example.org/authorize" tokenUrl: "https://auth.example.org/token" scopes: "tools:read": "List and read tool metadata" "tools:write": "Create and modify tools" resourceMetadataUrl: "https://api.example.org/.well-known/oauth-protected-resource" env: type: env # Secrets supplied as environment variables variables: - name: "API_TOKEN" description: "Personal access token" isSecret: true isRequired: true ``` -------------------------------- ### MCPDS 1.0 Top-Level Structure Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md This YAML snippet illustrates the required and optional fields at the top level of an MCPDS 1.0 document. It includes versioning, server identity, transport definitions, and optional extensions. ```yaml mcpds: "1.0" # REQUIRED. Spec version string; MUST be "1.0". x-mcpProtocolVersion: "2025-11-25" # OPTIONAL. MCP protocol revision targeted. server: {} # REQUIRED. Identity & metadata. instructions: "" # OPTIONAL. Server-wide guidance for the LLM. capabilities: {} # OPTIONAL. Declared protocol feature flags. requiresClientCapabilities: [] # OPTIONAL. Client capabilities the server depends on. transports: [] # REQUIRED. Transport AND remote-endpoint definitions. auth: {} # OPTIONAL. Authentication & authorization. packaging: {} # OPTIONAL. Local distribution packages. tools: [] # OPTIONAL. Tool definitions. resources: [] # OPTIONAL. Static resource definitions. resourceTemplates: [] # OPTIONAL. URI-templated resource definitions. prompts: [] # OPTIONAL. Prompt template definitions. x-*: {} # OPTIONAL. Vendor extensions (any top-level x- key). ``` -------------------------------- ### Reference MCPDS JSON Schema in YAML Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Configure your YAML language server to automatically provide schema validation and autocompletion for `.mcp.yaml` files by referencing the bundled JSON Schema. This improves the development experience. ```yaml # yaml-language-server: $schema=https://unpkg.com/@mcpds/spec/schemas/mcpds-1.0.schema.json ``` -------------------------------- ### MCPDS Client Capability Requirements Source: https://github.com/mcpdesignorg/mcpds/blob/main/skills/mcpds/references/mcpds-1.0.0.md Declares specific client-side MCP capabilities that the server actively utilizes. Clients should verify support for these before connecting, and unknown values must be tolerated. ```yaml requiresClientCapabilities: ["elicitation", "sampling"] ``` -------------------------------- ### Import MCPDS Schema from Subpath Export Source: https://github.com/mcpdesignorg/mcpds/blob/main/README.md Access the MCPDS schema directly using subpath exports from the package. This is useful for referencing the schema in configurations or other tools. ```typescript import schema from "@mcpds/spec/schema"; ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.