dizi (Listenai)

Dizi - 动态配置的 MCP 服务器

💡 注意：这个项目几乎是纯 AI 生成的项目，目前处于初级阶段，已通过初步验证可正常使用。

Dizi 是一个基于 Model Context Protocol (MCP) 的高性能服务器，支持通过 YAML 配置文件动态定义和管理工具，让 AI 助手能够与您的开发环境无缝集成。

📋 目录

• ✨ 核心特性
• 🚀 快速安装
• ⚡ 快速开始
• 🔧 客户端配置
• 📁 文件系统工具
• 🛠️ 工具类型详解
• 📖 配置参考
• 🎯 Lua 脚本功能
• 💻 命令行选项

✨ 核心特性

🚀 快速安装

方式一：从 GitHub Release 下载（推荐）

访问 Releases 页面 下载预编译二进制文件：

📱 各平台安装命令

Linux (x86_64):

wget https://github.com/LISTENAI/dizi/releases/latest/download/dizi-linux-amd64
chmod +x dizi-linux-amd64
sudo mv dizi-linux-amd64 /usr/local/bin/dizi

Linux (ARM64):

wget https://github.com/LISTENAI/dizi/releases/latest/download/dizi-linux-arm64
chmod +x dizi-linux-arm64
sudo mv dizi-linux-arm64 /usr/local/bin/dizi

macOS (Intel):

wget https://github.com/LISTENAI/dizi/releases/latest/download/dizi-darwin-amd64
chmod +x dizi-darwin-amd64
sudo mv dizi-darwin-amd64 /usr/local/bin/dizi

macOS (Apple Silicon):

wget https://github.com/LISTENAI/dizi/releases/latest/download/dizi-darwin-arm64
chmod +x dizi-darwin-arm64
sudo mv dizi-darwin-arm64 /usr/local/bin/dizi

Windows: 下载 dizi-windows-amd64.exe 并将其添加到系统 PATH。

方式二：从源码编译

git clone https://github.com/LISTENAI/dizi.git
cd dizi
go build -o dizi

⚡ 快速开始

1️⃣ 初始化项目

# 在您的项目目录中运行
dizi init

这将创建：

📁 您的项目/
├── 📄 dizi.yml          # 主配置文件
└── 📁 dizi_bin/         # Lua 脚本目录
    ├── 📜 hello.lua     # 问候和数学计算示例
    ├── 📜 system_info.lua  # 系统信息工具
    └── 📜 file_utils.lua   # 文件操作工具

2️⃣ 启动服务器

# 默认启动（SSE 模式）
dizi

# 启用文件系统工具
dizi -fs-tools

# 使用 stdio 模式
dizi -transport=stdio

# 指定端口
dizi -port=9000

3️⃣ 测试工具

# 交互式 Lua REPL
dizi repl

# 运行 Lua 脚本
dizi lua dizi_bin/hello.lua

🔧 客户端配置

Claude Desktop 配置

基础配置：

{
  "mcpServers": {
    "dizi": {
      "command": "dizi",
      "args": ["-transport=stdio", "-workdir=/path/to/your/project"],
      "env": {}
    }
  }
}

启用文件系统工具：

{
  "mcpServers": {
    "dizi": {
      "command": "dizi", 
      "args": ["-transport=stdio", "-workdir=/path/to/your/project", "-fs-tools"],
      "env": {}
    }
  }
}

SSE 客户端配置

📁 文件系统工具

Dizi 提供安全、完整的文件系统操作能力。

🔐 安全特性

• 🛡️ 路径限制：默认仅允许访问项目目录内的文件
• 🚫 防止遍历：严格验证路径，防止 ../ 攻击
• ✅ 显式启用：文件系统工具需要明确启用

📋 可用工具

🛠️ 工具类型详解

Command 工具

执行系统命令：

- name: "git_status"
  description: "获取 Git 仓库状态"
  type: "command"
  command: "git"
  args: ["status", "--porcelain"]

Script 工具

执行 shell 脚本，支持参数占位符：

