MCP Tcl Udf Server

🚀 TCL MCP 服务器

TCL MCP 服务器是一个模型上下文协议（MCP）服务器，它使 AI 代理能够执行 TCL 脚本并管理 MCP 工具生态系统。该项目在设计时充分考虑了安全性和开发者体验。

🚀 快速开始

# 安装并运行（使用 Molt 运行时的安全模式）
cargo install tcl-mcp-server
tcl-mcp-server

# 或者从源代码构建
git clone https://github.com/cyberdione/mcp-tcl-udf-server
cd mcp-tcl-udf-server
cargo build --release
./target/release/tcl-mcp-server

# 可选：使用完整的不安全 TCL 运行时进行构建（需要系统安装 TCL）
# cargo build --release --features tcl

✨ 主要特性

• 执行 TCL 脚本：通过 MCP 运行 TCL 代码，并具备智能安全控制。
• 管理 MCP 生态系统：添加、移除和编排其他 MCP 服务器。
• 默认安全：使用 Molt（内存安全的 TCL）进行沙盒执行。
• 工具管理：创建、版本控制和组织自定义工具。
• 跨平台：可在 Linux、macOS 和 Windows 上运行。

🔧 运行时选项

可以在两种 TCL 运行时实现之间进行选择：

🔒 Molt 运行时（默认 - 安全）

• 内存安全：用 Rust 编写，具有内置的安全保证。
• 沙盒化：无文件 I/O、无系统命令、无网络访问。
• 子集功能：具备用于数据处理和算法的核心 TCL 功能。
• 推荐使用：适用于生产环境和不可信环境。
• 文档：Molt TCL 手册

⚠️ TCL 运行时（完整 - 不安全）

• 完整功能：具备完整的 TCL 语言特性。
• 系统访问：支持文件 I/O、系统命令和网络操作。
• 功能强大：具有高级脚本功能和系统集成能力。
• 存在风险：需要可信环境并仔细验证输入。
• 文档：官方 TCL 文档

💻 使用示例

基础用法

运行服务器

# 默认（只读模式）
tcl-mcp-server

# 特权模式（保存/存储脚本）
tcl-mcp-server --privileged
# 或者使用管理包装器
tcl-mcp-server-admin

基本命令

# 直接执行 TCL
tcl-mcp-server run tcl_execute '{"script": "expr {2 + 2}"}'

# 列出可用工具
tcl-mcp-server list

# 获取工具信息
tcl-mcp-server info tcl_execute

# 管理 MCP 服务器
tcl-mcp-server mcp add my-server "My Server" -- node server.js
tcl-mcp-server mcp remove my-server

MCP 客户端集成

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

高级用法

创建自定义工具

# 1. 添加工具（需要特权模式）
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. 使用工具
tcl-mcp-server run user__dev__math__fibonacci '{"n": 10}'

运行时能力检测

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

📚 详细文档

内置工具

核心工具（始终可用）

bin__tcl_execute - 执行 TCL 脚本

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

bin__list_tools - 列出可用工具

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

docs__molt_book - 访问 TCL 文档

{
  "topic": "basic_syntax"
}

管理工具（仅特权模式可用）

sbin__tcl_tool_add - 创建自定义工具

