Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Chebaleomkar wants to merge 2 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19cd1bd
fix(tools): handle binary output and truncate large command results
Chebaleomkar Feb 4, 2026
ebdd31b
docs: fix MCP configuration paths and document platform differences
Chebaleomkar Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions .cursor/mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,28 @@
{
"mcpServers": {
"agent-builder": {
"command": "python",
"args": ["-m", "framework.mcp.agent_builder_server"],
"command": "uv",
"args": [
"run",
"-m",
"framework.mcp.agent_builder_server"
],
"cwd": "core",
"env": {
"PYTHONPATH": "../tools/src"
"PYTHONPATH": ".:../tools/src"
}
},
"tools": {
"command": "python",
"args": ["mcp_server.py", "--stdio"],
"command": "uv",
"args": [
"run",
"mcp_server.py",
"--stdio"
],
"cwd": "tools",
"env": {
"PYTHONPATH": "src"
"PYTHONPATH": "src:../core"
}
}
}
}
}
24 changes: 19 additions & 5 deletions .mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,27 @@
"mcpServers": {
"agent-builder": {
"command": "uv",
"args": ["run", "-m", "framework.mcp.agent_builder_server"],
"cwd": "core"
"args": [
"run",
"-m",
"framework.mcp.agent_builder_server"
],
"cwd": "core",
"env": {
"PYTHONPATH": ".:../tools/src"
}
},
"tools": {
"command": "uv",
"args": ["run", "mcp_server.py", "--stdio"],
"cwd": "tools"
"args": [
"run",
"mcp_server.py",
"--stdio"
],
"cwd": "tools",
"env": {
"PYTHONPATH": "src:../core"
}
}
}
}
}
31 changes: 26 additions & 5 deletions ENVIRONMENT_SETUP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -439,18 +439,39 @@ PYTHONPATH=core:tools/src python your_script.py

### MCP Server Configuration

The `.mcp.json` at project root configures MCP servers to use their respective virtual environments:
The `.mcp.json` at project root configures MCP servers. Using `uv` is the recommended way as it handles cross-platform path differences automatically:

```json
{
"mcpServers": {
"agent-builder": {
"command": "core/.venv/bin/python",
"args": ["-m", "framework.mcp.agent_builder_server"]
"command": "uv",
"args": ["run", "-m", "framework.mcp.agent_builder_server"],
"cwd": "core"
},
"tools": {
"command": "tools/.venv/bin/python",
"args": ["-m", "aden_tools.mcp_server", "--stdio"]
"command": "uv",
"args": ["run", "mcp_server.py", "--stdio"],
"cwd": "tools"
}
}
}
```

If you are not using `uv`, you must use the absolute or relative path to the Python executable in the virtual environment. Note that the path differs between Linux/macOS and Windows:

- **Linux/macOS:** `core/.venv/bin/python` or `.venv/bin/python`
- **Windows:** `core/.venv/Scripts/python.exe` or `.venv/Scripts/python.exe`

Example of manual configuration (Windows):

