feat: add mcp_servers to agent.yaml for portable MCP server definitions

[chr1syy]

Summary

• Adds mcp_servers field to agent.yaml so MCP servers can be defined once and exported to each provider's native configuration format
• Supports both stdio-based servers (command + args) and HTTP-based servers (url + headers)
• Tier 1 adapters export native MCP config JSON: Claude Code (.mcp.json), Cursor (.cursor/mcp.json), Gemini (.gemini/settings.json), Codex (codex.json), OpenCode (opencode.json)
• Tier 2 adapters document MCP servers in markdown instructions: system-prompt, copilot, openai, crewai, lyzr, nanobot, openclaw
• Fixes pre-existing duplicate .requiredOption bugs in export/import commands

Closes #57

Test plan

• 51 tests pass (20 new MCP-specific tests + 31 existing)
• TypeScript builds cleanly
• gitagent validate passes on updated examples/full/agent.yaml
• Manual: export with mcp_servers defined for each format, verify output contains correct MCP config

🤖 Generated with Claude Code

[shreyas-lyzr]

Apologies for the slow review — this should not have sat for a month.

Brutally honest review: this is excellent and on-spec. mcp_servers is the right shape, in the right place, with the right schema.

What I love:

• oneOf between command-based (stdio) and url-based (HTTP/SSE) servers is exactly the MCP protocol's split. additionalProperties: false keeps it tight.
• The ${VAR} interpolation pattern in env and headers matches what we already do elsewhere — consistent.
• buildMcpServersConfig and buildMcpServersMarkdown in shared.ts are the right factoring. JSON-shaped adapters (claude-code, codex, cursor) get the structured config; markdown-shaped adapters (copilot, crewai) get a human-readable section. The right thing.
• The split of exportToClaudeCode into a structured object ({instructions, mcpConfig}) and a string variant (exportToClaudeCodeString) is a real improvement — it lets Claude Code's adapter write CLAUDE.md AND .mcp.json separately, which is what Claude Code actually wants.
• Schema first, adapters second. Good order.

Things I want to confirm before merge:

1. Validate against examples/full/agent.yaml. The example you added uses both stdio (command: npx) and HTTP (url:) variants. A gapman validate examples/full/ should pass after this lands.
2. Does it touch existing exports? Cursor, copilot, crewai already exported successfully; the addition is appended. Worth a quick check that the existing examples (examples/standard/, examples/llm-wiki/) without mcp_servers still export with no change in output bytes.
3. No corresponding import support yet. Not a blocker — import reads framework-native files; mcp_servers is a new field gitagent introduces, so there's no source to import from. But a follow-up that reads .mcp.json from a Claude Code source would be a natural next PR.

Recommendation: merge. I'd like to see CI green on this branch (it currently shows no checks — possibly needs a rebase to pick up the workflow). If @chr1syy can rebase on main and the build passes, I'll merge same-day.

Real apologies for the delay, and thank you for shipping this — mcp_servers is one of the most-asked-for features.

[shreyas-lyzr]

Picking this back up — apologies for the longer-than-promised wait after my Apr-3 review.

Re-read the diff against current main:

• Schema is right (oneOf between command-based stdio and url-based HTTP/SSE; additionalProperties: false; ${VAR} interpolation pattern matches the rest of the spec).
• buildMcpServersConfig and buildMcpServersMarkdown in shared.ts are the right factoring — JSON-shaped adapters get the structured config; markdown adapters get a human-readable section.
• The exportToClaudeCode split into {instructions, mcpConfig} + a separate exportToClaudeCodeString wrapper is a real improvement — it lets the export emit CLAUDE.md AND .mcp.json separately.
• Threaded cleanly through claude-code, codex, cursor (structured) and copilot, crewai (markdown).

Merging. Will add the corresponding import direction (read .mcp.json from a Claude Code source → populate agent.yaml: mcp_servers) as a follow-up issue.

Closes #57. Thank you for the patience.