[IDEA] Specify required CLI arguments in the spec

[danbarr]

Some MCP servers have arguments that are required to run. For example, LaunchDarkly's needs a start arg.

It would be nice to bake these into the container, since doing so at the ToolHive registry level means it's easy for users to accidentally overwrite them due to the way CLI arg handling works with thv run (args supplied with -- <args> overwrite default args from the registry, not append).

My idea is something like adding an args array to the spec...

spec:
  package: "@launchdarkly/mcp-server"
  version: "0.4.2"
  args:
    - "start"

And these would be appended to the entrypoint command in the Dockerfile. In the above example, instead of exec npx @launchdarkly/mcp-server@latest, it would be exec npx @launchdarkly/mcp-server@latest start

I think this would have to happen at the Dockyard level since I don't think the ToolHive BuildFromProtocolSchemeWithName function has this ability (or necessarily needs it, this issue aside)?

[danbarr]

Proposed Solution

After investigating this issue and reviewing the ToolHive codebase, I believe the right approach is to add a buildArgs parameter to the BuildFromProtocolSchemeWithName function in pkg/runner/protocol.go. This would allow Dockyard to bake required CLI arguments directly into the container's ENTRYPOINT at build time.

Why This Approach is Sound

This proposal is validated by recent work in ToolHive:

• PR #2630 removed an unimplemented MCPArgs field from templates specifically because it would have led to argument duplication
• The key difference: buildArgs are for required subcommands (like start), while runtime args from thv run -- <args> are for optional flags
• This semantic separation prevents duplication since they serve different purposes

Implementation Plan

1. Update Function Signature

In pkg/runner/protocol.go:

func BuildFromProtocolSchemeWithName(
    ctx context.Context,
    imageManager images.ImageManager,
    serverOrImage string,
    caCertPath string,
    imageName string,
    buildArgs []string,  // NEW parameter
    dryRun bool,
) (string, error)

2. Update TemplateData Struct

In pkg/container/templates/templates.go:

type TemplateData struct {
    MCPPackage    string
    CACertContent string
    IsLocalPath   bool
    BuildArgs     []string  // NEW: baked into entrypoint
}

3. Update Dockerfile Templates

Modify all three templates to insert buildArgs before "$@":

npx.tmpl (line ~101):

# Current:
echo "exec npx {{.MCPPackage}} \"\$@\"" >> entrypoint.sh

# New:
echo "exec npx {{.MCPPackage}}{{range .BuildArgs}} {{.}}{{end}} \"\$@\"" >> entrypoint.sh

uvx.tmpl (line ~121):

# Current:
ENTRYPOINT ["sh", "-c", "package='{{.MCPPackage}}'; exec \"${package%%@*}\"", "--"]

# New:
ENTRYPOINT ["sh", "-c", "package='{{.MCPPackage}}'; exec \"${package%%@*}\"{{range .BuildArgs}} \"{{.}}\"{{end}}", "--"]

go.tmpl (line ~102):

# Current:
ENTRYPOINT ["/app/mcp-server"]

# New:
ENTRYPOINT ["/app/mcp-server"{{range .BuildArgs}}, "{{.}}{{end}}"]

4. Update Existing Callers

Update all existing ToolHive callers to pass empty slice (no breaking changes):

• HandleProtocolScheme(): Pass nil or []string{}
• thv build command: Pass nil or []string{} (initially)

5. Dockyard Integration

Dockyard would call the updated function with args from the spec:

buildArgs := []string{"start"}  // From spec.args
imageName, err := runner.BuildFromProtocolSchemeWithName(
    ctx, imageManager, serverOrImage, caCertPath, imageName, buildArgs, dryRun)

Example Results

LaunchDarkly MCP Server:

# Dockyard spec:
spec:
  package: "@launchdarkly/mcp-server"
  version: "0.4.2"
  args:
    - "start"

# Generated entrypoint.sh:
exec npx @launchdarkly/mcp-server start "$@"

# Container command when user runs with additional args:
npx @launchdarkly/mcp-server start --verbose --debug

No Duplication Risk

The design prevents duplication because:

• buildArgs: Required subcommands baked into the image (e.g., start)
• Runtime args: User-provided flags that append via "$@" (e.g., --verbose)
• These serve different purposes and don't overlap

This is different from the removed MCPArgs field which would have duplicated runtime args.

Optional: Enhancement to thv build

We could also add support for build args to thv build for consistency:

thv build npx://@launchdarkly/mcp-server -- start

This would:

• Use the same -- <args> separator as thv run for consistency
• Reuse existing parseCommandArguments() logic
• Make it easy for users to test build-time args locally

However, this is optional and not required for the Dockyard use case.

Questions

1. Should we add validation for buildArgs (e.g., shell escaping, character restrictions)?
2. Do we need to handle shell escaping differently for the three template types?
3. Should this be documented as a best practice for "required subcommands only"?

Let me know if this approach looks good and I can implement it!