examples/

Scriptling Examples

This directory contains examples and tools for working with Scriptling.

Structure

• scripts/ - Script examples and test files

  • main.go - Go integration example for running scripts
  • *.py - Various Scriptling example scripts (basics, features, libraries, etc.)
  • run_all_examples.sh - Script to run all examples

• background/ - Runtime library background tasks and concurrency example

  • example.py - Demonstrates background tasks, runtime.run(), sync primitives, KV store
  • README.md - Background tasks documentation

• databases/ - Database plugin examples (sqlite, sql, valkey, badger)

  • *.py - Runnable scripts covering both API shapes; README.md has container commands for local test servers
  • README.md - Database examples documentation

• mcp-client/ - MCP client examples

  • with-openai/ - Using MCP tools through an OpenAI client
  • direct/ - Direct MCP server connection
  • README.md - MCP client examples documentation

• mcp-per-user-tools/ - Per-user MCP tool sets via middleware

  • setup.py, auth.py, usertools.py, tools/ - Middleware authenticates each caller and registers the MCP tools, resources and prompts they are allowed to see
  • README.md - Per-user tools documentation

• openai/ - AI library examples with OpenAI-compatible APIs

  • shared/ - Using shared client configured in Go
  • instance/ - Creating client from script
  • streaming/ - Streaming chat completions
  • scriptlingcoder/ - AI coding assistant with custom tools (⚠️ executes AI code)
  • README.md - OpenAI examples documentation

• extending/ - Example of extending Scriptling with custom Go functions

  • main.go - Go integration example
  • README.md - Extension documentation

• script-metadata/ - Example of checking a script's inline metadata block before running it

  • main.go - Host version check, dependency resolution, and a refused missing-plugin run

• logging/ - Example of using the logging library

  • main.go - Go integration with logging
  • example.py - Scriptling logging example

• multi-environment/ - Example of using multiple isolated Scriptling environments

  • main.go - Go integration example
  • README.md - Multi-environment documentation

• call_method/ - Example of calling methods on Scriptling objects from Go

  • main.go - Go integration example
  • README.md - Method calling documentation

• custom_io/ - Example of custom input/output handling

  • main.go - Go integration example
  • README.md - Custom I/O documentation

• http-server/ - Example of using the HTTP server library

  • main.go - Go integration example
  • README.md - HTTP server documentation

• net/ - Networking library examples (scriptling.net.*)

  • net/multicast/ - UDP multicast group messaging
    • multicast_demo.py - Join a multicast group, send and receive messages
    • README.md - Multicast library documentation
  • net/unicast/ - UDP and TCP point-to-point messaging
    • tcp_echo.py - TCP echo server and client
    • udp_ping_pong.py - UDP ping-pong example
    • README.md - Unicast library documentation
  • net/gossip/ - Gossip protocol cluster membership and messaging
    • gossip_demo.py - Single-node metadata and introspection demo
    • gossip_cluster.py - Two-node cluster with message passing
    • gossip_nodegroups.py - Metadata-criteria-based node groups
    • gossip_leader.py - Leader election and failover
    • gossip_request_reply.py - Request/reply messaging pattern
    • gossip_advanced.py - Advanced config and event handlers
    • README.md - Gossip library documentation

• mcp-tools/ - Example MCP tools for use with the CLI MCP server

  • *.toml - Tool metadata files
  • *.py - Tool implementation scripts
  • README.md - MCP tools documentation

• mcp-decorated/ - Every MCP entry kind registered from one decorated .py file

  • tools/shop.py - @mcp.tool, @mcp.resource (static + template), @mcp.prompt and @mcp.skill together
  • client.py - lists and exercises them all over stdio
  • README.md - what it demonstrates

• mcp-app-package/ - A complete MCP app packaged as one zip: app view, plain tools, prompt and skill

  • manifest.toml + setup.py - serve = ["mcp"], convention directories for the rest
  • client.py - verification client run against the built package
  • README.md - build, run and prove

• mcp-resources-prompts/ - Tools, resources and prompts served as files, no Go code

  • tools/, resources/, prompts/ - one file per entry, live-reloaded
  • README.md - file conventions for each MCP primitive

