feat: introduce a flag to disable version check (#33)

* feat: add disable version check functionality for Portainer MCP

- Introduced a `--disable-version-check` flag to allow connections to unsupported Portainer versions, enhancing flexibility for users.
- Updated the README to include instructions and warnings regarding the use of the new flag.
- Modified the MCP server implementation to conditionally skip version validation based on the flag.
- Enhanced unit tests to cover scenarios involving the disabled version check, ensuring robust error handling and functionality.

* test: add integration test for disabled version check in Portainer MCP server

- Implemented a new test to verify that the Portainer MCP server can connect to unsupported Portainer versions when the version check is disabled.
- Ensured proper setup and teardown of the Portainer container during the test.
- Validated the successful creation of the MCP server and the retrieval of settings, confirming functionality without version validation.

Author: deviantony

README.md

@@ -16,7 +16,10 @@ MCP (Model Context Protocol) is an open protocol that standardizes how applicati
 
 This implementation focuses on exposing Portainer environment data through the MCP protocol, allowing AI assistants and other tools to interact with your containerized infrastructure in a secure and standardized way.
 
-See the [Portainer Version Support](#portainer-version-support) and [Supported Capabilities](#supported-capabilities) sections for more details on compatibility and available features.
+> [!NOTE]
+> This tool is designed to work with specific Portainer versions. If your Portainer version doesn't match the supported version, you can use the `--disable-version-check` flag to attempt connection anyway. See [Portainer Version Support](#portainer-version-support) for compatible versions and [Disable Version Check](#disable-version-check) for bypass instructions.
+
+See the [Supported Capabilities](#supported-capabilities) sections for more details on compatibility and available features.
 
 *Note: This project is currently under development.*
 
@@ -89,6 +92,42 @@ Replace `[IP]`, `[PORT]` and `[TOKEN]` with the IP, port and API access token as
 > [!NOTE]
 > By default, the tool looks for "tools.yaml" in the same directory as the binary. If the file does not exist, it will be created there with the default tool definitions. You may need to modify this path as described above, particularly when using AI assistants like Claude that have restricted write permissions to the working directory.
 
+## Disable Version Check
+
+By default, the application validates that your Portainer server version matches the supported version and will fail to start if there's a mismatch. If you have a Portainer server version that doesn't have a corresponding Portainer MCP version available, you can disable this version check to attempt connection anyway.
+
+To disable the version check, add the `-disable-version-check` flag to your command arguments:
+
+```
+{
+    "mcpServers": {
+        "portainer": {
+            "command": "/path/to/portainer-mcp",
+            "args": [
+                "-server",
+                "[IP]:[PORT]",
+                "-token",
+                "[TOKEN]",
+                "-disable-version-check"
+            ]
+        }
+    }
+}
+```
+
+> [!WARNING]
+> Disabling the version check may result in unexpected behavior or API incompatibilities if your Portainer server version differs significantly from the supported version. The tool may work partially or not at all with unsupported versions.
+
+When using this flag:
+- The application will skip Portainer server version validation at startup
+- Some features may not work correctly due to API differences between versions
+- Newer Portainer versions may have API changes that cause errors
+- Older Portainer versions may be missing APIs that the tool expects
+
+This flag is useful when:
+- You're running a newer Portainer version that doesn't have MCP support yet
+- You're running an older Portainer version and want to try the tool anyway
+
 ## Tool Customization
 
 By default, the tool definitions are embedded in the binary. The application will create a tools file at the default location if one doesn't already exist.
@@ -160,6 +199,9 @@ This tool is pinned to support a specific version of Portainer. The application
 | 0.4.1 | 2.29.2 |
 | 0.5.0 | 2.30.0 |
 
+> [!NOTE]
+> If you need to connect to an unsupported Portainer version, you can use the `-disable-version-check` flag to bypass version validation. See the [Disable Version Check](#disable-version-check) section for more details and important warnings about using this feature.
+
 # Supported Capabilities
 
 The following table lists the currently (latest version) supported operations through MCP tools:

cmd/portainer-mcp/mcp.go

@@ -27,6 +27,8 @@ func main() {
 	tokenFlag := flag.String("token", "", "The authentication token for the Portainer server")
 	toolsFlag := flag.String("tools", "", "The path to the tools YAML file")
 	readOnlyFlag := flag.Bool("read-only", false, "Run in read-only mode")
+	disableVersionCheckFlag := flag.Bool("disable-version-check", false, "Disable Portainer server version check")
+
 	flag.Parse()
 
 	if *serverFlag == "" || *tokenFlag == "" {
@@ -55,9 +57,10 @@ func main() {
 		Str("portainer-host", *serverFlag).
 		Str("tools-path", toolsPath).
 		Bool("read-only", *readOnlyFlag).
+		Bool("disable-version-check", *disableVersionCheckFlag).
 		Msg("starting MCP server")
 
-	server, err := mcp.NewPortainerMCPServer(*serverFlag, *tokenFlag, toolsPath, mcp.WithReadOnly(*readOnlyFlag))
+	server, err := mcp.NewPortainerMCPServer(*serverFlag, *tokenFlag, toolsPath, mcp.WithReadOnly(*readOnlyFlag), mcp.WithDisableVersionCheck(*disableVersionCheckFlag))
 	if err != nil {
 		log.Fatal().Err(err).Msg("failed to create server")
 	}

internal/mcp/server.go

@@ -90,8 +90,9 @@ type ServerOption func(*serverOptions)
 
 // serverOptions contains all configurable options for the server
 type serverOptions struct {
-	client   PortainerClient
-	readOnly bool
+	client              PortainerClient
+	readOnly            bool
+	disableVersionCheck bool
 }
 
 // WithClient sets a custom client for the server.
@@ -110,6 +111,14 @@ func WithReadOnly(readOnly bool) ServerOption {
 	}
 }
 
+// WithDisableVersionCheck disables the Portainer server version check.
+// This allows connecting to unsupported Portainer versions.
+func WithDisableVersionCheck(disable bool) ServerOption {
+	return func(opts *serverOptions) {
+		opts.disableVersionCheck = disable
+	}
+}
+
 // NewPortainerMCPServer creates a new Portainer MCP server.
 //
 // This server provides an implementation of the MCP protocol for Portainer,
@@ -148,13 +157,15 @@ func NewPortainerMCPServer(serverURL, token, toolsPath string, options ...Server
 		portainerClient = client.NewPortainerClient(serverURL, token, client.WithSkipTLSVerify(true))
 	}
 
-	version, err := portainerClient.GetVersion()
-	if err != nil {
-		return nil, fmt.Errorf("failed to get Portainer server version: %w", err)
-	}
+	if !opts.disableVersionCheck {
+		version, err := portainerClient.GetVersion()
+		if err != nil {
+			return nil, fmt.Errorf("failed to get Portainer server version: %w", err)
+		}
 
-	if version != SupportedPortainerVersion {
-		return nil, fmt.Errorf("unsupported Portainer server version: %s, only version %s is supported", version, SupportedPortainerVersion)
+		if version != SupportedPortainerVersion {
+			return nil, fmt.Errorf("unsupported Portainer server version: %s, only version %s is supported", version, SupportedPortainerVersion)
+		}
 	}
 
 	return &PortainerMCPServer{

internal/mcp/server_test.go

@@ -75,6 +75,16 @@ func TestNewPortainerMCPServer(t *testing.T) {
 			expectError:   true,
 			errorContains: "unsupported Portainer server version",
 		},
+		{
+			name:      "unsupported version with disabled version check",
+			serverURL: "https://portainer.example.com",
+			token:     "valid-token",
+			toolsPath: validToolsPath,
+			mockSetup: func(m *MockPortainerClient) {
+				// No GetVersion call expected when version check is disabled
+			},
+			expectError: false,
+		},
 	}
 
 	for _, tt := range tests {
@@ -84,11 +94,19 @@ func TestNewPortainerMCPServer(t *testing.T) {
 			tt.mockSetup(mockClient)
 
 			// Create server with mock client using the WithClient option
+			var options []ServerOption
+			options = append(options, WithClient(mockClient))
+
+			// Add WithDisableVersionCheck for the specific test case
+			if tt.name == "unsupported version with disabled version check" {
+				options = append(options, WithDisableVersionCheck(true))
+			}
+
 			server, err := NewPortainerMCPServer(
 				tt.serverURL,
 				tt.token,
 				tt.toolsPath,
-				WithClient(mockClient),
+				options...,
 			)
 
 			if tt.expectError {

tests/integration/server_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"testing"
 
+	mcpmodels "github.com/mark3labs/mcp-go/mcp"
 	"github.com/portainer/portainer-mcp/internal/mcp"
 	"github.com/portainer/portainer-mcp/tests/integration/containers"
 	"github.com/stretchr/testify/assert"
@@ -74,3 +75,46 @@ func TestServerInitializationUnsupportedVersion(t *testing.T) {
 	assert.Contains(t, err.Error(), "unsupported Portainer server version", "Error should indicate version mismatch")
 	assert.Nil(t, mcpServer, "Server should be nil when version check fails")
 }
+
+// TestServerInitializationDisabledVersionCheck verifies that the Portainer MCP server
+// can successfully connect to unsupported Portainer versions when version check is disabled.
+func TestServerInitializationDisabledVersionCheck(t *testing.T) {
+	// Start a Portainer container with unsupported version
+	ctx := context.Background()
+
+	portainer, err := containers.NewPortainerContainer(ctx, containers.WithImage(unsupportedImage))
+	require.NoError(t, err, "Failed to start unsupported Portainer container")
+
+	// Ensure container is terminated at the end of the test
+	defer func() {
+		if err := portainer.Terminate(ctx); err != nil {
+			t.Logf("Failed to terminate container: %v", err)
+		}
+	}()
+
+	// Get the host and port for the Portainer API
+	host, port := portainer.GetHostAndPort()
+	serverURL := fmt.Sprintf("%s:%s", host, port)
+	apiToken := portainer.GetAPIToken()
+
+	// Create the MCP server with disabled version check - should succeed despite unsupported version
+	mcpServer, err := mcp.NewPortainerMCPServer(serverURL, apiToken, toolsPath, mcp.WithDisableVersionCheck(true))
+
+	// Assert the server was created successfully
+	require.NoError(t, err, "Failed to create MCP server with disabled version check")
+	require.NotNil(t, mcpServer, "MCP server should not be nil when version check is disabled")
+
+	// Verify basic functionality by testing settings retrieval
+	handler := mcpServer.HandleGetSettings()
+	request := mcp.CreateMCPRequest(nil) // GetSettings doesn't require parameters
+
+	result, err := handler(ctx, request)
+	require.NoError(t, err, "Failed to get settings via MCP handler with disabled version check")
+	require.NotNil(t, result, "Settings result should not be nil")
+	require.Len(t, result.Content, 1, "Expected exactly one content block in settings result")
+
+	// Verify the response contains valid content
+	textContent, ok := result.Content[0].(mcpmodels.TextContent)
+	require.True(t, ok, "Expected text content in settings MCP response")
+	assert.NotEmpty(t, textContent.Text, "Settings response should not be empty")
+}