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 文件。