MCP Server with Datasaur Sandbox

使用 Datasaur Sandbox 的 MCP 服务

面向初学者的全面指南，介绍如何设置和使用搭配 Datasaur Sandbox 的 Model Context Protocol（MCP）服务。

目录

• 简介
• 前置条件
• 安装
• 配置
• 运行 MCP 服务
• 使用 MCP 服务
• 故障排除
• 扩展功能

简介

什么是 MCP？

Model Context Protocol（MCP）是一种应用与 AI 模型通信的标准化方式。它定义了一种协议，允许工具与大模型（LLM）交换结构化数据，从而使用外部函数和工具。

什么是 Datasaur Sandbox？

Datasaur Sandbox 提供对各种 AI 模型的托管 API 访问。本项目实现了一个 MCP 服务，充当您的应用与 Datasaur API 端点之间的桥梁，使您的应用能够：

• 处理和分析数据
• 访问通过 Datasaur 部署的 AI 模型
• 为各种任务构建专用助手

前置条件

开始之前，请确保您已具备：

1. 系统已安装 Python 3.8+

   • 从 python.org 下载
   • 安装时务必勾选“Add Python to PATH”

2. 拥有可访问 API 的 Datasaur 账户

   • 在 datasaur.ai 注册
   • 从账户控制面板获取 API 密钥

3. 具备命令行操作的基础知识

安装

步骤 1：克隆或创建项目

为项目创建一个新目录：

mkdir datasaur-mcp-server
cd datasaur-mcp-server

步骤 2：设置环境

创建虚拟环境（推荐）：

# For Windows
python -m venv venv
venv\Scripts\activate

# For macOS/Linux
python -m venv venv
source venv/bin/activate

步骤 3：安装依赖项

创建一个 requirements.txt 文件，并添加以下内容：

mcp[cli]
httpx
python-dotenv
uv

安装依赖项：

pip install -r requirements.txt

或者使用 UV（安装速度更快）：

pip install uv
uv pip install -r requirements.txt

步骤 4：创建必要文件

1. 创建 .env 文件

在项目根目录中创建一个 .env 文件，用于存储 API 密钥和配置：

DATASAUR_API_KEY=your_api_key_here
DATASAUR_SANDBOX_API_URL=your_sandbox_url

您可以根据需要添加更多环境变量，以配置其他 Sandbox 模型。

2. 创建 utils.py

创建工具文件 utils.py，并添加辅助函数：

# Utility functions for mcp-datasaur

import os
import logging
from dotenv import load_dotenv

load_dotenv()

def get_datasaur_api_config():
    """
    Returns the Datasaur API URL and API key from environment variables.
    """
    api_url = os.getenv("DATASAUR_API_URL")
    api_key = os.getenv("DATASAUR_API_KEY")
    if not api_url or not api_key:
        logging.error("DATASAUR_API_URL or DATASAUR_API_KEY not set in .env")
        return None, None
    return api_url, api_key

3. 创建 main.py

创建主 MCP 服务文件（main.py）。此文件包含运行 MCP 服务所需的全部代码。您可以复制提供的示例代码，或创建一个简化版本。

完整示例太长，无法在此列出，但应包含：

• 环境加载
• MCP 服务设置
• 各种 Datasaur API 端点的工具定义
• 主执行代码

配置

了解配置文件

.env 文件

.env 文件包含 API 密钥和服务 URL 等敏感信息。切勿将此文件提交到公开代码仓库。

Claude Desktop 配置（面向 Claude 用户）

如果您使用 Claude Desktop，请创建 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "mcp-datasaur": {
      "command": "path\\to\\your\\python.exe",
      "args": ["path\\to\\your\\main.py"],
      "env": {
        "TRANSPORT": "stdio",
        "DATASAUR_API_KEY": "your-api-key-here",
        "DATASAUR_SANDBOX_API_URL": "https://deployment.datasaur.ai/api/deployment/your-deployment-id/your-model-id/chat/completions"
      }
    }
  }
}

替换以下内容：

• 将 path\\to\\your\\python.exe 替换为 Python 可执行文件的路径
• 将 path\\to\\your\\main.py 替换为 main.py 文件的路径
• 将 your-api-key-here 替换为您的实际 Datasaur API 密钥
• 将 your-deployment-id 和 your-model-id 替换为您在 Datasaur 中的实际部署 ID 和模型 ID

获取 Datasaur API URL

1. 登录您的 Datasaur 账户
2. 前往 Deployments 部分
3. 创建或选择您的部署
4. 记下部署 ID 和模型 ID
5. API URL 的格式通常为：https://deployment.datasaur.ai/api/deployment/{deployment_id}/{model_id}/chat/completions

运行 MCP 服务

直接运行

直接运行 MCP 服务：

# Activate your virtual environment first if using one
python main.py

使用 Claude Desktop 运行

如果你使用 Claude Desktop：

1. 将 claude_desktop_config.json 文件放在 Claude Desktop 配置目录中
2. 打开 Claude Desktop
3. Claude 即可将你的 MCP 服务作为工具使用

使用你的 MCP 服务

你的 MCP 服务在应用程序与 Datasaur 的 AI 模型之间搭建桥梁。以下是你可以实现的工具类型：

