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.
Quick Start
# Install and run (safe mode with Molt runtime)
# Or build from source
# 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
# List all servers
# Test connectivity
📦 Tool Organization
Tools are organized using a namespace system with MCP-compatible naming:
bin__tcl_execute
- Execute TCL scriptsuser__alice__utils__reverse_string
- User-created toolsmcp__context7__get_library_docs
- External MCP server tools
Usage
Running the Server
Default (Read-only mode)
Privileged Mode (Save/store scripts)
# or use the admin wrapper
Essential Commands
# Execute TCL directly
# List available tools
# Get tool information
# Manage MCP servers
MCP Client Integration
Claude Desktop
Claude Code
Built-in Tools
Core Tools (Always Available)
bin__tcl_execute
- Execute TCL scripts
bin__list_tools
- List available tools
docs__molt_book
- Access TCL documentation
Management Tools (Privileged Mode Only)
sbin__tcl_tool_add
- Create custom tools
sbin__mcp_add
- Add MCP servers programmatically
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)
# The resulting binary uses Molt by default
Build with TCL Runtime (Complete but Unsafe)
# Build with full TCL runtime (requires system TCL installation)
# The resulting binary uses full TCL
Build with Both Runtimes
# Build with both runtimes available (maximum flexibility)
# Select runtime at startup
Runtime Selection (Multi-Runtime Builds)
When built with multiple runtimes, you can choose at startup:
# Command line selection
# Environment variable
# 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 # macOS # 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
MCP Server Management
Adding Servers
# Basic server
# With environment variables
# Custom timeout and retry settings
Server Information
# List all servers
# Detailed view
# Server details
Connection Management
# Manual connection
# Test connectivity
# Disconnect
# Remove 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
- Add a tool (requires privileged mode):
- Use the tool:
Runtime Capability Detection
Query runtime capabilities for intelligent code generation:
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
# Test specific functionality
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
# Enable debug logging
RUST_LOG=debug
MCP server connection fails
# Test connectivity
# Check server logs
TCL_MCP_DEBUG_STDERR=1
Tool not found
# List available tools
# Check specific namespace
Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
License
MIT License - see LICENSE file for details