docyrus-architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docyrus Architect

Guide for using

docyrus-architect

MCP tools to manage and query data sources in Docyrus.

使用

docyrus-architect

MCP工具管理和查询Docyrus中数据源的指南。

Tool Overview

工具概述

Discovery Tools

发现工具

```
get_apps
```
— List tenant apps. Use before
```
create_data_source
```
to find the target
```
tenantAppId
```
.
```
get_data_source_list
```
— Search data sources by name/description or app ID.
```
get_data_source_list_with_fields
```
— Same as above but includes field names and types.
```
get_data_source_metadata
```
— Get full metadata (fields with IDs, types, slugs, enums, relations) for a data source. Always call this before querying to discover field slugs and relation targets.
```
get_enums_by_field_id
```
— Get enum options for select/status/tagSelect fields.
```
read_current_user
```
/
```
read_tenant_user
```
— Get user info.

```
get_apps
```
— 列出租户应用。在调用
```
create_data_source
```
前使用，以找到目标
```
tenantAppId
```
。
```
get_data_source_list
```
— 按名称/描述或应用ID搜索数据源。
```
get_data_source_list_with_fields
```
— 功能与上述工具相同，但包含字段名称和类型。
```
get_data_source_metadata
```
— 获取数据源的完整元数据（包含字段ID、类型、别名、枚举、关联关系）。查询前务必调用此工具，以发现字段别名和关联目标。
```
get_enums_by_field_id
```
— 获取下拉选择/状态/标签选择类型字段的枚举选项。
```
read_current_user
```
/
```
read_tenant_user
```
— 获取用户信息。

Data Source CRUD

数据源增删改查（CRUD）

create_data_source

— Create a new data source (table). Default fields auto-created:

id

autonumber_id

name

record_owner

created_on

created_by

last_modified_by

last_modified_on

```
update_data_source
```
— Update data source properties.
```
delete_data_source
```
— Delete a data source and all its data.

create_data_source

— 创建新的数据源（表）。默认自动创建以下字段：

id

、

autonumber_id

、

name

、

record_owner

、

created_on

、

created_by

、

last_modified_by

、

last_modified_on

。

```
update_data_source
```
— 更新数据源属性。
```
delete_data_source
```
— 删除数据源及其所有数据。

Field Management

字段管理

create_fields

— Batch create fields. Set

relationDataSourceId

for

field-relation

types.

```
update_fields
```
— Batch update fields. Non-CUSTOM fields get customization records.
```
delete_fields
```
— Batch delete fields by ID.

```
create_fields
```
— 批量创建字段。对于
```
field-relation
```
类型字段，需设置
```
relationDataSourceId
```
。
```
update_fields
```
— 批量更新字段。非自定义字段会生成自定义记录。
```
delete_fields
```
— 按ID批量删除字段。

Enum Management

枚举管理

```
create_enums
```
— Create enum options for select/tagSelect/status fields. Pass
```
fieldId
```
for field-specific enums or
```
enumSetId
```
for shared enum sets.
```
update_enums
```
— Update enum option name/slug/color/icon.
```
delete_enums
```
— Delete enum options.

```
create_enums
```
— 为下拉选择/标签选择/状态类型字段创建枚举选项。针对字段专属枚举，传入
```
fieldId
```
；针对共享枚举集，传入
```
enumSetId
```
。
```
update_enums
```
— 更新枚举选项的名称/别名/颜色/图标。
```
delete_enums
```
— 删除枚举选项。

Query & Compute

查询与计算

```
query_data_source
```
— Read data with filtering, sorting, aggregation, formulas, pivots, child queries. See references/data-source-query-guide.md for complete query syntax.
```
evaluate_jsonata
```
— Test JSONata expressions. Use for validating computed field formulas.

```
query_data_source
```
— 通过筛选、排序、聚合、公式、透视表、子查询读取数据。完整查询语法请参见references/data-source-query-guide.md。
```
evaluate_jsonata
```
— 测试JSONata表达式。用于验证计算字段的公式。

Common Workflows

常见工作流

Create a Data Source with Fields and Enums

创建包含字段和枚举的数据源

Call
```
get_apps
```
to find the target app ID
Call
```
create_data_source
```
with title (plural), name (singular), slug (singular snake_case)
Call
```
create_fields
```
with all custom fields (default fields already exist)
For select/tagSelect/status fields, call
```
create_enums
```
with the field ID from step 3

调用
```
get_apps
```
找到目标应用ID
调用
```
create_data_source
```
，传入复数形式的title、单数形式的name、单数蛇形命名的slug
调用
```
create_fields
```
创建所有自定义字段（默认字段已自动生成）
对于下拉选择/标签选择/状态类型字段，使用步骤3中获取的字段ID调用
```
create_enums
```

Query Data

查询数据

Call
```
get_data_source_metadata
```
to discover field slugs, types, and relations
Call
```
query_data_source
```
with appropriate columns, filters, and sorting
For advanced queries (aggregations, formulas, pivots, child queries), read references/data-source-query-guide.md

调用
```
get_data_source_metadata
```
发现字段别名、类型和关联关系
调用
```
query_data_source
```
并传入合适的列、筛选条件和排序规则
如需进行高级查询（聚合、公式、透视表、子查询），请阅读references/data-source-query-guide.md

Modify Existing Data Source

修改现有数据源

Call
```
get_data_source_metadata
```
to see current fields
Use
```
create_fields
```
/
```
update_fields
```
/
```
delete_fields
```
as needed

For enum changes, use

get_enums_by_field_id

first, then

create_enums

update_enums

delete_enums

调用
```
get_data_source_metadata
```
查看当前字段
根据需要使用
```
create_fields
```
/
```
update_fields
```
/
```
delete_fields
```

