基于 SDV 与 MCP 的本地合成数据生成用 Cursor 编排生成、评估与可视化全流程【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub导读本文讲解如何在 ai-engineering-hub 仓库的 sdv-mcp 项目中通过 Model Context ProtocolMCP把 Synthetic Data VaultSDV封装成本地 MCP Server让 Cursor 等 MCP Host 中的智能体能够基于真实表格数据如酒店与宾客数据自动完成合成数据生成Generate→ 质量评估Evaluate→ 分布可视化Visualize的完整闭环。读完本文你将掌握从零配置uv依赖、注册 MCP Server到调用三个核心工具函数并理解其底层 SDV 实现原理的完整实战方案。架构总览用户Cursor 中的 Agent通过 MCP Server 与 Tools Module 交互Tools Module 调用 SDV Framework 完成数据合成、评估与可视化结果再原路返回给用户形成可控的本地合成数据工作流。一、项目背景与核心思路SDVSynthetic Data Vault是一个开源的表格数据合成框架能够学习真实数据的统计分布与表间关系并生成与真实数据分布高度相似、但不会泄露原始记录的新数据。在数据共享、模型测试、隐私保护等场景中合成数据可以替代真实数据使用。本项目 sdv-mcp 的核心思路是把 SDV 的三大能力生成、评估、可视化封装为 MCP 工具。MCPModel Context Protocol提供了一套标准化的工具发现与调用协议使 LLM Agent例如 Cursor 作为 MCP Host能够动态发现并调用本地服务暴露的工具。这样用户只需用自然语言描述需求如生成合成数据、评估质量、对比某个字段的分布Agent 就会自动选择合适的工具完成数据操作整个过程完全在本地运行无需上传任何数据到云端。技术栈如下SDV负责多表合成数据生成HMASynthesizer、质量评估evaluate_quality与列分布可视化get_column_plotCursor作为 MCP Host负责发现工具并向用户展示结果MCP Python SDKFastMCP以stdio传输方式启动本地 MCP Server。从源码结构看整个项目由三个 Python 文件构成清晰的职责分层文件职责server.py基于 FastMCP 声明三个 MCP 工具负责参数校验与错误转发tools.py实现生成、评估、可视化的具体业务逻辑调用 SDV APIpyproject.toml声明项目依赖与 Python 版本要求二、环境准备与依赖安装项目使用uv作为包管理工具依赖声明位于 pyproject.toml[project] name sdv-mcp version 0.1.0 description MCP Server uses SDV for synthetic data operations. readme README.md requires-python 3.12 dependencies [ kaleido0.2.1, mcp[cli]1.8.0, plotly6.0.1, sdv1.20.1, ]依赖要点说明sdv1.20.1合成数据生成与评估核心库提供Metadata、HMASynthesizer、evaluate_quality等核心 APImcp[cli]1.8.0MCP 官方 Python SDK[cli]extra 附带命令行工具server.py 中使用的FastMCP即来自该包plotly6.0.1与kaleido0.2.1可视化依赖。Plotly 负责生成交互式图表Kaleido 用于将 Plotly 图形离线渲染为 PNG 文件fig.write_image的底层依赖requires-python 3.12要求 Python 3.12 及以上版本请先确认本机 Python 版本满足要求。在项目根目录执行以下命令安装全部依赖会自动读取uv.lock锁定版本保证可复现uv sync安装完成后uv会在项目目录下创建虚拟环境后续 MCP Server 的启动命令见下文mcp.json中uv run会自动复用该环境。三、注册并启动 MCP Server3.1 配置 mcp.jsonMCP Server 通过一个 JSON 配置文件注册给 MCP Host。该配置文件既可以放在当前项目目录仅对当前项目生效也可以放在全局位置对所有项目生效。原文档给出的全局配置示例如下{ mcpServers: { sdv_mcp: { command: uv, args: [ --directory, /Users/akshay/Eigen/ai-engineering-hub/sdv-mcp, run, --with, mcp, server.py ] } } }配置项逐条拆解配置项含义mcpServers.sdv_mcpMCP Server 的注册名Cursor 等 Host 会在工具列表中显示为sdv_mcp_*前缀的工具command: uv使用uv作为启动器不依赖全局 Python 环境args[0].--directory指向本仓库的sdv-mcp目录让uv在该目录下解析pyproject.toml与uv.lock。请务必替换为你的实际仓库路径args[1].runuv run在虚拟环境中执行后续命令args[2].--with mcp临时附加mcp包即使未在 pyproject 中显式声明也能运行args[3].server.pyMCP Server 入口脚本3.2 Server 启动原理server.py 的入口逻辑非常简洁from mcp.server.fastmcp import FastMCP from tools import generate, evaluate, visualize # Create FastMCP instance mcp FastMCP(sdv_mcp) # ... 三个 mcp.tool() 装饰的工具函数 ... # Run the server if __name__ __main__: mcp.run(transportstdio)关键点FastMCP(sdv_mcp)创建了一个名为sdv_mcp的 MCP 实例与mcp.json中的注册名保持一致mcp.tool()装饰器将普通 Python 函数自动注册为 MCP 工具函数名、参数签名、docstring 都会成为工具的元数据供 LLM 理解并决定何时调用mcp.run(transportstdio)以stdio 传输模式启动服务这也是本地 MCP Server 的标准做法MCP Host 通过标准输入/输出与 Server 进程通信无需开放任何网络端口天然安全。启动后CursorMCP Host会自动发现并展示以下三个工具Agent 即可在对话中直接调用。四、三个核心 MCP 工具详解4.1 sdv_generate生成合成数据工具签名与 docstring来自 server.pymcp.tool() def sdv_generate(folder_name: str) - str: Generate synthetic data based on real data using SDV Synthesizer. This tool reads CSV files from the specified folder, creates a synthetic version of that data, and saves it to a synthetic_data folder. try: return generate(folder_name) except FileNotFoundError as e: return fError: {str(e)} except RuntimeError as e: return fError: {str(e)}底层实现在 tools.py 的generate函数中调用链为connector CSVHandler() data connector.read(folder_namefolder_name) # 1. 读取 CSV metadata Metadata.load_from_json(metadata_file) # 2. 加载元数据 synthesizer HMASynthesizer(metadata) # 3. 创建多表合成器 synthesizer.fit(data) # 4. 学习真实数据分布 synthetic_data synthesizer.sample(scale1) # 5. 按 1:1 比例采样逐步说明读取数据CSVHandler().read(folder_name)会扫描文件夹内所有 CSV 文件以文件名不含扩展名作为表名载入加载元数据Metadata.load_from_json(metadata_file)读取同目录下的metadata.json它描述了每个表的列类型sdtype、主外键关系与 PII 标记是 SDV 理解数据结构的关键训练合成器HMASynthesizer是 SDV 的多表层次合成器会根据 metadata 中的表间关系父子表、外键学习联合分布采样生成sample(scale1)表示生成与真实数据同等规模1:1的合成数据落盘将每张合成表写入当前目录下的synthetic_data/文件夹文件名与真实表一一对应。函数末尾会返回成功信息包括生成的表数量与表名列表return fData generated successfully and saved in synthetic_data folder with {len(synthetic_data)} tables named as {list(synthetic_data.keys())} CSV files.前置校验函数会先检查folder_name是否存在、metadata.json是否存在于该目录否则抛出FileNotFoundError并在server.py层被捕获后转为对 Agent 友好的错误字符串。4.2 sdv_evaluate评估合成数据质量mcp.tool() def sdv_evaluate(folder_name: str) - dict: Evaluate the quality of synthetic data compared to real data. This tool compares the synthetic data in the synthetic_data folder with the real data in the specified folder and generates quality metrics. 底层实现tools.py 的evaluatetable_names metadata.tables # 从 metadata 获取所有表名 for table_name in table_names: real_path os.path.join(folder_name, f{table_name}.csv) synthetic_path os.path.join(synthetic_data, f{table_name}.csv) real_data_dict[table_name] pd.read_csv(real_path) synthetic_data_dict[table_name] pd.read_csv(synthetic_path) quality_report evaluate_quality( real_datareal_data_dict, synthetic_datasynthetic_data_dict, metadatametadata, verboseFalse, ) overall_score quality_report.get_score() properties quality_report.get_properties().to_dict(orientrecords) return {Overall Score: overall_score, Properties: properties}评估要点该工具依赖上一步生成的synthetic_data文件夹若不存在会抛出FileNotFoundError提示请先使用生成工具它遍历metadata.tables中的每张表按表名从真实目录与合成目录分别加载数据保证一一对应evaluate_quality返回的质量报告包含整体分数Overall Score与各项属性Properties如列形状、列对趋势、表间关系等维度的子分数最终以{Overall Score: ..., Properties: [...]}的 dict 形式返回给 Agent返回类型为dict便于 LLM 直接读取指标数值并进行后续分析或展示。4.3 sdv_visualize对比真实与合成数据的分布mcp.tool() def sdv_visualize( folder_name: str, table_name: str, column_name: str, ) - str: Generate visualization comparing real and synthetic data for a specific column. This tool creates a visual comparison between the real data in the specified folder and the synthetic data in the synthetic_data folder for a particular table column. The visualization is saved as a PNG file in the evaluation_plots folder. 底层实现tools.py 的visualize核心片段# 1. 校验表与列 if table_name not in metadata.tables: raise ValueError(fTable {table_name} not found in metadata) if column_name not in real_data.columns: raise ValueError(fColumn {column_name} not found in table {table_name}) # 2. 构建 SDV 要求的 dict 结构 real_data_dict {table_name: real_data} synthetic_data_dict {table_name: synthetic_data} # 3. 生成列分布对比图 fig get_column_plot( real_datareal_data_dict, synthetic_datasynthetic_data_dict, metadatametadata, table_nametable_name, column_namecolumn_name, ) # 4. 渲染为 PNG safe_column_name column_name.replace( , _).replace(/, _) filename f{table_name}_{safe_column_name}.png filepath os.path.join(visualization_folder, filename) fig.write_image(filepath) return fVisualization for {table_name}.{column_name} saved successfully at {os.path.abspath(filepath)}可视化要点强校验工具会对table_name须存在于 metadata与column_name须存在于该表真实数据列逐一校验避免无效调用对比方式get_column_plot会同时基于真实数据与合成数据绘制同一列的分布曲线数值列绘制 KDE 密度曲线类别列绘制条形图直接可视化两者的分布贴合度文件命名列名中的空格与/会被替换为_生成如guests_amenities_fee.png的清晰文件名落盘位置图片保存在当前目录的evaluation_plots/文件夹可通过参数visualization_folder自定义并返回文件的绝对路径Agent 可以直接读取该路径向用户展示。五、数据目录与元数据设计项目内置了一套酒店场景的双表真实数据作为示例位于 sdv-mcp/data/文件内容hotels.csv酒店主表hotel_id主键、城市、州、评分、酒店分类RESORT/CHAIN/MOTELguests.csv宾客表guest_email主键、外键hotel_id、是否会员、房型、设施费、入住/退房日期、房价、账单地址、信用卡号metadata.jsonSDV 元数据定义列类型、PII 标记与表间关系5.1 metadata.json 结构解读元数据是 SDV 合成的骨架决定了每列如何建模。以 metadata.json 为例{ tables: { hotels: { columns: { hotel_id: { sdtype: id, regex_format: HID_[0-9]{3,5} }, city: { pii: true, sdtype: city }, rating: { sdtype: numerical }, classification: { sdtype: categorical } }, primary_key: hotel_id }, guests: { columns: { guest_email: { pii: true, sdtype: email }, hotel_id: { sdtype: id, regex_format: HID_[0-9]{3,5} }, checkin_date: { datetime_format: %d %b %Y, sdtype: datetime }, credit_card_number: { pii: true, sdtype: credit_card_number } }, primary_key: guest_email } }, relationships: [ { parent_table_name: hotels, child_table_name: guests, parent_primary_key: hotel_id, child_foreign_key: hotel_id } ], METADATA_SPEC_VERSION: V1 }关键配置语义sdtype语义数据类型id标识符、numerical数值、categorical类别、datetime时间、email/city/administrative_unit/address/credit_card_numberPII 语义类型等SDV 会为每种类型选择对应的建模方式pii: true标记个人身份信息字段合成时会保留其格式与分布但生成的是全新、不可追溯到真实个人的数据regex_format如HID_[0-9]{3,5}约束 ID 类字段的生成格式前缀 3~5 位数字保证主外键的可关联性datetime_format如%d %b %Y指明 CSV 中时间列的原始格式供 SDV 正确解析relationships声明父子表关系hotels.hotel_id→guests.hotel_id这是HMASynthesizer能够跨表生成一致数据的前提METADATA_SPEC_VERSIONSDV 元数据规范版本号V1。5.2 真实数据示例hotels.csv 展示了主表结构如HID_000,Boston,Massachusetts,4.8,RESORTguests.csv 展示了带 PII 字段的宾客数据邮箱、账单地址、信用卡号等。注意 CSV 中日期采用27 Dec 2020这种格式与 metadata 中声明的%d %b %Y严格对应同时存在缺失值如某行amenities_fee为空、某酒店rating为空SDV 在训练时会自动处理这类真实场景中的脏数据。六、端到端实战从自然语言到合成数据项目根目录的 prompt.txt 提供了一组可直接复制到 Cursor 对话中的提示词演示了完整的三个步骤Generate synthetic data from the folder located at 仓库绝对路径/sdv-mcp/data Evaluate the synthetic data that has been generated for the actual data folder located at 仓库绝对路径/sdv-mcp/data Please visualize the amenities_fee column in the guests table from the data located at 仓库绝对路径/sdv-mcp/data I would like to compare the distribution of synthetic data to that of real data for this specific column.实际使用时请将仓库绝对路径替换为你的本地路径。6.1 执行流程推演当你在 Cursor 中粘贴这些提示词后Agent 的行为如下工具发现Cursor 通过 MCP 握手自动发现sdv_generate、sdv_evaluate、sdv_visualize三个工具及其参数 schema调用 sdv_generateAgent 提取folder_namedata目录触发 server.py 中对应的工具函数SDV 完成训练与采样在项目目录生成synthetic_data/hotels.csv与synthetic_data/guests.csv调用 sdv_evaluateSDV 对比真实与合成数据返回整体分数与各属性子分数Agent 可据此判断合成质量调用 sdv_visualize针对guests表的amenities_fee列生成分布对比图保存为evaluation_plots/guests_amenities_fee.pngAgent 拿到绝对路径后即可向用户展示。6.2 使用注意事项路径必须正确folder_name指向的目录必须同时包含 CSV 文件与metadata.json且 CSV 文件名与 metadata 中的表名一一对应严格的调用顺序evaluate与visualize都依赖generate产出的synthetic_data文件夹必须先合成后评估、再可视化本地运行、数据不出域所有计算均在本地完成合成数据不经过任何第三方服务适合处理敏感数据错误反馈每个工具都做了FileNotFoundError与RuntimeError的捕获错误会以字符串/dict 形式返回给 Agent而不是让 Server 崩溃这也体现了工具调用失败也能被 LLM 理解并自我修正的 MCP 设计哲学。七、扩展思考从本项目出发还能做什么从 tools.py 的实现可以推断工具层与 SDV API 是一一对应的薄封装因此很容易继续扩展添加新工具在tools.py中实现新函数、在server.py中加一个mcp.tool()装饰即可例如sdv_get_report将评估报告保存为 HTML/JSON 文件供留存sdv_sample_n暴露sample的num_rows/scale参数按指定行数或比例生成sdv_update_metadata自动从 CSV 推断列类型并生成 metadata降低上手门槛更换合成器目前使用多表HMASynthesizer对于单表场景可替换为 SDV 的GaussianCopulaSynthesizer、CTGANSynthesizer等只需改动tools.py中一行合成器实例化代码接入更多 MCP HostMCP 是开放标准同一个 Server 也可被 Claude Desktop、其他支持 MCP 的 IDE 复用只需配置对应的mcp.json。八、小结本项目通过 MCP 将 SDV 的合成数据能力工具化让 LLM Agent 能够自主完成从数据读取、合成生成、质量评估到可视化对比的完整闭环。全文要点回顾架构CursorMCP Host FastMCP Serverserver.py 业务工具层tools.py SDV 框架四层各司其职三个工具sdv_generateHMASynthesizer 多表合成、sdv_evaluateevaluate_quality质量评分、sdv_visualizeget_column_plot分布对比图元数据是灵魂metadata.json 通过sdtype、pii、regex_format、relationships精确刻画数据结构决定合成质量隐私友好PII 字段被专门标记建模合成数据保留统计特征但无法追溯真实个体且全程本地运行上手路径uv sync安装依赖 → 配置mcp.json注册 Server → 在 Cursor 中用自然语言发起生成、评估、可视化请求参考 prompt.txt 中的示例提示词即可。这套MCP 封装 本地合成数据的组合为数据工程师和 AI 应用开发者提供了一种低门槛、可复用的数据合成基础设施既能让非技术用户用自然语言操作数据又保证了敏感数据不出本机。如需在自有数据集上使用只需仿照 sdv-mcp/data/ 的结构准备 CSV 与 metadata.json即可无缝接入。相关文件索引MCP Server 入口与工具注册server.py业务实现生成/评估/可视化tools.py依赖声明pyproject.toml示例数据与元数据data/、metadata.json使用提示词prompt.txt官方 READMEsdv-mcp/README.md【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考