tcl-mcp-server 0.1.2

A Model Context Protocol (MCP) server that provides TCL (Tool Command Language) execution capabilities with namespace-based tool management and versioning.
docs.rs failed to build tcl-mcp-server-0.1.2
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

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.

crates.io Documentation

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"
    }
  ]
}'
  1. 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