Improve MCP configuration error messages with YAML examples and type information #4067
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Enhanced error messages in pkg/workflow/mcp-config.go and pkg/parser/mcp.go to follow the three-part template (what's wrong + expected + example) as specified in the error message style guide. Changes: - Unknown property errors now list all valid properties with examples - Missing required field errors explain options and show complete YAML examples - Type validation errors show received type using %T and expected types - Mutual exclusivity errors (command vs container) explain both options with examples - HTTP MCP errors clearly explain required url field with examples - Unsupported type errors list valid types with examples - All examples use proper multi-line YAML formatting with \n Added comprehensive test suite in mcp_error_messages_test.go that verifies: - All error messages contain what's wrong, expected format, and examples - Error messages include tool names for personalization - YAML examples have proper structure and formatting - Type mismatches show both received and expected types All existing tests continue to pass. Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Enhance MCP configuration validation error messages with YAML examples
Improve MCP configuration error messages with YAML examples and type information
Nov 15, 2025
Copilot finished work on behalf of
pelikhan
November 15, 2025 17:42
pelikhan
approved these changes
Nov 15, 2025
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR enhances MCP (Model Context Protocol) configuration validation error messages to provide actionable guidance with complete YAML examples, type information, and comprehensive explanations. The improvements address user confusion when configuring complex MCP server setups by following a three-part template: what's wrong → what's expected → working example.
Key Changes:
- Error messages now include complete lists of valid properties/types when validation fails
- Type mismatches show both received and expected types using
%Tformat specifier - Multi-line YAML examples with proper formatting demonstrate correct configuration
- Examples are personalized with actual tool names from the context
- Mutual exclusivity (command vs container) is explained with examples for both options
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| pkg/workflow/mcp_error_messages_test.go | New comprehensive test suite (412 lines) validating error message quality, structure, and three-part template compliance for MCP configuration errors |
| pkg/workflow/mcp-config.go | Enhanced 4 error messages with valid property lists, type information, and multi-line YAML examples for unknown properties, missing type determination, HTTP URL requirements, and unsupported types |
| pkg/parser/mcp.go | Improved 11 error messages with type information (%T), YAML examples, and detailed explanations for format validation, type checking, stdio/http requirements, and field validation |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
pkg/workflow/mcp-config.go
Outdated
| } | ||
| default: | ||
| return nil, fmt.Errorf("unsupported MCP type '%s' for tool '%s'", result.Type, toolName) | ||
| return nil, fmt.Errorf("unsupported MCP type '%s' for tool '%s'. Valid types are: stdio, http. Example:\nmcp-servers:\n %s:\n type: stdio\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", result.Type, toolName, toolName) |
There was a problem hiding this comment.
[nitpick] Long error message line: This error message exceeds typical line length limits. Consider breaking it into multiple lines for better code readability.
Suggested formatting:
return nil, fmt.Errorf("unsupported MCP type '%s' for tool '%s'. Valid types are: stdio, http. "+
"Example:\nmcp-servers:\n %s:\n type: stdio\n command: \"npx @my/tool\"\n"+
" args: [\"--port\", \"3000\"]", result.Type, toolName, toolName)
Suggested change
| return nil, fmt.Errorf("unsupported MCP type '%s' for tool '%s'. Valid types are: stdio, http. Example:\nmcp-servers:\n %s:\n type: stdio\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", result.Type, toolName, toolName) | |
| return nil, fmt.Errorf( | |
| "unsupported MCP type '%s' for tool '%s'. Valid types are: stdio, http. "+ | |
| "Example:\n"+ | |
| "mcp-servers:\n"+ | |
| " %s:\n"+ | |
| " type: stdio\n"+ | |
| " command: \"npx @my/tool\"\n"+ | |
| " args: [\"--port\", \"3000\"]", | |
| result.Type, toolName, toolName) |
Contributor
Author
There was a problem hiding this comment.
Fixed in commit d57732e. Error message now split across multiple lines with proper concatenation for better readability.
pkg/workflow/mcp-config.go
Outdated
| mcpLog.Printf("Inferred MCP type as stdio (has container field)") | ||
| } else { | ||
| return nil, fmt.Errorf("unable to determine MCP type for tool '%s': missing type, url, command, or container", toolName) | ||
| return nil, fmt.Errorf("unable to determine MCP type for tool '%s': missing type, url, command, or container. Must specify one of: 'type' (stdio/http), 'url' (for HTTP MCP), 'command' (for command-based), or 'container' (for Docker-based). Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", toolName, toolName) |
There was a problem hiding this comment.
[nitpick] Long error message line: This error message exceeds typical line length limits. Consider breaking it into multiple lines for better code readability.
Suggested formatting:
return nil, fmt.Errorf("unable to determine MCP type for tool '%s': missing type, url, command, or container. "+
"Must specify one of: 'type' (stdio/http), 'url' (for HTTP MCP), 'command' (for command-based), or 'container' (for Docker-based). "+
"Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", toolName, toolName)
Suggested change
| return nil, fmt.Errorf("unable to determine MCP type for tool '%s': missing type, url, command, or container. Must specify one of: 'type' (stdio/http), 'url' (for HTTP MCP), 'command' (for command-based), or 'container' (for Docker-based). Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", toolName, toolName) | |
| return nil, fmt.Errorf( | |
| "unable to determine MCP type for tool '%s': missing type, url, command, or container. "+ | |
| "Must specify one of: 'type' (stdio/http), 'url' (for HTTP MCP), 'command' (for command-based), or 'container' (for Docker-based). "+ | |
| "Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", | |
| toolName, toolName, | |
| ) |
Contributor
Author
There was a problem hiding this comment.
Fixed in commit d57732e. Error message reformatted with proper line breaks.
| for prop := range knownProperties { | ||
| validProps = append(validProps, prop) | ||
| } | ||
| sort.Strings(validProps) |
There was a problem hiding this comment.
Missing import: This code uses sort.Strings() but the sort package import is not added to the file. Add "sort" to the imports at the top of the file.
import (
"sort"
"strings"
// ... other imports
)
Contributor
Author
There was a problem hiding this comment.
The sort package import was already present in the file after merging main. No changes needed.
pkg/workflow/mcp-config.go
Outdated
| validProps = append(validProps, prop) | ||
| } | ||
| sort.Strings(validProps) | ||
| return nil, fmt.Errorf("unknown property '%s' in MCP configuration for tool '%s'. Valid properties are: %s. Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", |
There was a problem hiding this comment.
Incorrect string escaping: The backticks in \"npx @my/tool\" are unnecessary and will appear literally in the error message. The @ symbol doesn't need to be escaped in a regular string.
Remove the backticks:
return nil, fmt.Errorf("unknown property '%s' in MCP configuration for tool '%s'. Valid properties are: %s. Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]",
key, toolName, strings.Join(validProps, ", "), toolName)
Suggested change
| return nil, fmt.Errorf("unknown property '%s' in MCP configuration for tool '%s'. Valid properties are: %s. Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", | |
| return nil, fmt.Errorf("unknown property '%s' in MCP configuration for tool '%s'. Valid properties are: %s. Example:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]", |
pkg/parser/mcp.go
Outdated
| } | ||
| } else { | ||
| return config, fmt.Errorf("stdio type requires 'command' or 'container' field") | ||
| return config, fmt.Errorf("stdio MCP tool '%s' must specify either 'command' or 'container' field. Cannot specify both. Example with command:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]\n\nExample with container:\nmcp-servers:\n %s:\n container: \"myorg/my-tool:latest\"\n env:\n API_KEY: \"${{ secrets.API_KEY }}\"", toolName, toolName, toolName) |
There was a problem hiding this comment.
[nitpick] Long error message line: This error message exceeds typical line length limits (appears to be ~350+ characters). While the content is valuable, consider breaking it into multiple lines for better readability in the code.
Suggested formatting:
return config, fmt.Errorf("stdio MCP tool '%s' must specify either 'command' or 'container' field. Cannot specify both. "+
"Example with command:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]\n\n"+
"Example with container:\nmcp-servers:\n %s:\n container: \"myorg/my-tool:latest\"\n env:\n API_KEY: \"${{ secrets.API_KEY }}\"",
toolName, toolName, toolName)
Suggested change
| return config, fmt.Errorf("stdio MCP tool '%s' must specify either 'command' or 'container' field. Cannot specify both. Example with command:\nmcp-servers:\n %s:\n command: \"npx @my/tool\"\n args: [\"--port\", \"3000\"]\n\nExample with container:\nmcp-servers:\n %s:\n container: \"myorg/my-tool:latest\"\n env:\n API_KEY: \"${{ secrets.API_KEY }}\"", toolName, toolName, toolName) | |
| return config, fmt.Errorf( | |
| "stdio MCP tool '%s' must specify either 'command' or 'container' field. Cannot specify both. "+ | |
| "Example with command:\n"+ | |
| "mcp-servers:\n"+ | |
| " %s:\n"+ | |
| " command: \"npx @my/tool\"\n"+ | |
| " args: [\"--port\", \"3000\"]\n\n"+ | |
| "Example with container:\n"+ | |
| "mcp-servers:\n"+ | |
| " %s:\n"+ | |
| " container: \"myorg/my-tool:latest\"\n"+ | |
| " env:\n"+ | |
| " API_KEY: \"${{ secrets.API_KEY }}\"", | |
| toolName, toolName, toolName, | |
| ) |
Contributor
Author
There was a problem hiding this comment.
Fixed in commit d57732e. Error message reformatted with proper line breaks for better readability.
pkg/parser/mcp.go
Outdated
| config.URL = urlStr | ||
| } else { | ||
| return config, fmt.Errorf("url must be a string") | ||
| return config, fmt.Errorf("url field must be a string, got %T. Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", url, toolName) |
There was a problem hiding this comment.
[nitpick] Long error message line: This error message exceeds typical line length limits. Consider breaking it into multiple lines for better code readability.
Suggested formatting:
return config, fmt.Errorf("url field must be a string, got %T. Example:\n"+
"mcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n"+
" headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", url, toolName)
Suggested change
| return config, fmt.Errorf("url field must be a string, got %T. Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", url, toolName) | |
| return config, fmt.Errorf( | |
| "url field must be a string, got %T. Example:\n"+ | |
| "mcp-servers:\n"+ | |
| " %s:\n"+ | |
| " type: http\n"+ | |
| " url: \"https://api.example.com/mcp\"\n"+ | |
| " headers:\n"+ | |
| " Authorization: \"Bearer ${{ secrets.API_KEY }}\"", | |
| url, toolName) |
pkg/parser/mcp.go
Outdated
| } | ||
| } else { | ||
| return config, fmt.Errorf("http type requires 'url' field") | ||
| return config, fmt.Errorf("http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", toolName, toolName) |
There was a problem hiding this comment.
[nitpick] Long error message line: This error message exceeds typical line length limits. Consider breaking it into multiple lines for better code readability.
Suggested formatting:
return config, fmt.Errorf("http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. "+
"Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n"+
" headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", toolName, toolName)
Suggested change
| return config, fmt.Errorf("http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", toolName, toolName) | |
| return config, fmt.Errorf( | |
| "http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. "+ | |
| "Example:\n"+ | |
| "mcp-servers:\n"+ | |
| " %s:\n"+ | |
| " type: http\n"+ | |
| " url: \"https://api.example.com/mcp\"\n"+ | |
| " headers:\n"+ | |
| " Authorization: \"Bearer ${{ secrets.API_KEY }}\"", | |
| toolName, toolName, | |
| ) |
pkg/workflow/mcp-config.go
Outdated
| result.URL = url | ||
| } else { | ||
| return nil, fmt.Errorf("http MCP tool '%s' missing required 'url' field", toolName) | ||
| return nil, fmt.Errorf("http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", toolName, toolName) |
There was a problem hiding this comment.
[nitpick] Long error message line: This error message exceeds typical line length limits. Consider breaking it into multiple lines for better code readability.
Suggested formatting:
return nil, fmt.Errorf("http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. "+
"Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n"+
" headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", toolName, toolName)
Suggested change
| return nil, fmt.Errorf("http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. Example:\nmcp-servers:\n %s:\n type: http\n url: \"https://api.example.com/mcp\"\n headers:\n Authorization: \"Bearer ${{ secrets.API_KEY }}\"", toolName, toolName) | |
| return nil, fmt.Errorf( | |
| "http MCP tool '%s' missing required 'url' field. HTTP MCP servers must specify a URL endpoint. "+ | |
| "Example:\n"+ | |
| "mcp-servers:\n"+ | |
| " %s:\n"+ | |
| " type: http\n"+ | |
| " url: \"https://api.example.com/mcp\"\n"+ | |
| " headers:\n"+ | |
| " Authorization: \"Bearer ${{ secrets.API_KEY }}\"", | |
| toolName, toolName, | |
| ) |
Contributor
Author
There was a problem hiding this comment.
Fixed in commit d57732e. Error message reformatted across multiple lines.
Contributor
|
@copilot merge main and lint |
- Merged main branch - Reformatted long error message lines for better readability - Split multi-line error messages across multiple lines with proper indentation - All error messages maintain the three-part template structure - Tests continue to pass - Linting passes Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Contributor
Author
Copilot finished work on behalf of
pelikhan
November 15, 2025 18:03
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
MCP Configuration Error Message Improvements ✅
Successfully improved all MCP (Model Context Protocol) configuration error messages to follow the error message style guide's three-part template: what's wrong + what's expected + example.
Summary of Changes
Files Modified
pkg/workflow/mcp-config.go- 4 error messages improved and reformattedpkg/parser/mcp.go- 11 error messages improved and reformattedpkg/workflow/mcp_error_messages_test.go- Comprehensive test suite (380+ lines)Recent Updates (Latest Commit)
Error Messages Enhanced
pkg/workflow/mcp-config.go:
pkg/parser/mcp.go:
%T) and exampleKey Improvements
%TTesting
All tests continue to pass:
Verification
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.