TCL MCP Server

A Model Context Protocol (MCP) server that enables AI agents to execute TCL scripts and manage MCP tool ecosystems. Built with safety and developer experience in mind.

Quick Start

# Install and run (safe mode with Molt runtime)
cargo install tcl-mcp-server
tcl-mcp-server

# Or build from source
git clone https://github.com/cyberdione/mcp-tcl-udf-server
cd mcp-tcl-udf-server
cargo build --release
./target/release/tcl-mcp-server

# OPTIONAL: Build with full unsafe TCL runtime (requires system TCL installation)
# cargo build --release --features tcl

What It Does

• Execute TCL Scripts: Run TCL code through MCP with intelligent safety controls
• Manage MCP Ecosystem: Add, remove, and orchestrate other MCP servers
• Safe by Default: Uses Molt (memory-safe TCL) with sandboxed execution
• Tool Management: Create, version, and organize custom tools
• Cross-Platform: Works on Linux, macOS, and Windows

Runtime Options

Choose between two TCL runtime implementations:

🔒 Molt Runtime (Default - Safe)

• Memory-safe: Written in Rust with built-in safety guarantees
• Sandboxed: No file I/O, no system commands, no network access
• Subset: Core TCL functionality for data processing and algorithms
• Recommended: For production use and untrusted environments
• Documentation: Molt TCL Book

⚠️ TCL Runtime (Complete - Unsafe)

• Full functionality: Complete TCL language with all features
• System access: File I/O, system commands, network operations
• Powerful: Advanced scripting capabilities and system integration
• Risky: Requires trusted environment and careful input validation
• Documentation: Official TCL Documentation

Core Features

🔒 Safety First

• Restricted Mode (default): Safe TCL execution with limited commands
• Privileged Mode: Full TCL access for advanced use cases
• Runtime Selection: Choose between safe (Molt) and complete (TCL) implementations

🛠️ MCP Management

# Add external MCP servers
tcl-mcp-server mcp add claude-flow "Claude Flow" -- npx claude-flow@alpha mcp start

# List all servers
tcl-mcp-server mcp list

# Test connectivity
tcl-mcp-server mcp ping claude-flow

📦 Tool Organization

Tools are organized using a namespace system with MCP-compatible naming:

• bin__tcl_execute - Execute TCL scripts
• user__alice__utils__reverse_string - User-created tools
• mcp__context7__get_library_docs - External MCP server tools

Usage

Running the Server

Default (Read-only mode)

tcl-mcp-server

Privileged Mode (Save/store scripts)

tcl-mcp-server --privileged
# or use the admin wrapper
tcl-mcp-server-admin

Essential Commands

# Execute TCL directly
tcl-mcp-server run tcl_execute '{"script": "expr {2 + 2}"}'

# List available tools
tcl-mcp-server list

# Get tool information
tcl-mcp-server info tcl_execute

# Manage MCP servers
tcl-mcp-server mcp add my-server "My Server" -- node server.js
tcl-mcp-server mcp remove my-server

MCP Client Integration

Claude Desktop

{
  "mcpServers": {
    "tcl": {
      "command": "/path/to/tcl-mcp-server",
      "args": ["--runtime", "molt", "--privileged"]
    }
  }
}

Claude Code

claude mcp add tcl /path/to/tcl-mcp-server

Built-in Tools

Core Tools (Always Available)

bin__tcl_execute - Execute TCL scripts

{
  "script": "set x 5; set y 10; expr {$x + $y}"
}

bin__list_tools - List available tools

{
  "namespace": "user",
  "filter": "utils*"
}

docs__molt_book - Access TCL documentation

{
  "topic": "basic_syntax"
}

Management Tools (Privileged Mode Only)

sbin__tcl_tool_add - Create custom tools

{
  "user": "alice",
  "package": "utils",
  "name": "reverse_string",
  "version": "1.0",
  "description": "Reverse a string",
  "script": "return [string reverse $text]",
  "parameters": [
    {
      "name": "text",
      "description": "Text to reverse",
      "required": true,
      "type_name": "string"
    }
  ]
}

sbin__mcp_add - Add MCP servers programmatically

{
  "id": "context7",
  "name": "Context7 Server",
  "command": "npx",
  "args": ["@modelcontextprotocol/server-everything"],
  "auto_start": true
}

Compilation and Runtime Configuration

Build Options

The server supports two TCL runtime implementations that must be selected at compile time:

Default Build (Molt Runtime - Safe)

# Build with Molt runtime only (recommended)
cargo build --release

# The resulting binary uses Molt by default
./target/release/tcl-mcp-server

Build with TCL Runtime (Complete but Unsafe)

# Build with full TCL runtime (requires system TCL installation)
cargo build --release --no-default-features --features tcl

# The resulting binary uses full TCL
./target/release/tcl-mcp-server

Build with Both Runtimes

# Build with both runtimes available (maximum flexibility)
cargo build --release --features molt,tcl

# Select runtime at startup
./target/release/tcl-mcp-server --runtime molt   # Safe mode
./target/release/tcl-mcp-server --runtime tcl    # Complete mode

Runtime Selection (Multi-Runtime Builds)

When built with multiple runtimes, you can choose at startup:

# Command line selection
tcl-mcp-server --runtime molt          # Safe: Molt runtime
tcl-mcp-server --runtime tcl           # Unsafe: Full TCL runtime

# Environment variable
export TCL_MCP_RUNTIME=molt
tcl-mcp-server

