Package MCP Server for Dockyard

This skill helps you package MCP servers for distribution via Dockyard containers.

When to Use This Skill

Use this skill when:

• Adding a new MCP server to Dockyard
• Creating a spec.yaml configuration file
• Packaging an npm (npx), PyPI (uvx), or Go MCP server
• The user mentions "package", "add server", "spec.yaml", or "dockyard"

Prerequisites

• The MCP server must be published to npm, PyPI, or as a Go module
• Know the exact package name and version

Workflow

Step 1: Gather Information

Ask the user for:

1. Package name - The exact registry name (e.g., @upstash/context7-mcp, mcp-clickhouse)
2. Package type - npm (npx), PyPI (uvx), or Go
3. Version - Specific version to package (not "latest")
4. Source repository - GitHub URL for the source code

If not provided, look up the package:

# For npm packages
npm view {package-name} version
npm view {package-name} repository.url

# For PyPI packages
curl -s https://pypi.org/pypi/{package-name}/json | jq -r '.info.version, .info.project_urls.Homepage'

Step 2: Determine Protocol Directory

Step 3: Create Directory Structure

mkdir -p {protocol}/{server-name}

The server name should be:

• Lowercase with hyphens
• Based on the package name (without scope)
• Example: @upstash/context7-mcp becomes context7

Step 4: Create spec.yaml

Write the configuration file to {protocol}/{server-name}/spec.yaml:

# {Server Name} MCP Server Configuration
# Package: {package-registry-url}
# Repository: {source-repository-url}
# Will build as: ghcr.io/stacklok/dockyard/{protocol}/{name}:{version}

metadata:
  name: {server-name}
  description: "{brief-description}"
  version: "{version}"
  protocol: {npx|uvx|go}

spec:
  package: "{full-package-name}"
  version: "{exact-version}"
  # args:                          # Optional: CLI arguments
  #   - "start"                    # Some packages need specific commands
  # env:                           # Optional: env vars baked into the runtime image
  #   SOME_VAR: "some-value"       # For values the server reads at process start

provenance:
  repository_uri: "{github-repo-url}"
  repository_ref: "refs/tags/v{version}"

  # Optional: Document attestations if available
  # attestations:
  #   available: true
  #   verified: true
  #   publisher:
  #     kind: "GitHub"
  #     repository: "{owner/repo}"

Step 5: Build dockhand CLI (First Time Only)

# Build the dockhand CLI tool
task build-setup

Step 6: Verify Provenance (Recommended)

Check if the package has provenance attestations:

# Check provenance
./build/dockhand verify-provenance -c {protocol}/{server-name}/spec.yaml -v

If provenance exists, update the spec.yaml with attestation information.

Step 7: Test Locally

# Setup scanner (first time only)
task scan-setup

# Validate spec and generate Dockerfile
task build -- {protocol}/{server-name}

# Run security scan
task scan -- {protocol}/{server-name}

# Optional: Full build test
task test-build -- {protocol}/{server-name}

Step 8: Commit

git add {protocol}/{server-name}/spec.yaml
git commit -m "feat: add {server-name} MCP server

Add packaging for {server-name} v{version}.
Package: {package-url}
Repository: {repo-url}"

Protocol-Specific Notes

npm (npx)

• Package name may include scope: @org/package-name
• Some packages require CLI args (e.g., args: ["start"])
• Check if package has npm provenance signatures

PyPI (uvx)

• Package name is usually lowercase with hyphens
• Check for PEP 740 attestations
• AWS Labs packages have verified attestations

Go

• Package is the full module path: github.com/org/repo
• Version must include v prefix: v0.3.1

Common Issues

See Also

• [SPEC-YAML-REFERENCE.md](references/SPEC-YAML-REFERENCE.md) - Full spec.yaml reference
• [docs/adding-servers.md](../../../docs/adding-servers.md) - Complete contribution guide
• [docs/provenance.md](../../../docs/provenance.md) - Provenance verification details