zsv MCP

zsv mcp

 

一个基于Go的模型上下文协议（MCP）服务器，为 zsv CLI（请参阅：https://github.com/liquidaty/zsv).

本项目使用官方MCP Go SDK： github.com/modelcontextprotocol/go-sdk.

特性

• zsv_run：run zsv 使用显式参数数组和返回捕获的stdout。
• zsv_help：run zsv --help 并返回捕获的stdout。
• 通过环境变量配置运行时值。
• 核心工具行为的单元测试。

仓库的规划

.
|- .cursor/
|  |- mcp.json             # Cursor MCP config
|- .github/
|  |- copilot-instructions.md
|- .mcp.json               # Claude Code MCP config
|- .vscode/
|  |- mcp.json             # VS Code / GitHub Copilot MCP config
|  |- settings.json        # VS Code MCP config (legacy format)
|- CLAUDE.md               # Cursor/Claude AI instructions for using zsv MCP tools
|- config/
|  |- config.go            # Environment-based configuration
|- docs/
|  |- TOOL_REFERENCE.md    # detailed tool contracts and examples
|- main.go                 # MCP server entry point
|- main_test.go            # Core handler tests
|- prompts/
|  |- tool_usage.go        # tool usage guidance prompt
|- resources/
|  |- tool_usage.go        # tool usage guidance resource
|- sample_data/
|  |- data.csv             # sample CSV for example prompts
|- SETUP.md                # VS Code local setup notes
|- tools/
|  |- help.go              # zsv_help tool
|  |- run.go               # zsv_run tool
|  |- run_help_test.go     # zsv_run/zsv_help tool tests

需求

• 转到1.23+
• zsv CLI可在您的 PATH 为了 zsv_run 和 zsv_help 工具，或 ZSV_PATH 设置为二进制位置-请参阅 安装 细节。

快速开始

1. 克隆并进入项目目录。

1. 安装依赖项：

go mod download

1. 构建：

# Linux/macOS
go build -o zsv-mcp

# Windows
go build -o zsv-mcp.exe

1. 启动服务器：

# Linux/macOS
./zsv-mcp

# Windows
zsv-mcp.exe

服务器通过stdio进行通信。看 MCP客户端配置文件 将其连接到您的编辑器。

1. 运行测试：

go test ./...

配置

环境变量被读入 config/config.go.

• SERVER_NAME （默认值： zsv-mcp)
• VERSION （默认值： v1.0.0)
• LOG_LEVEL （默认值： info)
• ZSV_PATH （默认值： zsv)被使用 zsv_run 和 zsv_help

日志记录注意事项：

• 服务器将日志写入 stderr 仅为了避免干扰上的MCP stdio协议流量 stdout.
• 支持 LOG_LEVEL 值： debug, info, warn （或 warning), error.
• 未知 LOG_LEVEL 值回落到 info 并在启动时发出警告。

PowerShell示例：

$env:SERVER_NAME = "zsv-mcp"
$env:VERSION = "v1.0.0"
$env:LOG_LEVEL = "debug"
$env:ZSV_PATH = "zsv"
zsv-mcp.exe

MCP客户端配置文件

该存储库附带了预配置的文件，因此MCP兼容的客户端可以在不进行手动设置的情况下发现并启动服务器。所有配置都期望二进制文件被命名 zsv-mcp （没有 .exe 扩展）——请参阅上面快速入门中的跨平台说明。

.mcp.json

Claude Code读取的项目级MCP发现文件。它注册 zsv-mcp 作为 stdio 服务器，没有额外的参数或环境覆盖。这 command 路径是相对于项目根目录的，因此必须从该目录启动客户端（或相应地调整路径）。

