Code Sandbox MCP Server

Instructions

Implementation Reference

• src/code_sandbox_mcp/server.py:43-62 (handler)

  The @mcp.tool() decorated function serving as both the handler and registration for the 'run_javascript_code' tool. It validates input via Annotated Field, executes the code using the run_code helper with language='javascript', handles output and errors, and returns TextContent.

  @mcp.tool()
  def run_javascript_code(
      code: Annotated[
          str,
          Field(
              description=f"The JavaScript code to execute, included libraries are {DEFAULT_ENVIRONMENT_MAP['javascript']['installed_libraries']}",
          ),
      ],
  ) -> TextContent:
      """Execute JavaScript code in the sandbox environment and captures the standard output and error."""
      try:
          result = run_code(code, language="javascript")
          if len(result) == 0:
              result = ExecutionResult(
                  exit_code=1, stderr="No output, forgot console.logs?"
              ).to_json()
          return TextContent(text=result, type="text")
      except Exception as e:
          result = ExecutionResult(exit_code=1, stderr=str(e)).to_json()
          return TextContent(text=result, type="text")

• src/code_sandbox_mcp/utils.py:25-78 (helper)

  Core helper function run_code that performs the actual code execution in a secure sandbox using llm_sandbox.SandboxSession, configured for the specified language (including 'javascript'), handling environment setup, libraries, and timeouts.

  def run_code(
      code: str,
      language: Literal["python", "javascript"] = DEFAULT_LANGUAGE,
      image: str | None = None,
      libraries: list[str] | None = None,
      timeout: int = EXECUTION_TIMEOUT,
  ) -> str:
      """Execute code in a secure sandbox environment and automatic visualization capture.
  
      Args:
          code: The code to execute
          language: Programming language (python, javascript, go)
          libraries: List of libraries/packages to install
          image: Docker image to use for the sandbox session
          timeout: Execution timeout in seconds (default: 30)
  
      Returns:
          List of content items including execution results and any generated visualizations
  
      """
      if language not in DEFAULT_ENVIRONMENT_MAP:
          raise ValueError(f"Language {language} not supported")
  
      session_args = {
          "lang": language,
          "keep_template": True,
          "verbose": VERBOSE,
          "backend": _get_backend(),
          "session_timeout": timeout,
          "image": DEFAULT_ENVIRONMENT_MAP[language]["image"],
      }
  
      if os.getenv("PASSTHROUGH_ENV", None):
          env_vars = {}
          for var in os.getenv("PASSTHROUGH_ENV", None).split(","):
              env_vars[var] = os.getenv(var)
          session_args["runtime_configs"] = {"environment": env_vars}
  
      if os.getenv("CONTAINER_IMAGE", None) and os.getenv("CONTAINER_LANGUAGE", None):
          session_args["lang"] = os.getenv("CONTAINER_LANGUAGE")
          session_args["image"] = os.getenv("CONTAINER_IMAGE")
  
      if libraries:
          session_args["libraries"] = libraries
  
      with SandboxSession(**session_args) as session:
          result = session.run(
              code=code,
              libraries=libraries or [],
              timeout=timeout,
          )
      if result.exit_code != 0:
          raise Exception(result.stderr.strip())
      return result.stdout.strip()

• src/code_sandbox_mcp/server.py:45-50 (schema)

  Pydantic-based input schema definition for the tool, specifying the 'code' parameter as a string with description of supported JavaScript libraries.

  code: Annotated[
      str,
      Field(
          description=f"The JavaScript code to execute, included libraries are {DEFAULT_ENVIRONMENT_MAP['javascript']['installed_libraries']}",
      ),
  ],

• src/code_sandbox_mcp/server.py:43-43 (registration)

  The @mcp.tool() decorator registers the run_javascript_code function as an MCP tool.

  @mcp.tool()