{
  "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 - 以编程方式添加 MCP 服务器

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

编译和运行时配置

构建选项

服务器支持两种 TCL 运行时实现，必须在编译时选择：

默认构建（Molt 运行时 - 安全）

# 仅使用 Molt 运行时进行构建（推荐）
cargo build --release

# 生成的二进制文件默认使用 Molt
./target/release/tcl-mcp-server

使用 TCL 运行时进行构建（完整但不安全）

# 使用完整的 TCL 运行时进行构建（需要系统安装 TCL）
cargo build --release --no-default-features --features tcl

# 生成的二进制文件使用完整的 TCL
./target/release/tcl-mcp-server

使用两种运行时进行构建

# 构建时同时支持两种运行时（最大灵活性）
cargo build --release --features molt,tcl

# 在启动时选择运行时
./target/release/tcl-mcp-server --runtime molt   # 安全模式
./target/release/tcl-mcp-server --runtime tcl    # 完整模式

运行时选择（多运行时构建）

当使用多个运行时进行构建时，可以在启动时选择：

# 命令行选择
tcl-mcp-server --runtime molt          # 安全：Molt 运行时
tcl-mcp-server --runtime tcl           # 不安全：完整 TCL 运行时

# 环境变量
export TCL_MCP_RUNTIME=molt
tcl-mcp-server

# 优先级：命令行参数 > 环境变量 > 默认（Molt）

系统要求

对于 Molt 运行时（默认）：

• 仅需 Rust 工具链
• 无外部依赖
• 可在所有平台上运行

对于 TCL 运行时：

• 需要系统安装 TCL（8.6+）
• 编译时需要开发头文件
• 特定平台设置：

# Ubuntu/Debian
sudo apt-get install tcl-dev

# macOS
brew install tcl-tk

# Windows
# 从 https://www.tcl-lang.org/software/tcltk/ 安装 TCL

预构建包装脚本

构建过程会自动生成便捷包装器：

# 构建时生成
./target/release/tcl-mcp-server-admin      # 特权模式
./target/release/tcl-mcp-server-molt       # 强制使用 Molt 运行时
./target/release/tcl-mcp-server-admin-molt # 特权 + Molt
./target/release/tcl-mcp-server-ctcl       # 强制使用 TCL 运行时
./target/release/tcl-mcp-server-admin-ctcl # 特权 + TCL

MCP 服务器管理

添加服务器

# 基本服务器
tcl-mcp-server mcp add my-server "My Server" -- node server.js

# 带有环境变量
tcl-mcp-server mcp add my-server "My Server" \
  --env "NODE_ENV=production" \
  --env "API_KEY=secret" \
  -- node server.js

# 自定义超时和重试设置
tcl-mcp-server mcp add my-server "My Server" \
  --timeout-ms 60000 \
  --max-retries 5 \
  -- node server.js

服务器信息

# 列出所有服务器
tcl-mcp-server mcp list

# 详细视图
tcl-mcp-server mcp list --detailed

# 服务器详情
tcl-mcp-server mcp info my-server

连接管理

# 手动连接
tcl-mcp-server mcp connect my-server

# 测试连接
tcl-mcp-server mcp ping my-server

# 断开连接
tcl-mcp-server mcp disconnect my-server

# 移除服务器
tcl-mcp-server mcp remove my-server

安全模型

默认安全（推荐）

• 受限模式：仅提供基本工具。
• Molt 运行时：内存安全，沙盒执行（参见 Molt 文档）。
• 无文件 I/O：防止未经授权的文件访问。
• 无系统命令：阻止系统级操作。

特权模式

⚠️ 谨慎使用

• 可完全访问 TCL 语言。
• 具备工具管理能力。
• 可能进行系统级操作（特别是使用 TCL 运行时）。
• 仅推荐在可信环境中使用。
• 使用 TCL 运行时：可完全访问系统（参见 TCL 文档）。

架构

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

高级用法

容器部署

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"]

测试

# 运行测试套件
./scripts/run_mcp_tests.sh

# 测试特定功能
python3 tests/test_bin_exec_tool_mcp.py

数据存储

服务器配置存储在适合平台的位置：

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

故障排除

常见问题

服务器无法启动

# 检查运行时可用性
tcl-mcp-server --runtime molt --privileged

# 启用调试日志
RUST_LOG=debug tcl-mcp-server

MCP 服务器连接失败

# 测试连接
tcl-mcp-server mcp ping server-id

# 检查服务器日志
TCL_MCP_DEBUG_STDERR=1 tcl-mcp-server

工具未找到

# 列出可用工具
tcl-mcp-server list

# 检查特定命名空间
tcl-mcp-server list --namespace user

🤝 贡献指南

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。