Skip to content

docs: fix MCP configuration paths and document platform differences#3500

Closed
Chebaleomkar wants to merge 2 commits intoadenhq:mainfrom
Chebaleomkar:docs/fix-mcp-config-paths
Closed

docs: fix MCP configuration paths and document platform differences#3500
Chebaleomkar wants to merge 2 commits intoadenhq:mainfrom
Chebaleomkar:docs/fix-mcp-config-paths

Conversation

@Chebaleomkar
Copy link

Description

This PR fixes configuration issues and path documentation for MCP servers, specifically addressing mismatches when running on Windows. It standardized configuration to use uv run for better cross-platform compatibility and updates documentation to guide users through environment-specific path requirements.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)

Related Issues

Fixes #3484

Changes Made

  • Standardized MCP Config: Updated .mcp.json and .cursor/mcp.json to use uv run. This eliminates the need for platform-specific binary paths (e.g., bin/python vs Scripts/python.exe).
  • Improved Documentation: Added a specific section in ENVIRONMENT_SETUP.md explaining how to configure MCP servers manually on both Windows and Linux/macOS.
  • Enhanced PYTHONPATH: Added explicit PYTHONPATH exports in the MCP server configurations to ensure cross-package discovery (linking core and tools) works out of the box.

Testing

  • Unit tests pass (N/A for docs, but verified uv run logic locally)
  • Lint passes (N/A for config/docs)
  • Manual testing performed: Verified that the uv run command successfully spawns the MCP server on Windows, whereas the old .venv/bin/python path failed.

Checklist

  • My code follows the project's style guidelines
  • I have performed a self-review of my code
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • New and existing unit tests pass locally with my changes

Screenshots (if applicable)

(None required for documentation and configuration fixes)

Fixes adenhq#3486. Captures bytes to prevent UnicodeDecodeError and truncates stdout/stderr to 5KB to avoid LLM context overflow.
Fixes adenhq#3484. Updates .mcp.json and .cursor/mcp.json to use uv for cross-platform robustness. Added platform-specific path guidance for Windows in ENVIRONMENT_SETUP.md and improved PYTHONPATH handling.
@Som-0619
Copy link

Som-0619 commented Feb 4, 2026

can i work on this to complete the remaining tasks....need assign tag

@Cn8001
Copy link

Cn8001 commented Feb 4, 2026

This PR does not completely solves the issue. I think it occurs mainly because of claude code's bug as well as Python path. I can continue and change the configuration according to related issues #3484 and #2903,needed assignment. @bryanadenhq

@Chebaleomkar
Copy link
Author

Chebaleomkar commented Feb 4, 2026

I have reproduced the bug and wrote tests . @bryanadenhq @Cn8001

@Cn8001
Copy link

Cn8001 commented Feb 4, 2026

@Chebaleomkar , sure it was same for me, but sometimes claude code ignores/crashes when "cwd" option is there and that breaks it again as seen in this bug.

@PatrickChen928
Copy link
Collaborator

Thanks for your contribution.
This issue should have been fixed in #3455

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

.mcp.json in CLI mode path change

4 participants