mcp/fibery

Fibery MCP Server 技术文档

1. 镜像概述与主要用途

Fibery MCP Server 是一个基于模型上下文协议（Model Context Protocol, MCP）的Docker镜像，用于与Fibery工作区进行交互。通过该镜像，用户可通过标准化接口调用Fibery API，实现实体创建、查询、更新等操作，简化与Fibery工作区的集成流程。

关于MCP协议的更多信息：什么是MCP Server？

2. 核心功能与特性

2.1 基本特性

2.2 核心功能

提供7个工具用于与Fibery工作区交互，包括实体管理、数据查询、日期获取等能力：

3. 使用场景与适用范围

• 批量数据管理：通过create_entities_batch批量导入实体数据，适用于项目初始化、数据迁移场景。
• 实体生命周期管理：使用create_entity和update_entity创建、更新任务、功能点等实体，支持工作流自动化。
• 数据查询与分析：通过query_database执行自定义API查询，结合list_databases和describe_database获取数据结构，满足报表生成、数据统计需求。
• 日期依赖场景：利用current_date获取标准格式日期，用于时间条件筛选（如查询今日创建的实体）。

4. 详细使用方法与配置说明

4.1 环境变量配置

运行镜像前需配置以下环境变量：

4.2 部署示例

4.2.1 Docker Run命令

直接通过docker run运行镜像，需挂载环境变量：

bash
docker run -i --rm \
  -e FIBERY_HOST="your-domain.fibery.io" \
  -e FIBERY_API_TOKEN="your-api-token" \
  mcp/fibery

4.2.2 Docker Compose配置

创建docker-compose.yml文件，定义服务配置：

yaml
version: '3'
services:
  fibery-mcp:
    image: mcp/fibery
    environment:
      - FIBERY_HOST=your-domain.fibery.io
      - FIBERY_API_TOKEN=your-api-token
    stdin_open: true  # 保持交互模式
    tty: true         # 分配终端

启动服务：

bash
docker-compose up

4.3 工具使用详情

4.3.1 create_entities_batch：批量创建实体

功能：批量创建指定数据库中的多个实体，支持自定义字段。

参数：

示例：

json
{
  "database": "Product Management/Feature",
  "entities": [
    {
      "Product Management/Name": "用户认证模块",
      "Product Management/Description": "实现邮箱密码登录",
      "workflow/state": "To Do"
    },
    {
      "Product Management/Name": "数据导出功能",
      "Product Management/Description": "支持CSV格式导出数据",
      "workflow/state": "In Progress"
    }
  ]
}

注意：示例中的数据库为虚构，实际使用需替换为用户工作区中存在的数据库。

4.3.2 create_entity：创建单个实体

功能：创建单个实体，支持指定字段配置。

参数：

示例：

json
{
  "database": "Product Management/Feature",
  "entity": {
    "Product Management/Name": "权限管理系统",
    "Product Management/Description": "基于角色的访问控制",
    "workflow/state": "To Do"
  }
}

4.3.3 current_date：获取当前日期

功能：返回当前日期，格式为ISO 8601（YYYY-mm-dd.HH:MM:SS.000Z）。

参数：无。

示例输出：2024-05-20.12:34:56.000Z

4.3.4 describe_database：描述数据库结构

功能：获取指定数据库及其关联数据库的所有字段列表，格式为“标题 [名称]: 类型”。

参数：

示例：

json
{
  "database_name": "Product Management/Feature"
}

示例输出：
名称 [Product Management/Name]: text, 状态 [workflow/state]: enum, 创建时间 [fibery/creation-date]: date

4.3.5 list_databases：列出所有数据库

功能：获取工作区中所有数据库（数据模型）的名称列表。

参数：无。

示例输出：
["Product Management/Feature", "Product Management/Insight", "Administrative/Admin Task"]

4.3.6 query_database：执行自定义API查询

功能：执行任意Fibery API命令，支持复杂条件筛选、字段选择和排序，需熟悉Fibery API语法。

参数：

示例：查询过去2个月创建的功能点

json
{
  "q_from": "Dev/Feature",
  "q_select": {
    "名称": ["Dev/Name"],
    "ID": ["fibery/public-id"],
    "创建时间": ["fibery/creation-date"]
  },
  "q_where": [">", ["fibery/creation-date"], "$twoMonthsAgo"],
  "q_order_by": {"fibery/creation-date": "q/desc"},
  "q_limit": 100,
  "q_params": {
    "$twoMonthsAgo": "2024-03-20T00:00:00.000Z"
  }
}

4.3.7 update_entity：更新实体

功能：更新指定数据库中的实体字段，支持文档字段的追加或覆盖。

参数：

示例：更新实体状态并追加描述

json
{
  "database": "Product Management/Feature",
  "entity": {
    "fibery/id": "12345678-1234-5678-1234-567812345678",  // 实体ID，必填
    "workflow/state": "Done",
    "Product Management/Description": {"append": true, "content": "\n更新：已完成测试。"}
  }
}

5. 许可证

本镜像遵循MIT许可证，详情参见https://github.com/Fibery-inc/fibery-mcp-server/blob/main/LICENSE%E3%80%82

安全说明：使用Docker运行MCP Server可通过容器隔离降低安全风险，详情参见为什么使用Docker运行MCP Server更安全？