Change mcp_servers map to single mcp_server configuration object in rules only (#164)

* Initial plan

* Convert mcp_servers map to single mcp_server string field

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Clarify MCPServer() comment about rules being ignored

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Change mcp_servers map to single mcp_server config object

Convert from map of server configs to single MCPServerConfig object.
Each task/rule now specifies one MCP server configuration with
standard fields (command, args, env, type, url, headers) plus
arbitrary custom fields via the Content map.

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Remove empty MCP server detection checks

Remove the empty server detection logic from MCPServers() method
as requested. The agent will handle filtering empty configs. Updated
tests to expect empty MCPServerConfig structs in the returned slice.

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Remove MCPServer field from TaskFrontMatter

Tasks no longer have mcp_server field. MCP servers are now only
specified in rules. Result.MCPServers() now only returns configs
from rules. Updated tests, examples, and documentation.

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Merge main branch and resolve conflicts

Fetched from main and merged to resolve conflicts. All conflicts resolved:
- Removed old task_frontmatter.go and rule_frontmatter.go files
- Applied changes to new pkg/codingcontext/markdown/frontmatter.go structure
- Removed MCPServer field from TaskFrontMatter
- Changed RuleFrontMatter.MCPServers to MCPServer (single config)
- Updated Result.MCPServers() to return []mcp.MCPServerConfig from rules only
- Updated all tests to match new structure
- All tests pass, linter passes

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Update examples/agents/tasks/example-mcp-arbitrary-fields.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update examples/agents/tasks/example-mcp-arbitrary-fields.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Filter empty MCP configs and fix documentation

- Filter out empty MCP server configs in MCPServers() method
- Only return configs with Command or URL set
- Update tests to expect empty configs to be filtered
- Remove duplicate standard fields list from example doc
- Add documentation that empty configs are filtered

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
Co-authored-by: Alex Collins <alexec@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

docs/reference/file-formats.md

@@ -137,35 +137,6 @@ timeout: 10m
 - `1h` - 1 hour
 - `1h30m` - 1 hour 30 minutes
 
-#### `mcp_servers` (optional, standard field)
-
-**Type:** Map (from server name to server configuration)  
-**Purpose:** Specifies the MCP (Model Context Protocol) servers that the task should use; stored in frontmatter output but does not filter rules
-
-The `mcp_servers` field is a **standard frontmatter field** following the industry standard for MCP server definition. It does not act as a selector. The field is a map where keys are server names and values are server configurations.
-
-**Example:**
-```yaml
----
-mcp_servers:
-  filesystem:
-    type: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
-  git:
-    type: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-git"]
-  database:
-    type: http
-    url: https://api.example.com/mcp
-    headers:
-      Authorization: Bearer token123
----
-```
-
-**Note:** The format follows the MCP specification for server identification. Each server configuration includes a `type` field (e.g., "stdio", "http", "sse") and other fields specific to that transport type.
-
 #### `agent` (optional, standard field)
 
 **Type:** String  
@@ -625,25 +596,38 @@ agent: cursor
 - If task/CLI specifies `agent: cursor`, only rules with `agent: cursor` or no agent field are included
 - Rules without an agent field are considered generic and always included (unless other selectors exclude them)
 
-#### `mcp_servers` (rule metadata)
+#### `mcp_server` (rule metadata)
 
-Specifies MCP servers that need to be running for this rule. Does not filter rules. The field is a map where keys are server names and values are server configurations.
+Specifies an MCP server configuration for this rule. Each rule can specify one MCP server configuration with standard and arbitrary custom fields. Does not filter rules.
+
+**Important:** MCP servers are specified in rules only, not in tasks. Tasks select rules (and thus MCP servers) via selectors.
 
 ```yaml
 ---
-mcp_servers:
-  filesystem:
-    type: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-filesystem"]
-  database:
-    type: http
-    url: https://api.example.com/mcp
+mcp_server:
+  command: python
+  args: ["-m", "server"]
+  env:
+    PYTHON_PATH: /usr/bin/python3
+  custom_config:
+    host: localhost
+    port: 5432
 ---
-# Metadata indicating required MCP servers
+# Rule with MCP server configuration
 ```
 
-**Note:** This field is informational and does not affect rule selection.
+**Standard configuration fields:**
+- `command`: The executable to run (e.g., "npx", "python", "docker")
+- `args`: Array of command-line arguments
+- `env`: Map of environment variables
+- `type`: Connection protocol - "stdio" (default), "http", or "sse"
+- `url`: Endpoint URL (required for HTTP/SSE types)
+- `headers`: Custom HTTP headers (for HTTP/SSE types)
+
+**Additional arbitrary fields:**
+You can include any custom fields for your specific server needs (e.g., `custom_config`, `monitoring`, `cache_enabled`, etc.). All fields are preserved in the configuration.
+
+**Note:** This field is metadata and does not affect rule selection.
 
 #### `expand` (optional)
 

examples/agents/tasks/example-mcp-arbitrary-fields.md

@@ -1,62 +1,58 @@
 ---
 task_name: example-mcp-arbitrary-fields
 agent: cursor
-mcp_servers:
-  # Example with standard fields only
-  filesystem:
-    type: stdio
-    command: filesystem
-  
-  # Example with standard fields plus arbitrary custom fields
-  custom-database:
-    type: stdio
-    command: database-mcp
-    args: ["--verbose"]
-    # Arbitrary fields below
-    cache_enabled: true
-    max_cache_size: 1000
-    connection_pool_size: 10
-    
-  # Example HTTP server with custom metadata
-  api-server:
-    type: http
-    url: https://api.example.com
-    headers:
-      Authorization: Bearer token123
-    # Arbitrary fields below
-    api_version: v2
-    rate_limit: 100
-    timeout_seconds: 30
-    retry_policy: exponential
-    region: us-west-2
-    
-  # Example with nested custom configuration
-  advanced-server:
-    type: stdio
-    command: python
-    args: ["-m", "server"]
-    env:
-      PYTHON_PATH: /usr/bin/python3
-    # Arbitrary nested fields below
-    custom_config:
-      host: localhost
-      port: 5432
-      ssl: true
-      pool:
-        min: 2
-        max: 10
-    monitoring:
-      enabled: true
-      metrics_port: 9090
 ---
 
-# Example Task with Arbitrary MCP Server Fields
+# Example Rule with MCP Server Configuration
+
+This example demonstrates how rules can specify MCP server configuration with arbitrary custom fields.
+
+Note: MCP servers are specified in rules, not in tasks. Tasks can select which rules (and thus which MCP servers) to use via selectors.
+
+## The `mcp_server` Field in Rules
+
+Rules can specify a single MCP server configuration with both standard and arbitrary custom fields.
+
+The `mcp_server` field, when present in a rule, specifies that rule's single MCP server configuration with both standard and arbitrary custom fields. Tasks cannot define MCP servers directly.
+
+**Standard fields:**
+- `command`: The executable to run (e.g., "python", "npx", "docker")
+- `args`: Array of command-line arguments
+- `env`: Environment variables for the server process
+- `type`: Connection protocol ("stdio", "http", "sse") - optional, defaults to stdio
+- `url`: Endpoint URL for HTTP/SSE types
+- `headers`: Custom HTTP headers for HTTP/SSE types
+
+## Example Rule with MCP Server
+
+```yaml
+---
+rule_name: python-mcp-server
+mcp_server:
+  command: python
+  args: ["-m", "server"]
+  env:
+    PYTHON_PATH: /usr/bin/python3
+  custom_config:
+    host: localhost
+    port: 5432
+    ssl: true
+    pool:
+      min: 2
+      max: 10
+  monitoring:
+    enabled: true
+    metrics_port: 9090
+---
+
+# Python MCP Server Rule
 
-This task demonstrates the ability to add arbitrary fields to MCP server configurations, just like we can with FrontMatter.
+This rule provides the Python MCP server configuration.
+```
 
 ## Why Arbitrary Fields?
 
-Different MCP servers may need different configuration options beyond the standard fields (`type`, `command`, `args`, `env`, `url`, `headers`). Arbitrary fields allow you to:
+Different MCP servers may need different configuration options beyond the standard fields. Arbitrary fields allow you to:
 
 1. **Add custom metadata**: Version info, regions, endpoints, etc.
 2. **Configure behavior**: Caching, retry policies, timeouts, rate limits
@@ -65,7 +61,7 @@ Different MCP servers may need different configuration options beyond the standa
 
 ## How It Works
 
-The `MCPServerConfig` struct now includes a `Content` field (similar to `BaseFrontMatter`) that captures all fields from YAML/JSON:
+The `MCPServerConfig` struct includes a `Content` field that captures all fields from YAML/JSON:
 
 ```go
 type MCPServerConfig struct {
@@ -82,12 +78,4 @@ type MCPServerConfig struct {
 }
 ```
 
-## Example Usage
-
-The examples above show:
-- **Simple custom fields**: `cache_enabled`, `max_cache_size`
-- **API configuration**: `api_version`, `rate_limit`, `timeout_seconds`
-- **Nested objects**: `custom_config` with sub-fields like `host`, `port`, `ssl`
-- **Multiple custom sections**: `custom_config` and `monitoring` as separate objects
-
-All these fields are preserved when the configuration is parsed and can be accessed via the `Content` map.
+All fields (both standard and custom) are preserved when the configuration is parsed and can be accessed via the struct fields or the `Content` map.

examples/agents/tasks/example-with-standard-fields.md

@@ -5,13 +5,6 @@ language: go
 model: anthropic.claude-sonnet-4-20250514-v1-0
 single_shot: false
 timeout: 10m
-mcp_servers:
-  filesystem:
-    type: stdio
-    command: filesystem
-  git:
-    type: stdio
-    command: git
 selectors:
   stage: implementation
 ---
@@ -34,7 +27,6 @@ These fields are stored in frontmatter and passed through to output, but do NOT
 - **model**: `anthropic.claude-sonnet-4-20250514-v1-0` - AI model to use for this task
 - **single_shot**: `false` - Task can be run multiple times
 - **timeout**: `10m` - Task timeout as time.Duration (10 minutes)
-- **mcp_servers**: `[filesystem, git]` - MCP servers required for this task
 
 ## Custom Selectors
 

pkg/codingcontext/README.md

@@ -116,8 +116,8 @@ func main() {
 
     // Access MCP server configurations
     mcpServers := result.MCPServers()
-    for name, config := range mcpServers {
-        fmt.Printf("MCP Server %s: %s\n", name, config.Command)
+    for i, config := range mcpServers {
+        fmt.Printf("MCP Server %d: %s\n", i, config.Command)
     }
 }
 ```
@@ -139,7 +139,7 @@ Result holds the assembled context from running a task:
 - `Agent Agent` - The agent used (from task frontmatter or option)
 
 **Methods:**
-- `MCPServers() MCPServerConfigs` - Returns all MCP server configurations from rules and task
+- `MCPServers() []MCPServerConfig` - Returns all MCP server configurations from rules as a slice
 
 #### `Markdown[T]`
 

pkg/codingcontext/markdown/frontmatter.go

@@ -35,10 +35,6 @@ type TaskFrontMatter struct {
 	// Does not filter rules, metadata only
 	Timeout string `yaml:"timeout,omitempty" json:"timeout,omitempty"`
 
-	// MCPServers maps server names to their configurations
-	// Does not filter rules, metadata only
-	MCPServers mcp.MCPServerConfigs `yaml:"mcp_servers,omitempty" json:"mcp_servers,omitempty"`
-
 	// Resume indicates if this task should be resumed
 	Resume bool `yaml:"resume,omitempty" json:"resume,omitempty"`
 
@@ -120,9 +116,9 @@ type RuleFrontMatter struct {
 	// Agent specifies which AI agent this rule is intended for
 	Agent string `yaml:"agent,omitempty" json:"agent,omitempty"`
 
-	// MCPServers maps server names to their configurations
+	// MCPServer specifies a single MCP server configuration
 	// Metadata only, does not filter
-	MCPServers mcp.MCPServerConfigs `yaml:"mcp_servers,omitempty" json:"mcp_servers,omitempty"`
+	MCPServer mcp.MCPServerConfig `yaml:"mcp_server,omitempty" json:"mcp_server,omitempty"`
 
 	// RuleName is an optional identifier for the rule file
 	RuleName string `yaml:"rule_name,omitempty" json:"rule_name,omitempty"`

pkg/codingcontext/markdown/frontmatter_rule_test.go

@@ -51,11 +51,10 @@ agent: cursor
 				TaskNames: []string{"test-task"},
 				Languages: []string{"go", "python"},
 				Agent:     "copilot",
-				MCPServers: mcp.MCPServerConfigs{
-					"database": {
-						Type:    mcp.TransportTypeStdio,
-						Command: "database-server",
-					},
+				MCPServer: mcp.MCPServerConfig{
+					Type:    mcp.TransportTypeStdio,
+					Command: "database-server",
+					Args:    []string{"--port", "5432"},
 				},
 				RuleName: "test-rule",
 			},
@@ -65,10 +64,12 @@ languages:
 - go
 - python
 agent: copilot
-mcp_servers:
-  database:
-    type: stdio
-    command: database-server
+mcp_server:
+  type: stdio
+  command: database-server
+  args:
+  - --port
+  - "5432"
 rule_name: test-rule
 `,
 		},

pkg/codingcontext/markdown/frontmatter_task_test.go

@@ -4,7 +4,6 @@ import (
 	"testing"
 
 	"github.com/goccy/go-yaml"
-	"github.com/kitproj/coding-context-cli/pkg/codingcontext/mcp"
 )
 
 func TestTaskFrontMatter_Marshal(t *testing.T) {
@@ -33,11 +32,7 @@ func TestTaskFrontMatter_Marshal(t *testing.T) {
 				Model:      "gpt-4",
 				SingleShot: true,
 				Timeout:    "10m",
-				MCPServers: mcp.MCPServerConfigs{
-					"filesystem": {Type: mcp.TransportTypeStdio, Command: "filesystem-server"},
-					"git":        {Type: mcp.TransportTypeStdio, Command: "git-server"},
-				},
-				Resume: false,
+				Resume:     false,
 				Selectors: map[string]any{
 					"stage": "implementation",
 				},
@@ -49,13 +44,6 @@ languages:
 model: gpt-4
 single_shot: true
 timeout: 10m
-mcp_servers:
-  filesystem:
-    type: stdio
-    command: filesystem-server
-  git:
-    type: stdio
-    command: git-server
 selectors:
   stage: implementation
 `,
@@ -142,13 +130,6 @@ languages:
 model: gpt-4
 single_shot: true
 timeout: 10m
-mcp_servers:
-  filesystem:
-    type: stdio
-    command: filesystem-server
-  git:
-    type: stdio
-    command: git-server
 selectors:
   stage: implementation
 `,
@@ -161,10 +142,6 @@ selectors:
 				Model:      "gpt-4",
 				SingleShot: true,
 				Timeout:    "10m",
-				MCPServers: mcp.MCPServerConfigs{
-					"filesystem": {Type: mcp.TransportTypeStdio, Command: "filesystem-server"},
-					"git":        {Type: mcp.TransportTypeStdio, Command: "git-server"},
-				},
 				Selectors: map[string]any{
 					"stage": "implementation",
 				},