Scriptling Scriptling

scriptling.mcp.tool

MCP tool helper library for authoring MCP tools in scriptling. This sub-library provides functions for parameter access and result handling when implementing tool scripts.

For the MCP client library (connecting to MCP servers), see scriptling.mcp.

Enabling

The tool helpers are a separate, optional sub-library. Register it explicitly when needed:

mcp.RegisterToolHelpers(sl)  // Registers scriptling.mcp.tool

Environment Variables

MCP tool helpers read and write environment variables set by the MCP tool execution environment:

  • __mcp_params: Dictionary containing tool parameters.
  • __mcp_response: String containing the tool’s result.

Available Functions

Function Description
get_int(name, default=0) Get an integer parameter
get_float(name, default=0.0) Get a float parameter
get_string(name, default="") Get a string parameter (trims whitespace)
get_bool(name, default=False) Get a boolean parameter
get_list(name, default=None) Get a list parameter (splits strings by comma)
get_string_list(name, default=None) Get a string array parameter
get_int_list(name, default=None) Get an integer array parameter
get_float_list(name, default=None) Get a float array parameter
get_bool_list(name, default=None) Get a boolean array parameter
return_string(text) Return a string result and stop execution
return_object(obj) Return an object as JSON and stop execution
return_toon(obj) Return an object as TOON and stop execution
return_error(message) Return an error message and stop execution

Parameter Access Functions

mcp.tool.get_int(name, default=0)

Gets an integer parameter from the tool’s input arguments. Returns the default value if the parameter doesn’t exist or can’t be coerced to an integer.

Parameters:

  • name (str): Parameter name.
  • default (int, optional): Default value if the parameter is missing. Default: 0.

Returns: int

import scriptling.mcp.tool as tool

project_id = tool.get_int("project_id", 0)
limit = tool.get_int("limit", 100)

mcp.tool.get_float(name, default=0.0)

Gets a float parameter from the tool’s input arguments. Returns the default value if the parameter doesn’t exist or can’t be coerced to a float.

Parameters:

  • name (str): Parameter name.
  • default (float, optional): Default value if the parameter is missing. Default: 0.0.

Returns: float

import scriptling.mcp.tool as tool

price = tool.get_float("price", 0.0)
percentage = tool.get_float("percentage", 100.0)

mcp.tool.get_string(name, default="")

Gets a string parameter from the tool’s input arguments. Automatically trims whitespace, and returns the default value if the parameter doesn’t exist, is empty, or is whitespace-only.

Parameters:

  • name (str): Parameter name.
  • default (str, optional): Default value if the parameter is missing or empty. Default: "".

Returns: str

import scriptling.mcp.tool as tool

name = tool.get_string("name", "guest")
query = tool.get_string("query")

mcp.tool.get_bool(name, default=False)

Gets a boolean parameter from the tool’s input arguments. Handles "true"/"false" strings (case-insensitive) and numeric 0/1.

Parameters:

  • name (str): Parameter name.
  • default (bool, optional): Default value if the parameter is missing or can’t be converted. Default: False.

Returns: bool

import scriptling.mcp.tool as tool

enabled = tool.get_bool("enabled", True)
verbose = tool.get_bool("verbose")

mcp.tool.get_list(name, default=None)

Gets a list parameter from the tool’s input arguments. If the value is a string, splits it by comma.

Parameters:

  • name (str): Parameter name.
  • default (list, optional): Default value if the parameter is missing. Default: empty list.

Returns: list

import scriptling.mcp.tool as tool

ids = tool.get_list("ids")              # "1,2,3" → ["1", "2", "3"]
tags = tool.get_list("tags", ["all"])   # "tag1, tag2" → ["tag1", "tag2"]

mcp.tool.get_string_list(name, default=None)

Gets a string array parameter (array:string type) from the tool’s input arguments.

Parameters:

  • name (str): Parameter name.
  • default (list, optional): Default value if the parameter is missing. Default: empty list.

Returns: list of str

import scriptling.mcp.tool as tool

args = tool.get_string_list("arguments")  # ["--verbose", "-o", "file.txt"]
tags = tool.get_string_list("tags", ["default"])

mcp.tool.get_int_list(name, default=None)

Gets an integer array parameter (array:int type) from the tool’s input arguments.

Parameters:

  • name (str): Parameter name.
  • default (list, optional): Default value if the parameter is missing. Default: empty list.

Returns: list of int

import scriptling.mcp.tool as tool

ids = tool.get_int_list("ids")  # [1, 2, 3, 4]
ports = tool.get_int_list("ports", [8080])

mcp.tool.get_float_list(name, default=None)

Gets a float array parameter (array:float type) from the tool’s input arguments.

Parameters:

  • name (str): Parameter name.
  • default (list, optional): Default value if the parameter is missing. Default: empty list.

Returns: list of float

import scriptling.mcp.tool as tool

prices = tool.get_float_list("prices")  # [19.99, 29.99, 39.99]
weights = tool.get_float_list("weights", [1.0])

