Verodat MCP 服务器

概览

这是一个为 Verodat 实现的模型上下文协议 (MCP) 服务器，它能够使 Verodat 的数据管理功能与像 Claude Desktop 这样的 AI 系统无缝集成。

Verodat MCP 服务器

此仓库包含一个为 Verodat 实现的模型上下文协议 (MCP) 服务器，允许 AI 模型通过定义良好的工具与 Verodat 的数据管理能力进行交互。

概览

Verodat MCP 服务器提供了一种标准化方式，让 AI 模型可以访问和操作 Verodat 中的数据。它实现了模型上下文协议规范，提供了用于数据消费、设计和管理的工具。

工具类别

该服务器被组织成三个主要工具类别，每个类别都提供了一系列递进的功能：

1. 消费（8 个工具）

基础类别专注于数据检索操作：

• get-accounts: 获取可用账户
• get-workspaces: 列出账户内的工作区
• get-datasets: 列出工作区中的数据集
• get-dataset-output: 从数据集中检索实际数据
• get-dataset-targetfields: 检索数据集的字段定义
• get-queries: 检索现有的 AI 查询
• get-ai-context: 获取工作区上下文和数据结构
• execute-ai-query: 在数据集上执行由 AI 支持的查询

2. 设计（9 个工具）

包括所有来自“消费”类别的工具，外加：

• create-dataset: 使用定义的模式创建新数据集

3. 管理（10 个工具）

包括所有来自“设计”类别的工具，外加：

• upload-dataset-rows: 向现有数据集上传数据行

前提条件

• Node.js (v18 或更高版本)
• Git
• Claude Desktop（用于 Claude 集成）
• Verodat 账户和 AI API 密钥

安装

快速开始

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 Verodat MCP 服务器：

npx -y @smithery/cli install @Verodat/verodat-mcp-server --client claude

手动安装

1. 克隆仓库：

git clone https://github.com/Verodat/verodat-mcp-server.git
cd verodat-mcp-server

1. 安装依赖并构建：

npm install
npm run build

1. 配置 Claude Desktop:
   创建或修改配置文件：

   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

   添加下面提到的配置信息到配置文件中：

开始使用 Verodat

1. 在 verodat.com 注册一个 Verodat 账户
2. 从您的 Verodat 仪表板生成一个 AI API 密钥
3. 将 API 密钥添加到您的 Claude Desktop 配置中

配置

服务器需要对认证和 API 端点进行配置。为您的 AI 模型创建一个配置文件以使用：

{
  "mcpServers": {
    "verodat-consume": {
      "command": "node",
      "args": [
        "path/to/verodat-mcp-server/build/src/consume.js"
      ],
      "env": {
        "VERODAT_AI_API_KEY": "your-api-key",
        "VERODAT_API_BASE_URL": "https://verodat.io/api/v3"
      }
    }
  }
}

配置选项

你可以通过在 claude 中一次指定适当的 JS 文件来配置这三类工具中的任何一类：

• 仅消费: 使用 consume.js（8 个用于数据检索的工具）
• 设计能力: 使用 design.js（9 个工具，包括数据集创建）
• 全面管理: 使用 manage.js（10 个工具，包括数据上传）

同时配置所有三类工具的例子：

{
  "mcpServers": {
    "verodat-consume": {
      "command": "node",
      "args": [
        "path/to/verodat-mcp-server/build/src/consume.js"
      ],
      "env": {
        "VERODAT_AI_API_KEY": "your-api-key",
        "VERODAT_API_BASE_URL": "https://verodat.io/api/v3"
      }
    },
    "verodat-design": {
      "command": "node",
      "args": [
        "path/to/verodat-mcp-server/build/src/design.js"
      ],
      "env": {
        "VERODAT_AI_API_KEY": "your-api-key",
        "VERODAT_API_BASE_URL": "https://verodat.io/api/v3"
      }
    },
    "verodat-manage": {
      "command": "node",
      "args": [
        "path/to/verodat-mcp-server/build/src/manage.js"
      ],
      "env": {
        "VERODAT_AI_API_KEY": "your-api-key",
        "VERODAT_API_BASE_URL": "https://verodat.io/api/v3"
      }
    }
  }
}

环境变量

• VERODAT_AI_API_KEY: 用于认证的 Verodat API 密钥
• VERODAT_API_BASE_URL: Verodat API 的基础 URL（如果未指定，默认为 "https://verodat.io/api/v3"）

工具使用指南

可用命令

服务器提供以下 MCP 命令：

// Account & Workspace Management
get-accounts        // List accessible accounts
get-workspaces      // List workspaces in an account
get-queries         // Retrieve existing AI queries

// Dataset Operations
create-dataset      // Create a new dataset
get-datasets        // List datasets in a workspace
get-dataset-output  // Retrieve dataset records
get-dataset-targetfields // Retrieve dataset targetfields
upload-dataset-rows // Add new data rows to an existing dataset

// AI Operations
get-ai-context      // Get workspace AI context
execute-ai-query    // Run AI queries on datasets

选择合适的工具类别

• 对于只读操作: 使用 consume.js 服务器配置
• 对于创建数据集: 使用 design.js 服务器配置
• 对于上传数据: 使用 manage.js 服务器配置

安全注意事项

• 需要通过 API 密钥进行身份验证
• 请求验证确保了格式正确的数据

开发

代码库使用 TypeScript 编写，并组织成以下几个部分：

• 工具处理程序: 每个工具功能的实现
• 传输层: 处理与 AI 模型的通信
• 验证: 使用 Zod 模式确保正确的数据格式

调试

MCP 服务器通过 stdio 进行通信，这可能会使调试变得困难。我们提供了一个 MCP Inspector 工具来帮助：

npm run inspector

这将提供一个 URL，以便您在浏览器中访问调试工具。

贡献

我们欢迎贡献！请随时提交 Pull Request。

许可证

LICENSE 文件了解更多详情

支持

• 文档: Verodat 文档
• 问题: GitHub Issues
• 社区: Verodat 社区