关键词

数据分析语义建模AI数据访问数据平台Malloy

Malloy Publisher（发布者）是一个开源的语义模型服务器，旨在通过结构化的方式暴露基于Malloy语言构建的数据模型，使其可供各种应用程序（尤其是AI代理）消费和交互。

项目简介

Publisher利用Malloy语言强大的语义建模能力，将数据结构、业务逻辑和数据关系编码成可理解的模型。这些模型随后通过标准化的服务器接口（包括Model Context Protocol）发布，确保数据在不同应用中被一致、可靠地访问和解释。这对于缺乏人类上下文理解的AI代理来说尤为重要，可以避免数据误解和分析错误。

主要功能点

  • 托管和管理Malloy包： Publisher加载和管理包含Malloy模型 (.malloy) 和Notebooks (.malloynb) 的标准化包，提供数据资产的版本管理和组织能力。
  • 暴露语义模型： 通过API接口暴露包内的Malloy模型结构，包括数据源 (Sources)、派生视图 (Views) 和命名查询 (Queries)。
  • 执行查询和分析： 允许客户端根据Malloy模型执行Ad-hoc查询或运行预定义的命名查询/视图，并将结果格式化返回。
  • MCP支持： 实现Model Context Protocol (MCP)，使兼容的AI代理和客户端能够发现、理解和交互Malloy模型及其能力（作为MCP的“资源”和“工具”）。
  • 数据库连接： 支持连接多种数据库（如BigQuery, Snowflake, Trino, DuckDB, Postgres, MySQL），将Malloy查询编译成对应的SQL执行。
  • REST API： 提供一套RESTful API，主要用于Web前端应用（如Publisher App）进行模型浏览和查询执行。
  • 灵活的配置： 通过本地配置文件管理项目和数据库连接，支持环境隔离和标准开发实践。

安装步骤

Publisher项目使用 'bun' 作为JavaScript运行时和包管理器。

  1. 克隆仓库： 
    git clone https://github.com/malloydata/publisher.git
cd publisher
  2. 初始化并更新Git子模块： 项目包含Malloy示例作为子模块。 
    git submodule init
git submodule update
  3. 安装依赖： 使用bun安装所有项目依赖。 
    bun install
  4. 构建项目： 编译TypeScript代码。 
    bun run build
  5. 启动Publisher服务器： 启动后台服务器。默认情况下，REST API运行在4000端口，MCP API运行在4040端口。 
    bun run start
    服务器启动后，即可通过配置的地址和端口访问Publisher的API接口。

服务器配置

Publisher服务器通过本地文件 'publisher.config.json'（位于服务器根目录）和每个项目目录下的 'publisher.connections.json' 来管理项目定义和数据库连接。

  • 'publisher.config.json'：定义可用的项目及其路径。
  • 'publisher.connections.json'：在每个项目目录下定义该项目内的数据库连接配置。

MCP客户端连接配置

MCP客户端需要知道Publisher MCP服务器的网络地址和服务器信息才能连接。通常，您不需要配置启动服务器的 'command' 和 'args'，因为Publisher是作为一个独立运行的服务。您需要配置客户端连接到已启动的Publisher服务器的地址。

连接 Publisher MCP 服务器的关键信息是：

  • 服务器名称 (Server Name): 'malloy-publisher-mcp-server'
  • MCP 协议版本 (Specification Version): '2025-03-26'
  • 传输协议 (Transport): 'StreamableHttpServerTransport'（基于HTTP/HTTPS）
  • 服务器地址 (Server URL):
    • 默认主机：'localhost'
    • 默认MCP端口：'4040'
    • MCP端点路径：'/mcp'
    • 完整的默认MCP连接地址通常是：'http://localhost:4040/mcp'

您的MCP客户端配置应包含这些信息，以便通过Streamable HTTP协议连接到Publisher服务器的指定地址。

基本使用方法

一个典型的MCP客户端（如AI代理）与Publisher交互的流程可能如下：

  1. 建立连接： 客户端使用Streamable HTTP协议连接到Publisher MCP服务器地址（例如 'http://localhost:4040/mcp'），并指定服务器名称和协议版本。
  2. 发现资源： 客户端调用 'listResources' 方法，获取服务器上可用的顶层资源列表（例如，列出所有项目）。
  3. 浏览项目和包： 客户端使用 'listResources' 或 'readResource' 方法，根据URI导航到特定的项目和包，发现其中包含的模型、Notebooks、源、视图和查询。例如，'readResource' 可以获取Package Contents URI ('malloy://project/home/package/faa/contents') 来查看其包含的模型和Notebook列表及其metadata。
  4. 理解模型结构： 客户端使用 'readResource' 方法获取特定模型（'.malloy' 文件）的定义（例如，'malloy://project/home/package/faa/models/flights.malloy'），以理解其包含的源、视图和查询的结构、字段和关系。Notebook ('.malloynb') 资源包含文本和代码单元，展示分析步骤。
  5. 执行查询： 客户端调用 'callTool' 方法执行 'malloy/executeQuery' 工具。提供必要的参数，例如：
    • 'projectName': 项目名称 (e.g., 'home')
    • 'packageName': 包名称 (e.g., 'faa')
    • 'modelPath': 模型文件路径 (e.g., 'flights.malloy')
    • 可以提供 'query' 参数执行一个临时的Malloy查询字符串 (e.g., 'run: flights -> { aggregate: count() }')
    • 或者，可以提供 'sourceName' 和 'queryName'（或 'viewName'）参数来执行模型中预定义的命名查询或视图 (e.g., 'sourceName: flights', 'queryName: flights_by_carrier')。
  6. 处理结果： 工具执行结果将以结构化的方式返回，通常包含查询结果数据（JSON格式）、编译后的模型定义和数据样式信息，供客户端进行解释、分析或可视化。

信息

分类

数据库与文件

访问项目