- name: "greet_user"
  description: "问候用户"
  type: "script"
  script: "echo 'Hello, {{name}}! 今天是 $(date)'"
  parameters:
    type: "object"
    properties:
      name:
        type: "string"
        description: "用户名"
    required: ["name"]

Lua 工具

执行 Lua 脚本文件：

- name: "hello_tool"
  description: "问候和基础数学计算工具"
  type: "lua"
  script: "dizi_bin/hello.lua"
  parameters:
    type: "object"
    properties:
      name:
        type: "string"
        description: "要问候的名称"
      operation:
        type: "string"
        description: "数学操作 (add, multiply, subtract, divide)"

Builtin 工具

内置的特殊工具：

- name: "lua_eval"
  description: "执行 Lua 代码片段"
  type: "builtin"
  parameters:
    type: "object"
    properties:
      code:
        type: "string"
        description: "要执行的 Lua 代码"
    required: ["code"]

📖 配置参考

完整配置示例

# Dizi MCP Server Configuration
name: "my-mcp-server"
version: "1.0.0"
description: "My Custom MCP Server"

server:
  port: 8081

tools:
  # Shell 命令执行
  - name: "shell_eval"
    description: "执行标准的 bash 命令"
    type: "script"
    script: "{{command}}"
    parameters:
      type: "object"
      properties:
        command:
          type: "string"
          description: "要执行的 shell 命令"
      required: ["command"]

  # Git 操作
  - name: "git_status"
    description: "显示 Git 仓库状态"
    type: "script"
    script: "cd {{path}} && git status --porcelain"
    parameters:
      type: "object"
      properties:
        path:
          type: "string"
          description: "Git 仓库路径"
      required: ["path"]

  # 时间工具
  - name: "current_time"
    description: "获取当前日期和时间"
    type: "script"
    script: "date '+%Y-%m-%d %H:%M:%S'"

  # Zephyr 开发工具
  - name: "zephyr_build"
    description: "编译 Zephyr 项目"
    type: "script"
    script: "source .venv/bin/activate && west build -p -s {{source_dir}} -b {{board}}"
    parameters:
      type: "object"
      properties:
        board:
          type: "string"
          description: "目标开发板"
        source_dir:
          type: "string"
          description: "源码目录（可选）"
      required: ["board"]

参数配置说明

🎯 Lua 脚本功能

命令行脚本执行

# 运行 Lua 脚本
dizi lua dizi_bin/hello.lua

# 运行系统信息脚本
dizi lua dizi_bin/system_info.lua

交互式 REPL

启动交互式 Lua 环境：

dizi repl

REPL 特性：

• ✨ 自动计算：输入 2 + 3 显示 => 5
• 🔄 历史记录：上下箭头浏览命令历史
• 📋 自动补全：Tab 键触发智能补全
• 🎨 语法高亮：彩色代码显示

内置命令：

• :help - 显示帮助信息
• :quit / :exit - 退出 REPL
• :clear - 清屏
• :reset - 重置 Lua 状态
• :vars - 显示所有变量
• :history - 显示命令历史

使用示例：

lua:1> 2 + 3
=> 5

lua:2> name = "Dizi"
lua:3> "Hello, " .. name  
=> Hello, Dizi

lua:4> function factorial(n)
lua:4>   if n    return n * factorial(n-1)
lua:4> end

lua:5> factorial(5)
=> 120

Lua 脚本开发指南

• 兼容性：支持 Lua 5.1 语法
• 输入获取：使用全局变量 args 获取外部输入
• 结果返回：使用全局变量 result 返回结果
• 调试输出：使用 print() 函数打印调试信息
• 可以使用额外的库：支持系统检测，http client等功能，具体可以看仓库 dizi_bin/gopher_lua_libs_simple.lua。也可以看参考资源的拓展库

参考资源：

• Gopher-Lua 文档
• Lua 5.1 手册
• 拓展库

💻 命令行选项

基本命令

服务器选项

文件系统选项

其他选项

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

📄 许可证

本项目采用 MIT License 开源协议。

🔗 相关链接

• Model Context Protocol 官网
• MCP 规范文档
• 问题反馈

🌟 如果这个项目对您有帮助，请给它一个 Star！

Made with ❤️ by AI & Human Collaboration