mcp.tool.get_bool_list(name, default=None)

Gets a boolean array parameter (array:bool type) from the tool’s input arguments.

Parameters:

  • name (str): Parameter name.
  • default (list, optional): Default value if the parameter is missing. Default: empty list.

Returns: list of bool

import scriptling.mcp.tool as tool

flags = tool.get_bool_list("flags")  # [true, false, true]
options = tool.get_bool_list("options", [False])

Result Functions

Result functions set the tool’s response and immediately stop script execution using SystemExit. No code after these calls will execute.

mcp.tool.return_string(text)

Returns a string result and stops execution.

Parameters:

  • text (str): The result text.

Returns: None: execution stops before returning to caller.

import scriptling.mcp.tool as tool

tool.return_string("Search completed successfully")
# Code here will not execute

mcp.tool.return_object(obj)

Returns an object as JSON and stops execution.

Parameters:

  • obj (dict or list): The result object.

Returns: None: execution stops before returning to caller.

import scriptling.mcp.tool as tool

tool.return_object({"status": "success", "count": 42})
# Code here will not execute

mcp.tool.return_toon(obj)

Returns an object encoded as TOON (compact text format optimized for LLMs) and stops execution.

Parameters:

  • obj (dict or list): The result object.

Returns: None: execution stops before returning to caller.

import scriptling.mcp.tool as tool

tool.return_toon({"result": data})
# Code here will not execute

mcp.tool.return_error(message)

Returns an error message and stops execution with error code 1.

Parameters:

  • message (str): Error message.

Returns: None: execution stops before returning to caller.

import scriptling.mcp.tool as tool

if not customer_id:
    tool.return_error("Customer ID is required")
    # Code here will not execute

tool.return_error("Customer not found")

Complete Tool Example

# Recommended: import as alias (cleanest)
import scriptling.mcp.tool as tool

# Get parameters with defaults
name = tool.get_string("name", "guest")
age = tool.get_int("age", 0)
verbose = tool.get_bool("verbose", False)

# Validate inputs
if age < 0:
    tool.return_error("Age must be positive")

# Process and return result
result = {
    "greeting": f"Hello, {name}!",
    "age": age,
    "category": "adult" if age >= 18 else "minor"
}

if verbose:
    import time
    result["timestamp"] = time.time()

tool.return_object(result)

Usage in Tool Scripts

When implementing MCP tools, the execution environment sets __mcp_params before running your script:

# Tool script: greet_user.py
import scriptling.mcp.tool as tool

name = tool.get_string("name", "guest")
age = tool.get_int("age", 0)

tool.return_object({
    "message": f"Hello, {name}! You are {age} years old."
})

The tool execution environment will:

  1. Set the __mcp_params dict with tool parameters.
  2. Run the script.
  3. Catch the SystemExit exception from return_* functions.
  4. Extract the result from __mcp_response.
  5. Return it to the MCP client.

Go Helper Function

For Go applications that need to run MCP tool scripts, the RunToolScript helper function simplifies the process:

import (
    "context"
    "github.com/paularlott/scriptling"
    "github.com/paularlott/scriptling/extlibs/mcp"
)

// Create scriptling instance and register tool helpers
sl := scriptling.New()
mcp.RegisterToolHelpers(sl)

// Define tool script
script := `
import scriptling.mcp.tool as tool

name = tool.get_string("name", "guest")
age = tool.get_int("age", 0)

tool.return_object({
    "message": f"Hello, {name}! You are {age} years old."
})
`

// Run the tool with parameters
params := map[string]interface{}{
    "name": "Alice",
    "age":  30,
}

response, exitCode, err := mcp.RunToolScript(context.Background(), sl, script, params)
// response: JSON string with the result
// exitCode: 0 for success, 1 for error
// err: Go error if execution failed

Function signature:

func RunToolScript(
    ctx context.Context,
    sl *scriptling.Scriptling,
    script string,
    params map[string]interface{}
) (response string, exitCode int, err error)

Parameters:

  • ctx: Context for cancellation and timeouts.
  • sl: Scriptling instance (must have tool helpers registered).
  • script: The tool script code.
  • params: Map of parameter name to value.

Returns:

  • response: The tool response from __mcp_response (usually JSON).
  • exitCode: 0 for success, 1 for error.
  • err: Go error if execution failed (nil for exitCode 0).

Best Practices

  1. Always use defaults: Provide sensible default values for optional parameters.
  2. Validate early: Check required parameters and return errors immediately.
  3. Return quickly: Use return_* functions as soon as you have a result.
  4. Handle errors: Use return_error() for user-facing error messages.
  5. Choose the right format: Use return_string for text, return_object for structured data, return_toon for LLM-optimized output.

Security Considerations

This is an extended library, requiring registration in Go, see Library Registration.

scriptling.mcp.tool itself has no implicit network, filesystem, or process access: it only reads __mcp_params and writes __mcp_response. Risk depends entirely on what the tool script you write does with those parameters.

See Also