Tool schema for create_container fails VS Code validation: array type must have items

Fixing VS Code Validation Failure: "array type must have items" in mcp-server-docker

You might encounter an error when using mcp-server-docker with VS Code's MCP integration. Specifically, the validation of the mcp_docker_create_container tool fails with the message: "Error: tool parameters array type must have items". This article will guide you through understanding and resolving this issue.

Understanding the Problem

This error arises because the JSON schema generated for the mcp_docker_create_container tool's parameters doesn't fully comply with the schema validation requirements of some clients, like VS Code. The schema defines an array type without specifying the type of items it should contain, which triggers the validation error.

Environment

This issue commonly occurs in the following environment:

OS: Windows
MCP Client: VS Code (with GitHub Copilot MCP integration)
Server Launch: Using a command like uvx mcp-server-docker
Package Version: mcp-server-docker==0.2.1 (or potentially other versions)

Reproducing the Error

You can reproduce this error with these steps:

Configure the MCP server: Add the following configuration to your VS Code settings:
```
"docker": {
  "command": "uvx",
  "args": ["mcp-server-docker"]
}
    
```
Start VS Code MCP and validate tools.
Observe the validation failure: You should see the error message "Error: tool parameters array type must have items" for the mcp_docker_create_container tool.

Root Cause Analysis

The root cause lies in how the ports field within the CreateContainerInput data model is defined. The schema for this field includes a tuple branch, which translates to a JSON schema like this:


{
  "type": "array",
  "prefixItems": [{"type":"string"},{"type":"integer"}],
  "minItems": 2,
  "maxItems": 2
}

The problem is that even though the schema specifies the types of the first and second items in the array using prefixItems, it lacks a general items definition. Some schema validators require an items definition for all array types, leading to the validation failure.

The field definition in Python looks like this:


ports: dict[str, int | list[int] | tuple[str, int] | None] | None

Solution: Addressing the Schema Validation Issue

There are a couple of ways to resolve this issue:

1. Replacing Tuple with an Object

One approach is to replace the tuple[str, int] type with a more explicit object representation. This would involve changing the MCP input schema to use an object with named properties instead of a tuple. For example:

Instead of:


["host", 8080]

Use:


{ "host": "host", "port": 8080 }

This would require changes in the data model definition to reflect this new structure.

2. Defining `json_schema_extra`

Another approach is to define a json_schema_extra for the ports field. This allows you to explicitly specify the JSON schema for that field, ensuring that all array branches include an items definition. This method allows you to override the default schema generation.

Example (conceptual):


from typing import Dict, Union, List, Tuple, Optional
from pydantic import BaseModel, Field

class CreateContainerInput(BaseModel):
    ports: Optional[Dict[str, Union[int, List[int], Tuple[str, int], None]]] = Field(
        default=None,
        json_schema_extra={
            "oneOf": [
                {"type": "integer"},
                {"type": "array", "items": {"type": "integer"}},
                {"type": "array", "prefixItems": [{"type": "string"}, {"type": "integer"}], "minItems": 2, "maxItems": 2, "items": {"type": ["string", "integer"]}},
                {"type": "null"}
            ]
        }
    )

This example demonstrates how you can use json_schema_extra to provide a more detailed schema definition, including the missing items property for the tuple-based array.

Practical Tips and Considerations

Schema Validation: Always validate your JSON schemas against a robust validator to catch potential issues early on.
Client Compatibility: Be aware that different clients may have varying levels of strictness when it comes to schema validation. Test your schemas with multiple clients to ensure broad compatibility.
Documentation: Clearly document the expected format of your tool parameters to avoid confusion and errors.

By understanding the root cause of the "array type must have items" error and applying the suggested solutions, you can ensure that your mcp-server-docker tools validate correctly in VS Code and other MCP clients.