# Priority: CLI args > Environment > Default (Molt)

System Requirements

For Molt Runtime (default):

• Rust toolchain only
• No external dependencies
• Works on all platforms

For TCL Runtime:

• System TCL installation required (8.6+)
• Development headers needed for compilation
• Platform-specific setup:

  # Ubuntu/Debian
  sudo apt-get install tcl-dev
  
  # macOS
  brew install tcl-tk
  
  # Windows
  # Install TCL from https://www.tcl-lang.org/software/tcltk/

Pre-built Wrapper Scripts

The build process automatically generates convenience wrappers:

# Generated during build
./target/release/tcl-mcp-server-admin      # Privileged mode
./target/release/tcl-mcp-server-molt       # Force Molt runtime
./target/release/tcl-mcp-server-admin-molt # Privileged + Molt
./target/release/tcl-mcp-server-ctcl       # Force TCL runtime
./target/release/tcl-mcp-server-admin-ctcl # Privileged + TCL

MCP Server Management

Adding Servers

# Basic server
tcl-mcp-server mcp add my-server "My Server" -- node server.js

# With environment variables
tcl-mcp-server mcp add my-server "My Server" \
  --env "NODE_ENV=production" \
  --env "API_KEY=secret" \
  -- node server.js

# Custom timeout and retry settings
tcl-mcp-server mcp add my-server "My Server" \
  --timeout-ms 60000 \
  --max-retries 5 \
  -- node server.js

Server Information

# List all servers
tcl-mcp-server mcp list

# Detailed view
tcl-mcp-server mcp list --detailed

# Server details
tcl-mcp-server mcp info my-server

Connection Management

# Manual connection
tcl-mcp-server mcp connect my-server

# Test connectivity
tcl-mcp-server mcp ping my-server

# Disconnect
tcl-mcp-server mcp disconnect my-server

# Remove server
tcl-mcp-server mcp remove my-server

Security Model

Default Security (Recommended)

• Restricted Mode: Only essential tools available
• Molt Runtime: Memory-safe, sandboxed execution (see Molt docs)
• No File I/O: Prevents unauthorized file access
• No System Commands: Blocks system-level operations

Privileged Mode

⚠️ Use with caution

• Full TCL language access
• Tool management capabilities
• System-level operations possible (especially with TCL runtime)
• Recommended for trusted environments only
• With TCL Runtime: Complete system access (see TCL docs)

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  AI Agent   ├────►│  MCP Server  ├────►│TCL Executor │
│  (Claude)   │     │  (JSON-RPC)  │     │  (Molt)     │
└─────────────┘     └──────────────┘     └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │ MCP Manager │
                    │ (External   │
                    │  Servers)   │
                    └─────────────┘

Advanced Usage

Creating Custom Tools

1. Add a tool (requires privileged mode):

tcl-mcp-server run sbin__tcl_tool_add '{
  "user": "dev",
  "package": "math",
  "name": "fibonacci",
  "version": "1.0",
  "description": "Calculate Fibonacci number",
  "script": "proc fib {n} { if {$n <= 1} {return $n} else {return [expr {[fib [expr {$n-1}]] + [fib [expr {$n-2}]]}]} }; return [fib $n]",
  "parameters": [
    {
      "name": "n",
      "description": "Number to calculate Fibonacci for",
      "required": true,
      "type_name": "integer"
    }
  ]
}'

2. Use the tool:

tcl-mcp-server run user__dev__math__fibonacci '{"n": 10}'

Runtime Capability Detection

Query runtime capabilities for intelligent code generation:

tcl-mcp-server run tcl_runtime_info '{
  "include_examples": true,
  "category_filter": "safe"
}'

Runtime Feature Comparison:

Feature	Molt Runtime	TCL Runtime
Memory Safety	✅ Rust-based, memory-safe	⚠️ C-based, manual memory management
File I/O	❌ Blocked for security	✅ Full file operations
System Commands	❌ No exec or system calls	✅ Complete system integration
Networking	❌ No socket operations	✅ Full network capabilities
Performance	⚡ Fast startup, low overhead	🐌 Slower startup, higher memory usage
Compatibility	📚 Core TCL subset	🔧 Full TCL language + extensions
Use Cases	Data processing, algorithms, safe scripting	System administration, complex applications
Documentation	Molt Book	TCL Documentation

Container Deployment

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/tcl-mcp-server /usr/bin/
COPY --from=builder /app/target/release/tcl-mcp-server-admin /usr/bin/
CMD ["/usr/bin/tcl-mcp-server"]

Testing

# Run the test suite
./scripts/run_mcp_tests.sh

# Test specific functionality
python3 tests/test_bin_exec_tool_mcp.py

Data Storage

Server configurations are stored in platform-appropriate locations:

• Linux: ~/.local/share/tcl-mcp-server/
• macOS: ~/Library/Application Support/tcl-mcp-server/
• Windows: %APPDATA%\tcl-mcp-server\

Troubleshooting

Common Issues

Server won't start

# Check runtime availability
tcl-mcp-server --runtime molt --privileged

# Enable debug logging
RUST_LOG=debug tcl-mcp-server

MCP server connection fails

# Test connectivity
tcl-mcp-server mcp ping server-id

# Check server logs
TCL_MCP_DEBUG_STDERR=1 tcl-mcp-server

Tool not found

# List available tools
tcl-mcp-server list

# Check specific namespace
tcl-mcp-server list --namespace user

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details