{
  "mcpServers": {
    "zsv-mcp": {
      "type": "stdio",
      "command": "./zsv-mcp",
      "args": [],
      "env": {
        "ZSV_PATH": "zsv",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

.vscode/mcp.json

在较新的VS Code版本中引入了特定于VS Code的MCP服务器配置。VS Code读取此文件以填充聊天MCP工具列表。使用 ${workspaceFolder} 因此，无论在何处打开VS Code，路径都能正确解析。VS Code中的GitHub Copilot也使用此文件。

{
  "servers": {
    "zsv-mcp": {
      "command": "${workspaceFolder}/zsv-mcp",
      "type": "stdio",
      "args": [],
      "env": {
        "ZSV_PATH": "zsv",
        "LOG_LEVEL": "debug"
    }
  }
}

.vscode/settings.json

在下注册服务器的工作区设置文件 mcpServers 钥匙。VS Code的MCP集成的早期版本使用此文件，而不是 .vscode/mcp.jsonThe disabled 字段控制服务器是否处于活动状态，以及 alwaysAllow 列出在没有用户提示的情况下自动批准的任何工具调用。

{
  "mcpServers": {
    "zsv-mcp": {
      "command": "${workspaceFolder}/zsv-mcp",
      "args": [],
      "disabled": false,
      "alwaysAllow": [],
      "env": {
        "ZSV_PATH": "zsv",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

两者 .vscode/mcp.json 和 .vscode/settings.json 指向相同的二进制文件；VS Code查询的文件取决于其版本，因此两者都包含在内以保持兼容性。

.cursor/mcp.json

光标MCP配置。Cursor支持 ${workspaceFolder} 不同版本之间不一致，因此此配置仅按名称引用二进制文件。确保 zsv-mcp 在你的 PATH （例如，通过 go install)或者用二进制文件的绝对路径替换命令值。

{
  "mcpServers": {
    "zsv-mcp": {
      "command": "zsv-mcp",
      "args": [],
      "env": {
        "ZSV_PATH": "zsv",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

克劳德桌面版

Claude Desktop使用用户级配置文件，而不是仓库级配置文件。将以下内容添加到您的 claude_desktop_config.json:

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zsv-mcp": {
      "command": "/absolute/path/to/zsv-mcp",
      "args": [],
      "env": {
        "ZSV_PATH": "zsv",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

工具摘要

看 工具参考.md 获取完整的请求和响应详细信息。

• zsv_run(cmd[])
• zsv_help()

示例提示

以下提示可用于任何兼容MCP的AI客户端（Claude、Cursor、VS Code Copilot等）来练习zsv MCP工具。大多数提示都明确指定要使用的MCP工具，这样AI就不会扫描项目源文件以获取上下文。最后一个没有明确命名工具，而是依赖于AI客户端从MCP服务器和为其提供的指导中推断出来。

出于验证目的，应为每个客户端使用新的提示，以确保AI客户端不受先前提示消息结果的影响。在处理过程中，您可能会看到AI客户端在学习如何向MCP服务器发出格式良好的请求时进行自我纠正。

验证安装

使用zsv_help MCP工具，向我显示zsv帮助文本。

AI呼叫 zsv_help() 并返回zsv CLI的顶级帮助输出，列出可用的子命令。如果失败，则zsv MCP工具未注册， zsv 未打开 PATH 或 ZSV_PATH 设置不正确。

从文件中选择列

使用zsv_run MCP工具，只显示sample_data/data.csv中的名称和国家列。

AI呼叫 zsv_run 随着 select 子命令提取两列并返回一个过滤后的CSV。

计算列的平均值

使用zsv_run MCP工具，计算sample_data/data.csv中人员的平均年龄。

AI呼叫 zsv_run 使用 sql 带有查询的子命令，例如 select avg(cast([Age] as real)) from data，然后报告结果。

多阶段操作

使用zsv_run MCP工具，仅从sample_data/data.csv中选择“名称”和“年龄”列，然后按年龄降序对结果进行排序。

人工智能将决定如何处理这个问题。它可能决定发布两个 zsv_run 电话(select 缩小列，然后 sql 排序）或将这两个操作组合成一个 sql 查询。然后，它将报告最终结果。

多级操作（未指定特定的MCP工具）

使用zsv，从sample_data/data.csv中仅选择“名称”和“国家”列，然后按“名称”升序对结果进行排序。

人工智能将决定如何处理这个问题，可能会参考zsv MCP使用指南，并最终执行 sql 通过电话 zsv_run 生成并显示最终结果。

发展

• 本地编辑器设置： 设置.md
• 贡献工作流程： 贡献.md