• mcp-app-dashboard/ - An MCP Apps example: a tool linked to an interactive UI resource

  • tools/*.toml + .py - sales_report / add_sale, .toml-defined with [ui] linkage
  • resources/ui/sales-dashboard/ - the dashboard UI (AlpineJS + Chart.js) and its [ui.csp] metadata
  • README.md - what it demonstrates and how to test it against the Go host-simulator harness

• mcp-prize-wheel/ - A second MCP Apps example using the decorator style instead of .toml

  • tools/prize_wheel.py - spin_wheel / claim_prize, both @mcp.tool(..., ui={...})-decorated, no .toml file
  • resources/ui/prize-wheel/ - an animated SVG prize wheel, pure vanilla JS
  • README.md - what it demonstrates, differences from mcp-app-dashboard

• telegram-bot/ - Example Telegram bot using Scriptling

  • main.go - Go integration example
  • README.md - Telegram bot documentation

• fs/ - Binary file I/O with the fs library

  • read_gguf.py - Parse GGUF (LLM model) file headers
  • read_wav.py - Parse WAV audio file headers
  • read_png.py - Parse PNG image file headers
  • README.md - fs library documentation

• math/ - Linear algebra and advanced math functions

  • neural_network.py - Neural network forward pass using matmul, tanh, softmax
  • matrix_ops.py - Matrix multiplication, transpose, addition, dot product
  • README.md - math library documentation

• random/ - Random number generation and distributions

  • distributions.py - Weighted sampling, Monte Carlo, distribution sampling, card dealing
  • README.md - random library documentation

Running Script Examples

cd scripts
go run main.go example_basics.py
go run main.go test_all_features.py
./run_all_examples.sh

Runtime Library Example

Demonstrates background tasks, concurrent execution, synchronization primitives, and KV store:

# Build CLI first (from repo root)
task build

# Run the example
./bin/scriptling examples/background/example.py

See background/README.md for details.

AI/MCP Examples

OpenAI Examples

Examples demonstrating the AI library with OpenAI-compatible APIs (including LM Studio).

# Shared client pattern (client configured in Go)
cd openai/shared
go run main.go

# Instance pattern (client created from script)
cd openai/instance
go run main.go

# Streaming responses
cd openai/streaming
go run main.go

# AI coding assistant with custom tools (⚠️ WARNING: executes AI-generated code)
cd openai/scriptlingcoder
../../../bin/scriptling scriptlingcoder.py

See openai/README.md for details and prerequisites.

MCP Client Examples

Examples demonstrating MCP (Model Context Protocol) client usage.

# Using MCP tools through an OpenAI client
cd mcp-client/with-openai
go run main.go

# Direct MCP server connection
cd mcp-client/direct
go run main.go

Prerequisites: Start an MCP server first (e.g., using the CLI with --server :8000 --mcp-tools ./tools).

Example Scripts

The scripts/ directory contains numerous examples covering:

• Basics: example_basics.py, example_control_flow.py, example_loops.py
• Functions: example_functions.py, example_lambda.py, example_variadic_args.py
• Data Types: example_tuples.py, example_collections.py, example_list_comprehensions.py
• Libraries: example_lib_*.py - Examples for various libraries (json, regex, math, etc.)
• HTTP: example_lib_http.py, rest_api.py
• Async: example_async.py
• And many more...

Other Examples

See individual example directories for more details:

• background/README.md - Background tasks and concurrency
• call_method/README.md - Calling methods on Scriptling objects
• custom_io/README.md - Custom input/output handling
• extending/README.md - Extending Scriptling with Go
• http-server/README.md - HTTP server library
• logging/ - Logging library example
• mcp-client/README.md - MCP client examples
• mcp-tools/README.md - MCP tools examples
• mcp-decorated/README.md - Tool, resource, prompt and skill all registered with decorators from one .py file
• mcp-app-package/README.md - A complete MCP app (app view, tools, prompt, skill) packaged and verified from the zip
• mcp-resources-prompts/README.md - Tools, resources and prompts as files, no Go code
• mcp-app-dashboard/README.md - MCP Apps: a .toml-linked tool with an interactive UI
• mcp-prize-wheel/README.md - MCP Apps: the same, decorator-style, no .toml
• multi-environment/README.md - Multi-environment usage
• openai/README.md - AI library with OpenAI-compatible APIs
• telegram-bot/README.md - Telegram bot example
• net/unicast/README.md - UDP and TCP point-to-point messaging
• net/multicast/README.md - UDP multicast group messaging
• net/gossip/README.md - Gossip protocol cluster membership and messaging
• fs/README.md - Binary I/O: pack, unpack, read/write bytes
• find/example.py - Find files by name, type, mtime, and size with scriptling.find
• shlex/example.py - Shell quoting, splitting, and joining with shlex
• tempfile/example.py - Temporary files, directories, and atomic writes with tempfile
• shutil/example.py - Copy, rmtree, move, and disk_usage with shutil
• zipfile/example.py - Create, read, and extract ZIP archives with zipfile
• tarfile/example.py - Create, read, and extract gzipped TAR archives with tarfile
• math/README.md - Linear algebra: matmul, dot, transpose, softmax, special functions
• random/README.md - Distributions: gauss, beta, gamma, pareto, weibull, choices