1. 数据处理工具

   • 在不同格式之间转换文件（例如，将 CSV 转换为 JSON）
   • 处理和分析结构化数据
   • 将数据发送给专用 AI 模型进行分析

2. AI 模型访问

   • 创建可将提示词发送给你在 Datasaur 中部署的任意 AI 模型的函数
   • 每个函数都可以采用相同的模式，只需更改端点 URL 和特定于模型的参数
   • 示例：语言模型、代码助手、领域专家

3. 辅助工具

   • 为常见任务创建专用工具
   • 示例：撰写电子邮件、生成报告、领域专用助手

工具函数模式示例

以下是创建用于访问 Datasaur 沙盒模型的工具时的一般模式：

@mcp.tool()
async def call_your_model(prompt: str) -> str:
    """
    Sends a given prompt string to your deployed model via Datasaur API sandbox.
    
    Args:
        prompt: The text prompt to send to the model.
    """
    logging.debug(f"Received prompt: {prompt[:100]}...")

    # Check configuration
    if not DATASAUR_SANDBOX_API_URL or not DATASAUR_API_KEY:
        logging.error("DATASAUR_SANDBOX_API_URL or DATASAUR_API_KEY not configured.")
        return "Error: Datasaur API configuration missing on server."

    headers = {
        'Authorization': f'Bearer {DATASAUR_API_KEY}',
        'Content-Type': 'application/json'
    }
    payload = { "messages": [ {"role": "user", "content": prompt} ] }

    try:
        async with httpx.AsyncClient(timeout=180.0) as client:
            response = await client.post(DATASAUR_SANDBOX_API_URL, headers=headers, json=payload)
            response.raise_for_status()
            response_json = response.json()
            
            # Process response
            if 'choices' in response_json and len(response_json['choices']) > 0:
                if 'message' in response_json['choices'][0] and 'content' in response_json['choices'][0]['message']:
                    return str(response_json['choices'][0]['message']['content'])
            
            return "Error: Unexpected response format"
    except Exception as e:
        logging.error(f"Error: {e}")
        return f"Error: {e}"

Python 使用示例

import asyncio
from mcp.client import MCPClient

async def main():
    # Connect to your MCP server
    client = MCPClient()
    await client.connect_process(["python", "main.py"])
    
    # Use your tool
    result = await client.call_tool("call_your_model", {"prompt": "Your prompt here"})
    print(result)
    
    # Disconnect when done
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

故障排除

常见问题和解决方案

1. “未配置 API 密钥”错误

   • 确保 .env 文件包含 DATASAUR_API_KEY 变量
   • 检查是否已从 Datasaur 账户正确复制 API 密钥

2. “未配置 API URL”错误

   • 确保 .env 文件中已设置所有必需的 Datasaur API URL
   • 确认 URL 格式正确

3. 连接错误

   • 检查网络连接
   • 确认你的 Datasaur 账户处于有效状态，且拥有 API 访问权限

4. “找不到模块”错误

   • 确保已安装所有依赖项：pip install -r requirements.txt
   • 如果你使用虚拟环境，请激活它

5. 权限问题

   • 以管理员身份或使用提升后的权限运行终端或命令提示符

扩展功能

添加新模型

要向 MCP 服务添加新模型：

1. 在 .env 文件中添加新的环境变量：

DATASAUR_ANOTHER_MODEL_API_URL=your_another_model_url

2. 将该环境变量添加到 claude_desktop_config.json（如果使用 Claude Desktop）

3. 按照上文“工具函数模式示例”部分所示的模式，在 main.py 中创建新函数：

@mcp.tool()
async def call_another_model(prompt: str) -> str:
    """
    Documentation for your new model function.
    """
    logging.debug(f"Received prompt: {prompt[:100]}...")

    # Check configuration
    if not DATASAUR_ANOTHER_MODEL_API_URL or not DATASAUR_API_KEY:
        logging.error("DATASAUR_ANOTHER_MODEL_API_URL or DATASAUR_API_KEY not configured.")
        return "Error: Configuration missing on server."

    headers = {
        'Authorization': f'Bearer {DATASAUR_API_KEY}',
        'Content-Type': 'application/json'
    }
    payload = { "messages": [ {"role": "user", "content": prompt} ] }

    try:
        async with httpx.AsyncClient(timeout=180.0) as client:
            response = await client.post(DATASAUR_ANOTHER_MODEL_API_URL, headers=headers, json=payload)
            response.raise_for_status()
            response_json = response.json()
            
            # Process and return response
            if 'choices' in response_json and response_json['choices']:
                if 'message' in response_json['choices'][0] and 'content' in response_json['choices'][0]['message']:
                    return str(response_json['choices'][0]['message']['content'])
            
            return "Error: Unexpected response format"
    except Exception as e:
        logging.error(f"Error: {e}")
        return f"Error: {e}"

自定义响应处理

要自定义响应的处理方式：

1. 修改相关函数中的响应处理部分
2. 你可以解析 JSON、提取特定字段，或采用不同的格式整理响应

添加身份验证

要添加其他身份验证方式：

1. 将身份验证凭据添加到 .env 文件
2. 修改 API 请求中的标头

资源

• Model Context Protocol 文档
• Datasaur 文档
• Python httpx 库
• FastMCP 文档（如适用）

许可证

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

---

使用 Datasaur Sandbox 创作 ❤️