README - codebench-mcp by mark3labs

JavaScript Executor MCP Server

This MCP server provides JavaScript execution capabilities with a modern runtime.

Features

The executeJS tool provides:

Console API: console.log(), console.error(), console.warn() (built-in)
HTTP Server: serve() for server creation (via require('http/server'))
Fetch API: Modern fetch() with Request, Response, Headers, FormData (global)
Timers: setTimeout(), setInterval(), clearTimeout(), clearInterval() (global)
Buffer: Buffer, Blob, File APIs for binary data handling (global)
Crypto: Cryptographic functions - hashing, encryption, HMAC (via require('crypto'))
Cache: In-memory caching with TTL support (via require('cache'))
Additional modules: encoding (global), url (global)

Getting Started

Installation

Using Go Install

go install github.com/mark3labs/codebench-mcp@latest

Usage

As a standalone server

codebench-mcp

With module configuration

# Enable only specific modules
codebench-mcp --enabled-modules http,fetch

# Disable specific modules (enable all others)
codebench-mcp --disabled-modules timers

# Set custom execution timeout (in seconds)
codebench-mcp --execution-timeout 600  # 10 minutes

# Show help
codebench-mcp --help

Available modules:

http - HTTP server creation and client requests (require('http/server'))
fetch - Modern fetch API with Request, Response, Headers, FormData (available globally)
timers - setTimeout, setInterval, clearTimeout, clearInterval (available globally)
buffer - Buffer, Blob, File APIs for binary data handling (available globally)
cache - In-memory caching with TTL support (require('cache'))
crypto - Cryptographic functions (hashing, encryption, HMAC) (require('crypto'))
encoding - TextEncoder, TextDecoder for text encoding/decoding (available globally)
url - URL and URLSearchParams APIs (available globally)

All modules are enabled by default. You can selectively enable or disable modules using CLI flags.

Note: The executeJS tool description dynamically updates to show only the enabled modules and includes detailed information about what each module provides.

As a library in your Go project

package main

import (
	"log"

	"github.com/mark3labs/codebench-mcp/server"
	"github.com/mark3labs/mcp-go/server"
)

func main() {
	// Create a new JavaScript executor server
	jss, err := server.NewJSServer()
	if err != nil {
		log.Fatalf("Failed to create server: %v", err)
	}

	// Serve requests
	if err := server.ServeStdio(jss); err != nil {
		log.Fatalf("Server error: %v", err)
	}
}

Using InProcessTransport

package main

import (
	"context"
	"log"

	"github.com/mark3labs/codebench-mcp/server"
	"github.com/mark3labs/mcp-go/client"
	"github.com/mark3labs/mcp-go/mcp"
)

func main() {
	// Create the JS server with custom module configuration
	config := server.ModuleConfig{
		EnabledModules: []string{"fetch", "crypto", "buffer"},
	}
	jsServer, err := server.NewJSServerWithConfig(config)
	if err != nil {
		log.Fatalf("Failed to create server: %v", err)
	}

	// Create an in-process client
	mcpClient, err := client.NewInProcessClient(jsServer)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer mcpClient.Close()

	// Start the client
	if err := mcpClient.Start(context.Background()); err != nil {
		log.Fatalf("Failed to start client: %v", err)
	}

	// Initialize the client
	initRequest := mcp.InitializeRequest{}
	initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
	initRequest.Params.ClientInfo = mcp.Implementation{
		Name:    "my-app",
		Version: "1.0.0",
	}
	_, err = mcpClient.Initialize(context.Background(), initRequest)
	if err != nil {
		log.Fatalf("Failed to initialize: %v", err)
	}

	// Execute JavaScript code
	callRequest := mcp.CallToolRequest{}
	callRequest.Params.Name = "executeJS"
	callRequest.Params.Arguments = map[string]any{
		"code": `
			console.log("Hello from JavaScript!");
			const result = Math.sqrt(16);
			console.log("Square root of 16 is:", result);
			result;
		`,
	}

	result, err := mcpClient.CallTool(context.Background(), callRequest)
	if err != nil {
		log.Fatalf("Failed to call tool: %v", err)
	}

	if result.IsError {
		log.Printf("JavaScript execution error: %v", result.Content)
	} else {
		log.Printf("JavaScript execution result: %v", result.Content)
	}
}

Usage with Model Context Protocol

To integrate this server with apps that support MCP:

{
  "mcpServers": {
    "javascript": {
      "command": "codebench-mcp"
    }
  }
}

Docker

Running with Docker

You can run the JavaScript Executor MCP server using Docker:

docker run -i --rm ghcr.io/mark3labs/codebench-mcp:latest

Docker Configuration with MCP

To integrate the Docker image with apps that support MCP:

{
  "mcpServers": {
    "javascript": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mark3labs/codebench-mcp:latest"
      ]
    }
  }
}

Tool Reference

executeJS

Execute JavaScript code with a modern runtime environment.

Parameters:

code (required): JavaScript code to execute

Configuration:

Default execution timeout: 5 minutes
Configurable via --execution-timeout <seconds> CLI flag

Example:

console.log("Hello, World!");

// Basic JavaScript execution
const result = 2 + 3;
console.log('Result:', result);

// Fetch API (available globally when enabled)
const response = await fetch('https://api.example.com/data');
const data = await response.json();

// HTTP server (require import)
const serve = require('http/server');
serve(8000, async (req) => {
  return new Response('Hello World');
});

// Cache operations (require import)
const cache = require('cache');
cache.set('key', 'value');
console.log(cache.get('key'));

// Crypto operations (require import)
const crypto = require('crypto');
const hash = crypto.md5('hello').hex();
console.log('MD5 hash:', hash);

// Timers (available globally)
setTimeout(() => console.log('Hello after 1 second'), 1000);

// Buffer operations (available globally)
const buffer = Buffer.from('hello', 'utf8');
console.log(buffer.toString('base64'));

// URL operations (available globally)
const url = new URL('https://example.com/path?param=value');
console.log('Host:', url.host);
console.log('Pathname:', url.pathname);

Limitations

No fs or process modules - File system and process APIs are not available in the runtime
Module access varies - Some modules are global (fetch, http), others may need require()
Each execution creates a fresh VM - For isolation, each execution starts with a clean state
Module filtering - Configuration exists but actual runtime filtering not fully implemented
Execution timeout - JavaScript execution is limited by configurable timeout (default: 5 minutes)

Building

go build -o codebench-mcp .

License

See the file for details.