使用说明

项目简介

该项目是一个基于Model Context Protocol (MCP) 构建的应用后端，专门用于管理数据产品（Data Products）及其关联的数据契约（Data Contracts）。它旨在为大型语言模型（LLM）客户端提供一个标准的、AI友好的接口，以便LLM能够理解、发现、访问和查询数据资产，同时遵守数据契约的规范。

主要功能点

数据资产管理: 支持从本地文件和远程系统（如Data Mesh Manager）加载和组织数据产品和数据契约。
智能数据查询: 允许通过LLM使用自然语言或SQL对数据产品下的输出端口进行数据查询，支持多种底层数据源。
契约合规: 在数据访问和查询过程中考虑并应用数据契约的规范，帮助LLM理解数据结构和使用规则。
灵活识别: 支持使用不同的标识符格式（如资产标识符、URNs等）来引用数据产品和数据契约。
插件化架构: 具有可扩展的插件系统，方便添加新的数据资产来源和新的数据查询引擎。

安装步骤

项目需要Python 3.10 或更高版本。推荐使用 'uv' 包管理器进行安装。

安装 uv (推荐): 访问 https://astral.sh/uv 获取安装指南。

安装项目: 打开终端，进入项目根目录，然后运行以下命令：

使用 uv:
```
uv pip install -e .
```
使用 pip:
```
pip install -e .
```

服务器配置 (面向 MCP 客户端)

本MCP服务器旨在供MCP客户端（如支持MCP协议的AI或工具）使用。MCP客户端需要知道如何启动这个服务器进程。典型的客户端配置会包含服务器的启动命令和必要的参数。

您需要向您的MCP客户端提供如下配置信息：

服务器名称 (Server Name): 您希望在客户端中标识此服务器的名称，例如 'datacontract'。
启动命令 (Command): 用于启动服务器的可执行文件路径，通常是 'python'。
启动参数 (Args): 传递给启动命令的参数列表。对于此服务器，基本启动参数为 '-m src.datacontract_mcp.server --server'，表示以模块方式运行服务器脚本，并进入服务器模式。
环境变量 (Environment Variables): 服务器运行所需的环境变量。至少需要设置 'DATAASSET_SOURCE' 环境变量，指定存放本地数据产品和数据契约文件的目录路径。如果使用Data Mesh Manager源，还需要设置 'DATAMESH_MANAGER_API_KEY' 等。

示例概念配置说明 (非代码):

一个支持MCP的AI客户端会有一个地方（例如配置文件或UI界面）让您添加MCP服务器。您需要填写上面提到的信息：

服务器的逻辑名称 (比如: "我的数据资产")
启动程序路径 (比如: "python")
启动参数 (比如: ["-m", "src.datacontract_mcp.server", "--server"])
环境变量设置 (比如: DATAASSET_SOURCE="您本地存放数据资产的目录路径")

配置完成后，客户端会使用这些信息在需要时启动并连接到此MCP服务器。

基本使用方法

一旦服务器按照上述配置在MCP客户端环境中成功启动并运行，LLM代理就可以通过MCP协议与服务器进行交互。

LLM可以通过调用服务器暴露的工具 (Tools) 来执行操作，例如：

调用 'dataproducts_list' 工具获取所有可用的数据产品列表。
调用 'dataproducts_get' 工具，并提供一个数据产品的标识符（例如 'local:product/orders.dataproduct.yaml' 或 'datameshmanager:product/123'），来获取该数据产品的详细信息。
调用 'dataproducts_get_output_schema' 工具，并提供一个数据契约的标识符，来获取数据契约的Schema定义。
调用 'dataproducts_query' 工具，提供数据产品标识符、要执行的SQL查询和相关的端口/模型信息，来直接查询数据。

此外，LLM还可以访问服务器提供的资源 (Resources)，例如获取数据产品或数据契约的Schema定义或示例。

服务器还提供了一个初始提示 (Initial Prompt)，为LLM提供了关于如何使用服务器和资产标识符格式的重要指南。

关键词