feat: JavaScript Code Execution Tool with Full Observability

[Dumbris]

Summary

This PR implements a production-ready JavaScript code execution feature that allows LLM agents to orchestrate multiple upstream MCP tools in a single request using sandboxed JavaScript (ES5.1+). This significantly reduces round-trip latency and enables complex multi-step workflows with conditional logic, loops, and data transformations.

Key Features

Core Functionality

• Sandboxed JavaScript execution using Goja (ES5.1+ compatible)
• call_tool() function for invoking upstream MCP servers from JavaScript
• Execution limits: timeout, max_tool_calls, allowed_servers
• Concurrent execution pool with configurable size (default: 10 instances)
• Feature toggle: disabled by default for security (enable_code_execution: false)

Observability (Completed in this PR)

• ✅ execution_id tracking for complete log correlation
• ✅ Pool metrics: size, available instances, in-use count
• ✅ Duration tracking: acquisition, release, and execution times
• ✅ Tool call metrics: individual timing and result logging
• ✅ Thread-safe collection of all metrics

Security

• Sandbox restrictions: No require(), filesystem, or network access
• Timeout enforcement: Watchdog goroutine with configurable limits (default: 2 minutes, max: 10 minutes)
• Server whitelist: Optional allowed_servers per request
• Max tool calls limit: Prevents abuse and infinite loops
• Quarantine integration: Respects existing server quarantine status

Developer Experience

• CLI command: mcpproxy code exec with comprehensive flags
• Documentation: 4 comprehensive guides
  • Overview (architecture, patterns, best practices)
  • Examples (13 working code samples)
  • API Reference (complete schema, error codes, CLI reference)
  • Troubleshooting (common issues, solutions, debugging)
• Test coverage: 19 unit tests with 100% pass rate

Configuration

{
  "enable_code_execution": false,
  "code_execution_timeout_ms": 120000,
  "code_execution_max_tool_calls": 0,
  "code_execution_pool_size": 10
}

Example Usage

# Execute JavaScript code
mcpproxy code exec --code "return input.a + input.b" --input '{"a":1,"b":2}'

# Multi-tool orchestration
mcpproxy code exec --file workflow.js --input-file data.json

JavaScript Example:

// Orchestrate multiple tools in a single request
var fileList = call_tool('filesystem', 'list_directory', {path: '/project'});
if (!fileList.ok) {
  return {error: 'Failed to list files'};
}

var results = [];
for (var i = 0; i < fileList.result.files.length; i++) {
  var analysis = call_tool('ast-grep', 'analyze', {
    file: fileList.result.files[i]
  });
  if (analysis.ok) {
    results.push(analysis.result);
  }
}

return {analyzed: results.length, results: results};

Test Plan

• All 19 unit tests pass (runtime, pool, integration)
• Pool concurrency tested with 50 concurrent goroutines
• Timeout enforcement verified (100ms precision)
• Sandbox restrictions validated
• Observability metrics confirmed in logs
• CLI command tested with all flags
• Documentation reviewed and verified

Implementation Status

Completion: 100% (Production-Ready)

See IMPLEMENTATION_STATUS.md for detailed breakdown.

Files Changed

New Files

• internal/jsruntime/ - JavaScript runtime package (errors, pool, runtime)
• internal/server/mcp_code_execution.go - MCP tool handler with observability
• cmd/mcpproxy/code_cmd.go - CLI command implementation
• docs/code_execution/ - Complete documentation suite
• specs/001-code-execution/ - Feature specification and tracking

Modified Files

• internal/config/config.go - Configuration support
• internal/server/mcp.go - Tool registration
• internal/server/server.go - Pool lifecycle integration
• CLAUDE.md - Development documentation

Success Metrics

All critical success criteria met:

• ✅ SC-001: Multi-tool orchestration < 30s
• ✅ SC-002: 10 concurrent requests
• ✅ SC-003: 100% timeout violations terminated
• ✅ SC-004: Feature toggle rejection
• ✅ SC-005: Complete stack traces
• ✅ SC-006: 100% execution logging
• ✅ SC-008: 100% sandbox prevention
• ✅ SC-009: 95%+ valid requests succeed
• ✅ SC-011: CLI response < 10s
• ✅ SC-012: 100% CLI exit codes
• ✅ SC-013: 5+ documentation examples (13 provided)

🤖 Generated with Claude Code

[github-actions]

📦 Build Artifacts for PR #138

Version: v0.9.29-dev-8cc4f67-pr138
Latest tag: v0.9.29

Available Artifacts

• frontend-dist-pr (178 KB)
• archive-linux-amd64 (12 MB)
• archive-linux-arm64 (10 MB)
• archive-windows-amd64 (22 MB)
• archive-windows-arm64 (19 MB)
• archive-darwin-arm64 (20 MB)
• installer-dmg-darwin-arm64 (22 MB)
• archive-darwin-amd64 (22 MB)
• installer-dmg-darwin-amd64 (24 MB)

How to Download

Option 1: GitHub Web UI (easiest)

1. Go to the workflow run page
2. Scroll to the bottom "Artifacts" section
3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 19395037238 --repo smart-mcp-proxy/mcpproxy-go

# Or download a specific artifact:
gh run download 19395037238 --name dmg-darwin-arm64

Note: Artifacts expire in 14 days.