```json
{
"mcpServers": {
"agent-builder": {
"command": "core/.venv/Scripts/python.exe",
"args": ["-m", "framework.mcp.agent_builder_server"],
"cwd": "core"
}
}
}
Expand Down
52 changes: 49 additions & 3 deletions tools/src/aden_tools/tools/file_system_toolkits/execute_command_tool/execute_command_tool.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,39 @@

from ..security import WORKSPACES_DIR, get_secure_path

# Output truncation limit (in characters)
# This prevents memory issues and LLM context window overflow
MAX_OUTPUT_LENGTH = 5000 # ~5KB per stream (stdout/stderr)

# Truncation marker appended when output exceeds limit
TRUNCATION_MARKER = "\n... [output truncated, exceeded {limit} characters]"


def _safe_decode(data: bytes, max_length: int = MAX_OUTPUT_LENGTH) -> tuple[str, bool]:
"""
Safely decode bytes to string with truncation.

Handles binary/non-UTF-8 data gracefully by using error replacement,
and truncates large output to prevent context overflow.

Args:
data: Raw bytes from subprocess
max_length: Maximum output length in characters

Returns:
Tuple of (decoded_string, was_truncated)
"""
# Decode with error replacement to handle binary/non-UTF-8 data safely
# This replaces invalid bytes with the Unicode replacement character (�)
text = data.decode("utf-8", errors="replace")

# Truncate if necessary
if len(text) > max_length:
truncated_text = text[:max_length] + TRUNCATION_MARKER.format(limit=max_length)
return truncated_text, True

return text, False


def register_tools(mcp: FastMCP) -> None:
"""Register command execution tools with the MCP server."""
Expand All @@ -26,6 +59,7 @@ def execute_command_tool(
No network access unless explicitly allowed
No destructive commands (rm -rf, system modification)
Output must be treated as data, not truth
Output is truncated to ~5KB per stream to prevent context overflow

Args:
command: The shell command to execute
Expand All @@ -47,17 +81,29 @@ def execute_command_tool(
else:
secure_cwd = session_root

# Capture as bytes to avoid UnicodeDecodeError on binary output
result = subprocess.run(
command, shell=True, cwd=secure_cwd, capture_output=True, text=True, timeout=60
command,
shell=True,
cwd=secure_cwd,
capture_output=True,
text=False, # Capture bytes, not text - prevents encoding errors
timeout=60,
)

# Safely decode and truncate output
stdout, stdout_truncated = _safe_decode(result.stdout)
stderr, stderr_truncated = _safe_decode(result.stderr)

return {
"success": True,
"command": command,
"return_code": result.returncode,
"stdout": result.stdout,
"stderr": result.stderr,
"stdout": stdout,
"stderr": stderr,
"cwd": cwd or ".",
"stdout_truncated": stdout_truncated,
"stderr_truncated": stderr_truncated,
}
except subprocess.TimeoutExpired:
return {"error": "Command timed out after 60 seconds"}
Expand Down
75 changes: 75 additions & 0 deletions tools/tests/tools/test_file_system_toolkits.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -589,6 +589,81 @@ def test_execute_command_with_pipe(self, execute_command_fn, mock_workspace, moc
assert result["return_code"] == 0
assert "HELLO WORLD" in result["stdout"]

def test_execute_command_binary_output_safe_decode(
self, execute_command_fn, mock_workspace, mock_secure_path, tmp_path
):
"""Executing a command with binary output handles encoding gracefully.

Regression test for issue #3486: UnicodeDecodeError on binary output.
The tool should use errors='replace' to safely decode binary data.
"""
import sys

# Create a binary file with non-UTF-8 bytes
binary_file = tmp_path / "binary.bin"
binary_file.write_bytes(b"\x80\x81\x82\xff\xfeHello\x00\x01World")

if sys.platform == "win32":
command = f"type {binary_file}"
else:
command = f"cat {binary_file}"

result = execute_command_fn(command=command, **mock_workspace)

# Should NOT crash with UnicodeDecodeError
assert result["success"] is True
# Output should contain the readable parts (with replacement chars for invalid bytes)
assert "Hello" in result["stdout"] or "World" in result["stdout"]
# Truncation flags should be present
assert "stdout_truncated" in result
assert "stderr_truncated" in result

def test_execute_command_large_output_truncation(
self, execute_command_fn, mock_workspace, mock_secure_path
):
"""Executing a command with large output truncates it safely.

Regression test for issue #3486: Large output causing context overflow.
The tool should limit output to MAX_OUTPUT_LENGTH (~5KB).
"""
import sys

# Generate large output (> 5KB)
if sys.platform == "win32":
# PowerShell command to generate ~10KB of output
command = 'powershell -Command "1..200 | ForEach-Object { \'Line \' + $_ + \': This is a test line with some content to make it longer\' }"'
else:
command = "yes 'This is a test line with some content' | head -n 200"

result = execute_command_fn(command=command, **mock_workspace)

assert result["success"] is True
assert result["return_code"] == 0

# Check that output was truncated
from aden_tools.tools.file_system_toolkits.execute_command_tool.execute_command_tool import (
MAX_OUTPUT_LENGTH,
)

# If output was large enough to trigger truncation
if result.get("stdout_truncated", False):
assert len(result["stdout"]) <= MAX_OUTPUT_LENGTH + 100 # Allow for truncation marker
assert "[output truncated" in result["stdout"]

def test_execute_command_truncation_flags_present(
self, execute_command_fn, mock_workspace, mock_secure_path
):
"""Executing any command includes truncation status flags in response."""
result = execute_command_fn(command="echo 'short output'", **mock_workspace)

assert result["success"] is True
# New fields should always be present
assert "stdout_truncated" in result
assert "stderr_truncated" in result
# Short output should not be truncated
assert result["stdout_truncated"] is False
assert result["stderr_truncated"] is False


class TestApplyDiffTool:
"""Tests for apply_diff tool."""
Expand Down