Windows MCP System Health guide: address remaining PR #277 review feedback

[itomek]

Summary

PR #277 (MCP Client Support) received several review comments specific to the Windows MCP System Health guide and example script. The WindowsApiToolsMixin and PowershellToolsMixin items have been split into #332 and #333 respectively. This issue tracks the remaining unresolved feedback.

Files affected:

• docs/guides/mcp/windows-system-health.mdx (guide, recently moved from docs/guides/windows-mcp-system-health.mdx)
• examples/mcp_windows_system_health_agent.py (example agent script)
• pyproject.toml (project configuration)

Tasks

1. Add link to the Windows MCP server repository

The guide should prominently link to the upstream Windows MCP server package/repository so users can review it before running. The "Next Steps" section already has a card pointing to https://github.com/nicholasxjy/windows-mcp but the reviewer expected a more visible link earlier in the guide (e.g., in the intro or Quick Start).

File: docs/guides/mcp/windows-system-health.mdx

---

2. Remove prerequisites section and point to setup.mdx

The guide currently has a <Note> pointing to the Setup Guide, but the reviewer wants any remaining inline prerequisites removed entirely and replaced with a single pointer to docs/setup.mdx. Additionally, verify whether Python 3.13 is truly required or if 3.12+ is sufficient. The example docstring says "Python 3.12+" which aligns with the project's uv.lock (requires-python = ">=3.12").

Files: docs/guides/mcp/windows-system-health.mdx, examples/mcp_windows_system_health_agent.py

Acceptance criteria:

• No inline prerequisite list in the guide; single reference to /setup page
• Confirm and document minimum Python version (3.12 vs 3.13)

---

3. Fix requires-python warning when running examples with uv run

Running uv run examples/mcp_windows_system_health_agent.py produces:

warning: No 'requires-python' value found in the workspace. Defaulting to '>=3.12'.

The project's uv.lock has requires-python = ">=3.12" but pyproject.toml may be missing the explicit declaration.

File: pyproject.toml

Acceptance criteria:

• uv run examples/mcp_windows_system_health_agent.py runs without the requires-python warning
• The requires-python value is explicitly set in pyproject.toml

---

4. Fix MCP server connection error and misleading error message

The reviewer encountered:

Error during initialization: Server closed connection
Failed to connect to MCP server 'windows'

When connection fails, the example script prints:

print("  Ensure 'uvx' is installed: pip install uv")

This is misleading because GAIA uses uv, not pip. The pip install uv suggestion does not work inside the GAIA venv. The reviewer got it working by creating a separate Python 3.13 venv explicitly.

File: examples/mcp_windows_system_health_agent.py (line 77)

Acceptance criteria:

• Investigate why the default venv fails to connect (Python version mismatch? missing dependency?)
• Fix the error message to not suggest pip install uv
• Provide actionable troubleshooting guidance in the error output (e.g., check Python version, verify uvx availability)
• Document any Python version constraints specific to the Windows MCP server

---

5. Include uv venv setup instructions in guide

The reviewer got the example working by creating a dedicated venv with Python 3.13. If the Windows MCP server requires a specific Python version, the guide should include explicit uv venv setup instructions.

File: docs/guides/mcp/windows-system-health.mdx

Acceptance criteria:

• If Python 3.13 is required by the Windows MCP server, document uv venv creation with explicit Python version
• If 3.12 works, document that and remove any 3.13 references

---

6. Add a video demo

The reviewer requested a video demonstration of the agent in action.

File: docs/guides/mcp/windows-system-health.mdx (the "See It In Action" section)

Acceptance criteria:

• Record a short video showing the full agent workflow (prompt -> metrics collection -> Notepad output)
• Embed the video in the "See It In Action" section of the guide

---

7. Fix Notepad appending to pre-existing file

When the agent opens Notepad, it appends the report to a pre-existing file if Notepad was previously opened. The agent should create a new file instead of reusing an existing Notepad instance.

File: examples/mcp_windows_system_health_agent.py (system prompt in _get_system_prompt(), around line 126)

Acceptance criteria:

• Agent opens a NEW Notepad instance with a fresh/empty file (e.g., Start-Process notepad with no file argument, or generate a temp file path)
• If an existing Notepad window is open, the agent should not paste into it
• Update the system prompt instructions for Step 5 accordingly

---

8. Add section on discovering and integrating more MCP servers

The reviewer wants guidance on where to find additional MCP servers and how to integrate them into GAIA agents. The guide already has a "Where to Get More Servers" section with cards linking to MCP Server Hub and official servers, but it lacks:

• Step-by-step instructions for adding a new MCP server to an agent
• Security warnings about vetting third-party servers

File: docs/guides/mcp/windows-system-health.mdx

Acceptance criteria:

• Add brief step-by-step instructions showing how to add a new MCP server (the connect_mcp_server() call pattern)
• Include security warning about vetting third-party MCP servers before use (can expand the existing "Security Considerations" section)
• Reference the MCP Client guide (/guides/mcp/client) for full details

Context

• PR: MCP Client Support: Connect GAIA agents to any MCP server #277 (MCP Client Support: Connect GAIA agents to any MCP server)
• Related issues: Add WindowsApiToolsMixin for native Windows API tools (bypass MCP server overhead) #332 (WindowsApiToolsMixin), Add PowershellToolsMixin for direct PowerShell execution in agents #333 (PowershellToolsMixin) -- already split out
• Branch: 203-mcp-client-support-connect-gaia-agents-to-any-mcp-server