From d42f11e479e1f802f6826a9efb7ec614f3ae2015 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Sat, 12 Jul 2025 12:34:36 -0400 Subject: [PATCH] Make value_hint optional to allow constant positional arguments (#172) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Motivation and Context This is one attempt to resolve https://github.com/modelcontextprotocol/registry/issues/169. Instead of adding a new "constant" argument type, I expanded the existing positional one and just dropped the `value_hint` requirement. I am not sure if this has VS Code impact @sandy081, @connor4312. Also, removed unneeded release_date values from the samples. ## How Has This Been Tested? I tested the current server.json samples in the repo against the new (less strict) schema. Of course they passed (aside from an unrelated bug in my previous NuGet sample 🤦). ## Breaking Changes ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [ ] New and existing tests pass locally - [ ] I have added appropriate error handling - [x] I have added or updated documentation as needed ## Additional context --- docs/server-json/examples.md | 57 ++++++++++++++++++++------- docs/server-json/schema.json | 17 ++++++-- docs/server-registry-api/openapi.yaml | 6 ++- 3 files changed, 61 insertions(+), 19 deletions(-) diff --git a/docs/server-json/examples.md b/docs/server-json/examples.md index de87c1c..3de955a 100644 --- a/docs/server-json/examples.md +++ b/docs/server-json/examples.md @@ -12,8 +12,7 @@ "id": "abc123de-f456-7890-ghij-klmnopqrstuv" }, "version_detail": { - "version": "1.0.2", - "release_date": "2023-06-15T10:30:00Z" + "version": "1.0.2" }, "packages": [ { @@ -33,6 +32,39 @@ } ``` +## Constant (fixed) arguments needed to start the MCP server + +Suppose your MCP server application requires a `mcp start` CLI arguments to start in MCP server mode. Express these as positional arguments like this: + +```json +{ + "name": "Knapcode.SampleMcpServer", + "description": "Sample NuGet MCP server for a random number and random weather", + "version_detail": { + "version": "0.4.0-beta" + }, + "packages": [ + { + "registry_name": "nuget", + "name": "Knapcode.SampleMcpServer", + "version": "0.4.0-beta", + "package_arguments": [ + { + "type": "positional", + "value": "mcp" + }, + { + "type": "positional", + "value": "start" + } + ] + } + ] +} +``` + +This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcpServer@0.4.0-beta -- mcp start` instead of the default `dnx Knapcode.SampleMcpServer@0.4.0-beta` (when no `package_arguments` are provided). + ## Filesystem Server with Multiple Packages ```json @@ -45,8 +77,7 @@ "id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9" }, "version_detail": { - "version": "1.0.2", - "release_date": "2023-06-15T10:30:00Z" + "version": "1.0.2" }, "packages": [ { @@ -128,8 +159,7 @@ "id": "xyz789ab-cdef-0123-4567-890ghijklmno" }, "version_detail": { - "version": "2.0.0", - "release_date": "2024-01-20T14:30:00Z" + "version": "2.0.0" }, "remotes": [ { @@ -152,8 +182,7 @@ "id": "def456gh-ijkl-7890-mnop-qrstuvwxyz12" }, "version_detail": { - "version": "0.5.0", - "release_date": "2024-02-10T09:15:00Z" + "version": "0.5.0" }, "packages": [ { @@ -189,11 +218,11 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. "description": "Sample NuGet MCP server for a random number and random weather", "repository": { "url": "https://github.com/joelverhagen/Knapcode.SampleMcpServer", - "source": "github" + "source": "github", + "id": "def456gh-ijkl-7890-mnop-qrstuvwxyz13" }, "version_detail": { - "version": "0.3.0", - "release_date": "2025-07-02T18:54:28.00Z" + "version": "0.3.0-beta" }, "packages": [ { @@ -226,8 +255,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. "id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789" }, "version_detail": { - "version": "3.1.0", - "release_date": "2024-03-05T16:45:00Z" + "version": "3.1.0" }, "packages": [ { @@ -313,8 +341,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. "id": "klm012no-pqrs-3456-tuvw-xyz789abcdef" }, "version_detail": { - "version": "1.5.0", - "release_date": "2024-04-01T12:00:00Z" + "version": "1.5.0" }, "packages": [ { diff --git a/docs/server-json/schema.json b/docs/server-json/schema.json index 122a9ab..c5352fa 100644 --- a/docs/server-json/schema.json +++ b/docs/server-json/schema.json @@ -196,8 +196,7 @@ { "type": "object", "required": [ - "type", - "value_hint" + "type" ], "properties": { "type": { @@ -217,7 +216,19 @@ "description": "Whether the argument can be repeated multiple times in the command line.", "default": false } - } + }, + "anyOf": [ + { + "required": [ + "value_hint" + ] + }, + { + "required": [ + "value" + ] + } + ] } ] }, diff --git a/docs/server-registry-api/openapi.yaml b/docs/server-registry-api/openapi.yaml index 46dc5eb..9de90f7 100644 --- a/docs/server-registry-api/openapi.yaml +++ b/docs/server-registry-api/openapi.yaml @@ -247,7 +247,6 @@ components: - type: object required: - type - - value_hint properties: type: type: string @@ -261,6 +260,11 @@ components: type: boolean description: Whether the argument can be repeated multiple times in the command line. default: false + anyOf: + - required: + - value + - required: + - value_hint NamedArgument: description: A command-line `--flag={value}`.