如需修改枚举，请先调用

get_enums_by_field_id

，再使用

create_enums

update_enums

delete_enums

Key Rules

关键规则

Data Source Creation

数据源创建

```
title
```
is plural (e.g., "Sales Orders"),
```
name
```
is singular (e.g., "Sales Order"),
```
slug
```
is singular snake_case (e.g., "sales_order")
Use
```
defaultEditFormTarget: "tab"
```
for complex forms,
```
"side"
```
for simple ones
Enable
```
pluginActivityView
```
for CRM-type data sources (leads, contacts, deals)
Enable
```
pluginComments
```
for collaborative data sources
Enable
```
pluginFile
```
when users need to attach files to records
Enable
```
pluginDocyment
```
when users need rich text documents per record

```
title
```
为复数形式（例如："Sales Orders"），
```
name
```
为单数形式（例如："Sales Order"），
```
slug
```
为单数蛇形命名（例如："sales_order"）
复杂表单使用
```
defaultEditFormTarget: "tab"
```
，简单表单使用
```
"side"
```
CRM类数据源（线索、联系人、交易）启用
```
pluginActivityView
```
协作型数据源启用
```
pluginComments
```
需要为记录附加文件时启用
```
pluginFile
```
需要为每条记录添加富文本文档时启用
```
pluginDocyment
```

Field Types

字段类型

```
field-relation
```
requires
```
relationDataSourceId
```
— the ID of the related data source
```
field-list
```
is a virtual field showing child records (one-to-many) — not stored in DB
```
field-select
```
/
```
field-tagSelect
```
/
```
field-status
```
need enum options created after the field
```
field-formula
```
uses JSONata expressions — test with
```
evaluate_jsonata
```
first
```
field-inlineData
```
stores array of objects,
```
field-inlineForm
```
stores single nested object
Field
```
slug
```
must be snake_case matching
```
^[a-z][a-z0-9_]*$
```

```
field-relation
```
类型字段需要
```
relationDataSourceId
```
— 关联数据源的ID
```
field-list
```
是显示子记录的虚拟字段（一对多关系） — 不存储在数据库中
```
field-select
```
/
```
field-tagSelect
```
/
```
field-status
```
类型字段需在创建字段后添加枚举选项
```
field-formula
```
使用JSONata表达式 — 请先使用
```
evaluate_jsonata
```
测试
```
field-inlineData
```
存储对象数组，
```
field-inlineForm
```
存储单个嵌套对象
字段
```
slug
```
必须为蛇形命名，匹配正则
```
^[a-z][a-z0-9_]*$
```

Querying

查询

Use
```
dataSourceId
```
(UUID) to identify which data source to query
```
columns
```
is a comma-separated string of field slugs, not an array
For aggregations, always use
```
id
```
field for
```
count
```
calculations
Relation expansion:
```
relation_field(sub_field1, sub_field2)
```
selects nested columns
Spread operator:
```
...relation_field(alias:sub_field)
```
flattens into root object
Filter on related fields:
```
rel_{{relation_slug}}/{{field_slug}}
```
Date filters have shortcut operators like
```
today
```
,
```
this_month
```
,
```
last_30_days
```

使用
```
dataSourceId
```
（UUID）指定要查询的数据源
```
columns
```
是字段别名的逗号分隔字符串，而非数组
聚合计算时，务必使用
```
id
```
字段进行
```
count
```
统计
关联展开：
```
relation_field(sub_field1, sub_field2)
```
用于选择嵌套列
展开运算符：
```
...relation_field(alias:sub_field)
```
用于将嵌套字段展平至根对象
关联字段筛选：
```
rel_{{relation_slug}}/{{field_slug}}
```
日期筛选支持快捷操作符，如
```
today
```
、
```
this_month
```
、
```
last_30_days
```

query_data_source Required Parameters

query_data_source 必填参数

All parameters are required in the MCP tool schema (most accept

null

```
dataSourceId
```
: string (required, non-null)
```
columns
```
: string | null
```
filters
```
: object | null
```
filterKeyword
```
: string | null
```
orderBy
```
: array | null
```
limit
```
: number | null (default: 1000)
```
offset
```
: number | null
```
fullCount
```
: boolean | null
```
recordId
```
: string | null (fetch single record by ID)
```
calculations
```
: array | null
```
distinctColumns
```
: array | null
```
formulas
```
: array | null
```
childQueries
```
: array | null
```
pivot
```
: object | null

MCP工具架构中所有参数均为必填项（多数参数可接受

null

）：

```
dataSourceId
```
: string（必填，不可为null）
```
columns
```
: string | null
```
filters
```
: object | null
```
filterKeyword
```
: string | null
```
orderBy
```
: array | null
```
limit
```
: number | null（默认值：1000）
```
offset
```
: number | null
```
fullCount
```
: boolean | null
```
recordId
```
: string | null（按ID获取单条记录）
```
calculations
```
: array | null
```
distinctColumns
```
: array | null
```
formulas
```
: array | null
```
childQueries
```
: array | null
```
pivot
```
: object | null

References

参考资料

Data Source Query Guide — Complete reference for
```
query_data_source
```
including columns, filters, aggregations, formulas (simple + block AST), pivots, child queries, and full operator reference. Read this when building complex queries.
Formula Reference — Compact reference for SQL block formulas (inline and subquery). Read this when working with computed formula columns in queries.

数据源查询指南 —
```
query_data_source
```
的完整参考文档，包含列、筛选、聚合、公式（简单版+块AST）、透视表、子查询及完整操作符参考。构建复杂查询时请阅读此文档。
公式参考 — SQL块公式（内联和子查询）的精简参考文档。处理查询中的计算公式列时请阅读此文档。