Consider adding `prefix` property to NamedArgument

[BobDickinson]

Is your feature request related to a problem? Please describe.

The documentation of the NamedArgument name property is very clear:

"name": {
  "description": "The flag name, including any leading dashes.",
  "example": "--port",
  "type": "string"
 }

Yet it is widely misused in published servers. There are currently 49 instances of named arguments without leading dashes in the published servers and all of them are in error (according to their own docs, they require leading --).

I also did a brief search for any other MCP servers, SDKs, or toolkits that might use runtime or package args without dashes, and I did not find any (though I will grant that such use cases might exist, or might exist in the future).

Describe the solution you'd like

I would like to propose adding a prefix property to NamedArgument that contains the dash(es) (or presumably other) prefix, with that value defaulting to -- when not provided.

"prefix": {
  "description": "Optional prefix for the argument. Defaults to '--'. Set to empty string for no prefix.",
  "type": "string",
  "default": "--",
  "example": "--"
}

In our current situation, there is no way to detect or prevent the very common error of omitting required -- prefixes if we want to allow for the possibility (however remote) that the argument really doesn't have a prefix.

With an explicit prefix property (and default) we accomplish a few things:

• The documentation becomes even more clear and explicit
• The default behavior is correct for the mainline (only current?) use case and people who would have made the mistake of omitting dashes will be helped
• We have a mechanism to support communicating the case of an argument without a prefix if that ever happens ("prefix": "")
• By separating the prefix from the name, we can reasonably use the name without the prefix in template substitution, as in:

"transport": {
  "type": "streamable-http",
  "url": "http://127.0.0.1:{port}/mcp"
}

As opposed to how we would do this currently (if anyone using template substitution on a package transport actually used the correct notation, which they don't):

"transport": {
  "type": "streamable-http",
  "url": "http://127.0.0.1:{--port}/mcp"
}

[BobDickinson]

@tadasant and @connor4312 - this is also my preferred way to handle the "clean" token reference issue, as brought up in #570 and #656.

[connor4312]

This could also be solved/helped if the publisher CLI has a warning if it encounters named fields that don't use at least a single -, and/or better validation tools so MCP authors can see what their command line/server would be before publishing.

I'm not a big fan of making an API change and incrementally increasing complexity because documentation/practices are unclear. I'd prefer we fix and improve those rather than taking another breaking API change.

[BobDickinson]

I definitely get the aversion to adding fields or making really any changes this late. As a latecomer to the project, I've really tried to avoid suggesting such changes just because I think it would be better a different way (even if it may not seem that way).

That being said, it's not just that the schema/documentation is unclear (or not followed). The current model does not support both detection of missing prefixes and arguments that legitimately don't have prefixes. In my linter I have a warning rule for lack of prefixes (since it's always a mistake, in my experience), but if you had a legitimately non-prefixed arg, there would be no way in the argument spec to suppress the linter warning (other than blanket suppression by rule during validation).

I think separating the name and prefix makes referencing by name (without prefix) more acceptable - it's explicit, as opposed to having to understand the history or philosophy and the resolution logic around it to get "naked" args to work as tokens.

I'm not a subscriber to "more properties" == "more complicated". The goal is to have the correct properties based on how the data is defined and used, and there are cases where normalizing data with the correct properties actually makes the schema and its application more clear, easier to follow, and easier to implement. I would argue that bundling the prefix into the name, especially if we are going to then add out-of-band rules for how do deal with prefixes in special cases (manually validate their presence as required, remove prefixes when doing token matching, etc), is actually the more complicated approach.

I don't consider this a breaking change. No existing arg that includes dashes will fail to work as it currently does (we would expect people to migrate their prefixes into prefix, but it will still work as is). In fact, it is sort of an "unbreaking" change, because it will fix 49 instances of schema validation with no change required from the publishers.