Guide for using docyrus-architect MCP tools to manage and query data sources in 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.
Data Source 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.
create_data_sources_batch — Create multiple data sources with fields and enum options in a single atomic transaction. Supports cross-referencing data sources within the batch by slug for field-relation types. Max 20 data sources per batch.
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.
Enum Management
create_enums — Create enum options for select/tagSelect/status fields. Pass fieldId for field-specific enums or enumSetId for shared enum sets.
regenerate_openapi_spec — Regenerate and upload the tenant's OpenAPI spec after data source or field changes. Accepts optional dataSourceSlugs (string array) to limit scope; omit to include all data sources. Returns the publicUrl of the uploaded spec. Call this after anycreate_data_source, update_data_source, delete_data_source, create_fields, update_fields, or delete_fields operation to keep the spec in sync.
Query & Compute
query_data_source — Read data with filtering, sorting, aggregation, formulas, pivots, child queries. Seereferences/data-source-query-guide.md for complete query syntax.
evaluate_jsonata — Test JSONata expressions. Use for validating computed field formulas.
Custom Queries
get_custom_queries — List non-archived custom queries for the tenant.
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
Call regenerate_openapi_spec to update the OpenAPI spec
Manage a Custom Query Lifecycle
Call get_custom_queries to find an existing query or confirm naming
Call create_custom_query with name, query, and optional description/filters
Call get_custom_query_by_id to verify the saved template and filter definitions
Use update_custom_query for targeted edits (rename, revise SQL template, update filter definitions)
Use delete_custom_query only when archival is explicitly requested
Run and Debug a Custom Query
Call get_custom_query_by_id first to inspect SQL template and available filter slugs
Build runtime filters with rules[].field values that match the query's filter slugs
Call run_custom_query with simulate: true for complex or untrusted queries to inspect plan output
Call run_custom_query with simulate: false (or omitted) to fetch real data
Use offset for pagination and expect a max of 50,000 rows per execution
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
Field Types
field-relation requires relationDataSourceId — the ID (UUID) of the related data source, or in batch operations, the slug of another data source in the same batch
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:
In create_fields: call create_enums after field creation
In create_data_sources_batch: include inline enumOptions array in the field definition
Batch Operations
create_data_sources_batch creates up to 20 data sources in a single transaction
Within a batch, reference other data sources using their slug for relationDataSourceId
For external data sources (created outside the batch), use the UUID for relationDataSourceId
Data source slugs must be unique within the batch (validation error otherwise)
Inline enum options are defined per-field using the enumOptions array
Each enum option in enumOptions can specify: name, slug, color, icon,
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
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,
query_data_source Required Parameters
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
Custom Query Rules
Treat custom query query content as a Handlebars SQL template, not static SQL.
Use built-in context variables in templates when relevant: TENANT_ID, TENANT_SCHEMA, USER_ID, USER_EMAIL, USER_FIRSTNAME, USER_LASTNAME, USER_FULLNAME.
Use {{filter FILTERS.<slug> <column_expression>}} for optional runtime filtering. If no runtime value is provided, the helper resolves to 1=1.
References
Data Source Query Guide — Up-to-date reference for query_data_source including columns, filters, orderBy, pagination, calculations, formulas, pivots, child queries, and operator details.
Custom Query Guide — Full lifecycle and execution reference for get_custom_queries, get_custom_query_by_id, create_custom_query, update_custom_query, delete_custom_query, and run_custom_query.
