Add Docker volume mount support (#201)

* Add core volume infrastructure types.

* Add VolumeEntry and VolumesEntry types to config layer
* Add VariableTypeVolume constant to packages layer
* Add Path and From fields to ArgumentMetadata for volumes

* Add execution context volume support.

* Add VolumeExecutionContext type for volume mappings
* Add Volumes, RawVolumes fields to ServerExecutionContext
* Implement volume expansion and raw storage for filtering
* Update Equals() and IsEmpty() to include volumes

* Implement runtime volume handling and validation.

* Add Volume type with String() method for Docker mount formatting
* Add SafeVolumes() for filtered volume access
* Add computeVolumes() to combine config with runtime mappings
* Add validateRequiredVolumes() to check volume configuration
* Add filterVolumes() for cross-server reference filtering
* Wire volume computation into AggregateConfigs

* Integrate Docker volume support in daemon.

* Add volume arguments to Docker container startup
* Insert --volume flags before environment variables
* Use Volume.String() for proper Docker mount formatting

* Update provider registries for volume support.

* Add volume type to Mozilla AI schema with allOf constraints
* Add Path and From field mappings in model
* Add volume processing in registry loader
* Update MCPM registry formatting

* Add comprehensive test coverage for volumes.

* Add TestVolume_String to verify Docker mount formatting
* Add TestDaemon_DockerVolumeArguments to test volume flag generation
* Add testdata fixtures for volume loading and cross-server filtering
* Tests cover single/multiple volumes, named volumes, and optional volumes

Author: peteski22

internal/config/types.go

@@ -113,19 +113,34 @@ type ServerEntry struct {
 
 	// RequiredBoolArgs captures any command line args that are boolean flags when present, which are required to run the server.
 	RequiredBoolArgs []string `json:"requiredArgsBool,omitempty" toml:"required_args_bool,omitempty" yaml:"required_args_bool,omitempty"`
+
+	// Volumes maps volume names to their Docker volume configuration.
+	Volumes VolumesEntry `json:"volumes,omitempty" toml:"volumes,omitempty" yaml:"volumes,omitempty"`
 }
 
-type serverKey struct {
-	Name    string
-	Package string // NOTE: without version
+// VolumeEntry represents a single Docker volume configuration.
+type VolumeEntry struct {
+	// Path is the container mount path.
+	// e.g., "/workspace", "/home/nonroot/.kube/config".
+	Path string `toml:"path"`
+
+	// Required indicates whether the volume must be configured by the user.
+	Required bool `toml:"required"`
 }
 
-// argEntry represents a parsed command line argument.
+// VolumesEntry maps volume names to their configuration.
+type VolumesEntry map[string]VolumeEntry
+
 type argEntry struct {
 	key   string
 	value string
 }
 
+type serverKey struct {
+	Name    string
+	Package string // NOTE: without version
+}
+
 func (s *ServerEntry) PackageVersion() string {
 	versionDelim := "@"
 	pkg := stripPrefix(s.Package)

internal/context/context.go

@@ -34,12 +34,12 @@ type ExecutionContextConfig struct {
 
 // ServerExecutionContext stores execution context data for an MCP server.
 //
-// The Args and Env fields contain expanded values with environment variables resolved.
+// The Args, Env, and Volumes fields contain expanded values with environment variables resolved.
 // These should not be used directly when starting MCP servers, as they may contain
 // cross-server references that pose security risks.
 //
-// Instead, use the server's SafeArgs() and SafeEnv() methods (in the runtime package)
-// which filter out cross-server references using the RawArgs and RawEnv fields.
+// Instead, use the server's SafeArgs(), SafeEnv(), and SafeVolumes() methods (in the runtime package)
+// which filter out cross-server references using the RawArgs, RawEnv, and RawVolumes fields.
 type ServerExecutionContext struct {
 	// Name is the server name.
 	Name string `toml:"-"`
@@ -52,13 +52,24 @@ type ServerExecutionContext struct {
 	// NOTE: Use runtime.Server.SafeEnv() for filtered access when starting servers.
 	Env map[string]string `toml:"env,omitempty"`
 
-	// RawEnv stores unexpanded environment variables used for cross-server filtering decisions.
-	RawEnv map[string]string `toml:"-"`
+	// Volumes maps volume names to their host paths or named volumes with environment variables expanded.
+	// NOTE: Use runtime.Server.SafeVolumes() for filtered access when starting servers.
+	Volumes VolumeExecutionContext `toml:"volumes,omitempty"`
 
 	// RawArgs stores unexpanded command-line arguments used for cross-server filtering decisions.
 	RawArgs []string `toml:"-"`
+
+	// RawEnv stores unexpanded environment variables used for cross-server filtering decisions.
+	RawEnv map[string]string `toml:"-"`
+
+	// RawVolumes stores unexpanded volume mappings used for cross-server filtering decisions.
+	RawVolumes VolumeExecutionContext `toml:"-"`
 }
 
+// VolumeExecutionContext maps volume names to their host paths or named volumes.
+// e.g., {"workspace": "/Users/foo/repos/mcpd", "gdrive": "mcp-gdrive"}
+type VolumeExecutionContext map[string]string
+
 // Load loads an execution context configuration from the specified path.
 func (d *DefaultLoader) Load(path string) (Modifier, error) {
 	path = strings.TrimSpace(path)
@@ -88,11 +99,13 @@ func (c *ExecutionContextConfig) Get(name string) (ServerExecutionContext, bool)
 
 	if srv, ok := c.Servers[name]; ok {
 		return ServerExecutionContext{
-			Name:    name,
-			Args:    slices.Clone(srv.Args),
-			Env:     maps.Clone(srv.Env),
-			RawEnv:  maps.Clone(srv.RawEnv),
-			RawArgs: slices.Clone(srv.RawArgs),
+			Name:       name,
+			Args:       slices.Clone(srv.Args),
+			Env:        maps.Clone(srv.Env),
+			Volumes:    maps.Clone(srv.Volumes),
+			RawArgs:    slices.Clone(srv.RawArgs),
+			RawEnv:     maps.Clone(srv.RawEnv),
+			RawVolumes: maps.Clone(srv.RawVolumes),
 		}, true
 	}
 
@@ -179,20 +192,28 @@ func (s *ServerExecutionContext) Equals(b ServerExecutionContext) bool {
 		return false
 	}
 
-	if len(s.RawEnv) != len(b.RawEnv) || !maps.Equal(s.RawEnv, b.RawEnv) {
+	if !maps.Equal(s.Volumes, b.Volumes) {
 		return false
 	}
 
 	if !equalSlices(s.RawArgs, b.RawArgs) {
 		return false
 	}
 
+	if len(s.RawEnv) != len(b.RawEnv) || !maps.Equal(s.RawEnv, b.RawEnv) {
+		return false
+	}
+
+	if !maps.Equal(s.RawVolumes, b.RawVolumes) {
+		return false
+	}
+
 	return true
 }
 
-// IsEmpty returns true if the ServerExecutionContext has no args or env vars.
+// IsEmpty returns true if the ServerExecutionContext has no args, env vars, or volumes.
 func (s *ServerExecutionContext) IsEmpty() bool {
-	return len(s.Args) == 0 && len(s.Env) == 0
+	return len(s.Args) == 0 && len(s.Env) == 0 && len(s.Volumes) == 0
 }
 
 // AppDirName returns the name of the application directory for use in user-specific operations where data is being written.
@@ -312,11 +333,14 @@ func loadExecutionContextConfig(path string) (*ExecutionContextConfig, error) {
 	for name, server := range cfg.Servers {
 		server.Name = name
 
+		// Store raw args before expansion for filtering decisions.
+		server.RawArgs = slices.Clone(server.Args)
+
 		// Store raw env vars before expansion for filtering decisions.
 		server.RawEnv = maps.Clone(server.Env)
 
-		// Store raw args before expansion for filtering decisions.
-		server.RawArgs = slices.Clone(server.Args)
+		// Store raw volumes before expansion for filtering decisions.
+		server.RawVolumes = maps.Clone(server.Volumes)
 
 		// Expand args.
 		for i, arg := range server.Args {
@@ -328,6 +352,11 @@ func loadExecutionContextConfig(path string) (*ExecutionContextConfig, error) {
 			server.Env[k] = os.ExpandEnv(v)
 		}
 
+		// Expand volume paths.
+		for k, v := range server.Volumes {
+			server.Volumes[k] = os.ExpandEnv(v)
+		}
+
 		cfg.Servers[name] = server
 	}
 

internal/daemon/daemon.go

@@ -191,9 +191,14 @@ func (d *Daemon) startMCPServer(ctx context.Context, server runtime.Server) erro
 		// Format the Docker package and version
 		packageNameAndVersion := fmt.Sprintf("%s:%s", pkg, ver)
 
-		// Docker requires special handling for environment variables
+		// Docker requires special handling for volumes and environment variables
 		args = []string{"run", "-i", "--rm", "--network", "host"}
 
+		// Add volumes before environment variables.
+		for _, vol := range server.SafeVolumes() {
+			args = append(args, "--volume", vol.String())
+		}
+
 		// Docker supplies the environment variables via args (-e), so
 		// we don't use the server.SafeEnv() as this ensures least privilege.
 		for _, env := range server.SafeEnvIsolated() {
@@ -256,7 +261,7 @@ func (d *Daemon) startMCPServer(ctx context.Context, server runtime.Server) erro
 	initializeCtx, cancel := context.WithTimeout(ctx, d.clientInitTimeout)
 	defer cancel()
 
-	// 'Initialize'
+	// 'Initialize' the MCP server.
 	initResult, err := stdioClient.Initialize(
 		initializeCtx,
 		mcp.InitializeRequest{
@@ -271,14 +276,10 @@ func (d *Daemon) startMCPServer(ctx context.Context, server runtime.Server) erro
 
 	logger.Info(
 		"Initialized",
-		"package",
-		pkg,
-		"version",
-		ver,
-		"server-name",
-		initResult.ServerInfo.Name,
-		"server-version",
-		initResult.ServerInfo.Version,
+		"package", pkg,
+		"version", ver,
+		"server-name", initResult.ServerInfo.Name,
+		"server-version", initResult.ServerInfo.Version,
 	)
 
 	// Store and track the client.

internal/daemon/daemon_test.go

@@ -1118,3 +1118,124 @@ func TestDaemon_DockerRuntimeSupport(t *testing.T) {
 	// Verify Docker is in the daemon's supported runtimes
 	require.Contains(t, daemon.supportedRuntimes, runtime.Docker, "Daemon should support Docker runtime")
 }
+
+func TestDaemon_DockerVolumeArguments(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                string
+		volumes             map[string]config.VolumeEntry
+		volumeContext       map[string]string
+		expectedVolumeFlags []string
+	}{
+		{
+			name:                "no volumes",
+			volumes:             map[string]config.VolumeEntry{},
+			volumeContext:       map[string]string{},
+			expectedVolumeFlags: []string{},
+		},
+		{
+			name: "single required volume",
+			volumes: map[string]config.VolumeEntry{
+				"workspace": {
+					Path:     "/workspace",
+					Required: true,
+				},
+			},
+			volumeContext: map[string]string{
+				"workspace": "/Users/foo/repos/mcpd",
+			},
+			expectedVolumeFlags: []string{
+				"--volume", "/Users/foo/repos/mcpd:/workspace",
+			},
+		},
+		{
+			name: "multiple volumes",
+			volumes: map[string]config.VolumeEntry{
+				"workspace": {
+					Path:     "/workspace",
+					Required: true,
+				},
+				"kubeconfig": {
+					Path:     "/home/nonroot/.kube/config",
+					Required: true,
+				},
+			},
+			volumeContext: map[string]string{
+				"workspace":  "/Users/foo/repos",
+				"kubeconfig": "~/.kube/config",
+			},
+			expectedVolumeFlags: []string{
+				"--volume", "/Users/foo/repos:/workspace",
+				"--volume", "~/.kube/config:/home/nonroot/.kube/config",
+			},
+		},
+		{
+			name: "named docker volume",
+			volumes: map[string]config.VolumeEntry{
+				"data": {
+					Path:     "/data",
+					Required: true,
+				},
+			},
+			volumeContext: map[string]string{
+				"data": "mcp-data",
+			},
+			expectedVolumeFlags: []string{
+				"--volume", "mcp-data:/data",
+			},
+		},
+		{
+			name: "optional volume not configured",
+			volumes: map[string]config.VolumeEntry{
+				"workspace": {
+					Path:     "/workspace",
+					Required: true,
+				},
+				"cache": {
+					Path:     "/cache",
+					Required: false,
+				},
+			},
+			volumeContext: map[string]string{
+				"workspace": "/Users/foo/repos",
+			},
+			expectedVolumeFlags: []string{
+				"--volume", "/Users/foo/repos:/workspace",
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// Manually construct Volume structs to test the Docker argument formatting.
+			// This simulates what would be produced after AggregateConfigs/computeVolumes.
+			var volumes []runtime.Volume
+			for name, entry := range tc.volumes {
+				from, exists := tc.volumeContext[name]
+				// Skip optional volumes without runtime configuration.
+				if !entry.Required && !exists {
+					continue
+				}
+				volumes = append(volumes, runtime.Volume{
+					Name:        name,
+					VolumeEntry: entry,
+					From:        from,
+				})
+			}
+
+			// Build actual volume arguments as the daemon would.
+			var actualVolumeFlags []string
+			for _, vol := range volumes {
+				actualVolumeFlags = append(actualVolumeFlags, "--volume", vol.String())
+			}
+
+			// Verify the volume flags match expectations.
+			// Note: We use ElementsMatch instead of Equal because Go map iteration order is not guaranteed.
+			require.ElementsMatch(t, tc.expectedVolumeFlags, actualVolumeFlags,
+				"Docker volume flags should match expected format")
+		})
+	}
+}

internal/packages/argument.go

@@ -20,6 +20,9 @@ const (
 
 	// VariableTypeArgPositional represents a positional command line argument.
 	VariableTypeArgPositional VariableType = "argument_positional"
+
+	// VariableTypeVolume represents a Docker volume mount.
+	VariableTypeVolume VariableType = "volume"
 )
 
 // EnvVarPlaceholderRegex is used to find environment variable placeholders like ${VAR_NAME}.
@@ -37,7 +40,7 @@ type ArgumentMetadata struct {
 	// Name is the reference for the argument.
 	Name string `json:"name"`
 
-	// VariableType represents the type of argument this is (env var, value flag, bool flag, positional arg).
+	// VariableType represents the type of argument this is (env var, value flag, bool flag, positional arg, volume).
 	VariableType VariableType `json:"type"`
 
 	// Description provides a human-readable explanation of the argument's purpose.
@@ -52,6 +55,14 @@ type ArgumentMetadata struct {
 	// Position specifies the position for positional arguments (1-based index).
 	// Only relevant when Type is ArgumentPositional.
 	Position *int `json:"position,omitempty"`
+
+	// Path is the container mount path for volumes.
+	// Only relevant when VariableType is VariableTypeVolume.
+	Path string `json:"path,omitempty"`
+
+	// From is the host path or named volume for volumes.
+	// Only relevant when VariableType is VariableTypeVolume.
+	From string `json:"from,omitempty"`
 }
 
 // FilterBy allows filtering of Arguments using predicates.
@@ -165,3 +176,8 @@ func NonPositionalArgument(s string, data ArgumentMetadata) bool {
 func ValueAcceptingArgument(_ string, data ArgumentMetadata) bool {
 	return data.VariableType == VariableTypeArgPositional || data.VariableType == VariableTypeArg
 }
+
+// Volume is a predicate that requires the argument is a container volume mount.
+func Volume(_ string, data ArgumentMetadata) bool {
+	return data.VariableType == VariableTypeVolume
+}

internal/provider/mcpm/registry.go

@@ -83,11 +83,11 @@ func NewRegistry(logger hclog.Logger, url string, opt ...runtime.Option) (*Regis
 }
 
 // registrySupportedRuntimes declares the runtimes that this registry supports.
+// Docker runtime is excluded because MCPM packages don't provide rich enough Docker image metadata for volumes.
 func registrySupportedRuntimes() []runtime.Runtime {
 	return []runtime.Runtime{
 		runtime.NPX,
 		runtime.UVX,
-		runtime.Docker,
 	}
 }