Add MCP runtime config foundation

[Flames4fun]

Refs
#96

Describe the changes you have made in this PR -

This PR is the first of three planned pull requests toward resolving the MCP host/runtime support issue.

The issue asks the harness to move beyond the current MCP workflow adapter and define the first full-host MCP execution path. The complete issue includes keeping MCP dependencies optional, safely starting configured fixture servers or connecting to configured local servers, translating MCP tool calls into canonical mcp/<server_id>/<tool_name> trace entries, adding local fixture tests with no external services or credentials, and updating docs/mcp-adapter-design.md once implementation choices are made.

This PR intentionally does not complete the full issue. It prepares the configuration and dependency foundation needed for the following MCP host work while preserving the current --mcp-target workflow behavior.

Why this work is split into three PRs

The full MCP host/runtime work crosses several areas of the project: runtime configuration, optional dependency management, process execution, MCP SDK integration, trace translation, fixture servers, CLI/runner wiring, and documentation.

Splitting the implementation into three PRs keeps the work easier to review, lowers regression risk, and lets reviewers validate each layer before the next one depends on it.

The planned sequence is:

1. PR 1: Runtime configuration foundation

   • Add validated MCP runtime configuration primitives.
   • Keep the existing MCP workflow adapter unchanged.
   • Keep MCP dependencies optional.
   • Add focused tests for config validation and dependency detection.

2. PR 2: Minimal stdio host execution

   • Add the first real MCP host execution path.
   • Start configured local stdio fixture servers safely.
   • Initialize MCP sessions through the optional SDK.
   • Support deterministic fixture target execution.
   • Translate observed MCP tool calls into canonical trace entries.

3. PR 3: CLI, documentation, and final integration

   • Add or complete user-facing CLI/runner wiring.
   • Update docs/mcp-adapter-design.md with the implementation choices.
   • Update adapter documentation and README status.
   • Add final end-to-end coverage for the agreed workflow.

What this PR includes

This PR adds the MCP runtime configuration foundation.

Files changed:

• src/agent_harness/mcp_runtime.py
• tests/test_mcp_runtime.py
• pyproject.toml

Runtime configuration module

This PR introduces:

• MCPServerConfig
• MCPRuntimeConfig
• MCPHostRuntime
• load_mcp_runtime_config(...)
• parse_mcp_runtime_config(...)
• ensure_mcp_sdk_available(...)

The accepted runtime config shape is intentionally list-based:

servers:
  - id: filesystem_fixture
    transport: stdio
    command: python
    args:
      - tests/fixtures/mcp_servers/filesystem_server.py
    timeout_seconds: 5

The list shape is deliberate. It allows the harness to reliably detect duplicate server_id values before runtime execution starts. Mapping-shaped server definitions are rejected because YAML mappings can collapse duplicate keys before the harness has a chance to validate them.

Validation decisions

This PR validates:

• server_id is required
• server_id must be non-empty
• server_id must not contain /
• duplicate server_id values fail
• servers must be a list
• empty server lists fail
• transport is required
• only stdio is supported for now
• command is required for stdio
• args must be a list
• every args entry must be a string
• timeout_seconds defaults to a safe value
• timeout_seconds must be greater than zero

These validations are intentionally conservative because this configuration will later control local process startup for MCP fixture servers.

Dependency strategy

MCP dependencies remain optional.

The base package still does not import or require the MCP SDK. The new runtime module checks for the SDK lazily through ensure_mcp_sdk_available(...) and raises a clear AdapterError with installation guidance when the SDK is unavailable.

The mcp extra now installs the SDK with a bounded range:

mcp = ["mcp>=1.12.4,<2"]

The aggregate adapters extra includes the same optional MCP dependency:

adapters = ["openai-agents", "langchain", "langgraph", "mcp>=1.12.4,<2"]

This keeps the base install lightweight while making the MCP install hint actionable.

What this PR intentionally does not include

This PR does not add:

• new CLI flags
• runner integration
• real MCP sessions
• stdio server startup
• MCP fixture servers
• list_tools
• call_tool
• resource support
• prompt support
• HTTP transport support
• trace format changes
• large documentation rewrites

Those items are intentionally left for the following PRs so this foundation remains small and auditable.

Tests and checks run

• python -m pytest tests\test_mcp_runtime.py
• python -m pytest tests\test_mcp_adapter.py
• python -m pytest
• python -m compileall -q src\agent_harness tests

---

Code Understanding and AI Usage

Did you use AI assistance (ChatGPT, Claude, Copilot, etc.) to write any part of this code or documentation ?

• No, I wrote all the code myself
• Yes, I used AI assistance

If you used AI assistance, briefly describe:

• Tool(s) used: ChatGPT / Codex
• Parts of the contribution that were AI-assisted:
  • MCP runtime configuration structure
  • Validation test coverage
• How you reviewed the output:
  • Reviewed the changes against the issue requirements, the existing MCP adapter behavior, and the planned three-PR implementation split.
  • Confirmed that the existing --mcp-target workflow remains unchanged.
  • Confirmed that MCP SDK usage remains lazy and optional.
• Tests or checks I ran:
  • python -m pytest tests\test_mcp_runtime.py
  • python -m pytest tests\test_mcp_adapter.py
  • python -m pytest
  • python -m compileall -q src\agent_harness tests

---

Checklist before requesting a review

• I have added proper PR title and linked to the issue
• I have performed a self-review of my code
• I can explain the purpose of every documentation, function, class, and logic block I added
• I understand why my changes work and have tested them thoroughly
• I have considered potential edge cases and how my code handles them
• If it is a core feature, I have added thorough tests
• My code follows the project's style guidelines and conventions