docyrus-architect

Docyrus Architect

Docyrus でデータソースを管理・照会するための docyrus-architect MCP ツールの使用ガイドです。

ツールの概要

検出ツール

• get_apps — テナントのアプリを一覧表示します。対象の tenantAppId を見つけるため、create_data_source の前に使用します。
• get_data_source_list — 名前、説明、またはアプリ ID でデータソースを検索します。
• get_data_source_list_with_fields — 上記と同じ検索を行いますが、フィールド名と型も含めて返します。
• get_data_source_metadata — データソースの完全なメタデータ（ID、型、スラッグ、列挙値、リレーションを含むフィールド）を取得します。フィールドのスラッグとリレーションの参照先を確認するため、クエリの前には必ず呼び出してください。
• get_enums_by_field_id — 選択、ステータス、tagSelect フィールドの列挙値オプションを取得します。
• read_current_user / read_tenant_user — ユーザー情報を取得します。

データソースの CRUD

• create_data_source — 新しいデータソース（テーブル）を作成します。デフォルトのフィールドとして、id、autonumber_id、name、record_owner、created_on、created_by、last_modified_by、last_modified_on が自動作成されます。
• create_data_sources_batch — フィールドと列挙値オプションを含む複数のデータソースを、単一のアトミックなトランザクションで作成します。field-relation 型では、スラッグを使ってバッチ内のデータソースを相互参照できます。1 バッチにつき最大 20 個のデータソースを作成できます。
• update_data_source — データソースのプロパティを更新します。
• delete_data_source — データソースとそのすべてのデータを削除します。

フィールド管理

• create_fields — フィールドを一括作成します。field-relation 型では relationDataSourceId を設定します。
• update_fields — フィールドを一括更新します。CUSTOM 以外のフィールドにはカスタマイズレコードが作成されます。
• delete_fields — ID を指定してフィールドを一括削除します。

列挙値管理

• create_enums — select/tagSelect/status フィールドの列挙値オプションを作成します。フィールド固有の列挙値には fieldId を、共有列挙値セットには enumSetId を渡します。
• update_enums — 列挙値オプションの名前、スラッグ、色、アイコンを更新します。
• delete_enums — 列挙値オプションを削除します。

OpenAPI 仕様

• regenerate_openapi_spec — データソースまたはフィールドの変更後、テナントの OpenAPI 仕様を再生成してアップロードします。対象を絞るには、省略可能な dataSourceSlugs（文字列配列）を指定します。省略すると、すべてのデータソースが対象になります。アップロードされた仕様の publicUrl を返します。仕様との同期を保つため、create_data_source、update_data_source、delete_data_source、create_fields、update_fields、または delete_fields の操作後には、必ず呼び出してください。

クエリと計算

• query_data_source — フィルタリング、並べ替え、集計、数式、ピボット、子クエリを使ってデータを読み取ります。クエリ構文の全容については、references/data-source-query-guide.md を参照してください。
• evaluate_jsonata — JSONata 式をテストします。計算フィールドの数式の検証に使用します。

カスタムクエリ

• get_custom_queries — テナントのアーカイブされていないカスタムクエリを一覧表示します。
• get_custom_query_by_id — カスタムクエリの定義全体（name、description、query、filters）を読み取ります。
• create_custom_query — Handlebars 変数と省略可能なフィルター定義を使って、保存済みの SQL テンプレートを作成します。
• update_custom_query — 既存のカスタムクエリの指定したフィールドを更新します（部分更新）。
• delete_custom_query — カスタムクエリをソフト削除（アーカイブ）します。
• run_custom_query — 保存済みのカスタムクエリを、実行時フィルター、ページネーションオフセット、省略可能なシミュレーションモードを指定して実行します。

一般的なワークフロー

フィールドと列挙型を含むデータソースの作成

単一のデータソースを作成する方法：

1. get_apps を呼び出して、対象アプリの ID を確認します
2. タイトル（複数形）、名前（単数形）、スラッグ（単数形の snake_case）を指定して create_data_source を呼び出します
3. すべてのカスタムフィールドを指定して create_fields を呼び出します（デフォルトフィールドはすでに存在します）
4. select／tagSelect／status フィールドの場合は、手順 3 で取得したフィールド ID を使って create_enums を呼び出します
5. regenerate_openapi_spec を呼び出して、OpenAPI 仕様を更新します

一括作成する方法（複数のデータソースを作成する場合に推奨）：

1. get_apps を呼び出して、対象アプリの ID を確認します（任意。デフォルトは「Default Customizations App」です）
2. データソース定義の配列を指定して create_data_sources_batch を呼び出します（最大 20 件）
   • 各データソースには title、name、slug、fields 配列を含めます
   • select／status／tagSelect フィールドには、インラインの enumOptions を含められます
   • 同じバッチ内の他のデータソースを参照するには、relationDataSourceId にスラッグ参照を使用します
   • すべてのデータソース、フィールド、列挙型は、単一のアトミックトランザクションで作成されます
3. regenerate_openapi_spec を呼び出して、OpenAPI 仕様を更新します

データのクエリ

1. get_data_source_metadata を呼び出して、フィールドのスラッグ、型、リレーションを確認します
2. 適切な列、フィルター、並べ替えを指定して query_data_source を呼び出します
3. 高度なクエリ（集計、数式、ピボット、子クエリ）については、references/data-source-query-guide.md を参照してください

既存のデータソースの変更

1. get_data_source_metadata を呼び出して、現在のフィールドを確認します
2. 必要に応じて create_fields ／ update_fields ／ delete_fields を使用します
3. 列挙型を変更する場合は、まず get_enums_by_field_id を使用し、その後 create_enums ／ update_enums ／ delete_enums を使用します
4. regenerate_openapi_spec を呼び出して、OpenAPI 仕様を更新します

カスタムクエリのライフサイクル管理

1. get_custom_queries を呼び出して、既存のクエリを探すか、命名を確認します
2. name、query、および任意の description ／ filters を指定して create_custom_query を呼び出します
3. get_custom_query_by_id を呼び出して、保存されたテンプレートとフィルター定義を確認します
4. 対象を絞った編集（名前の変更、SQL テンプレートの修正、フィルター定義の更新）には update_custom_query を使用します
5. 明示的にアーカイブを依頼された場合にのみ delete_custom_query を使用します

カスタムクエリの実行とデバッグ

1. まず get_custom_query_by_id を呼び出して、SQL テンプレートと利用可能なフィルタースラッグを確認します
2. クエリのフィルタースラッグに一致する rules[].field の値を使って、実行時の filters を作成します
3. 複雑なクエリや信頼できないクエリでは、simulate: true を指定して run_custom_query を呼び出し、実行計画の出力を確認します
4. simulate: false（または省略）を指定して run_custom_query を呼び出し、実際のデータを取得します
5. ページネーションには offset を使用します。1 回の実行で取得できる行数は最大 50,000 行です

主なルール

データソースの作成

• title は複数形（例：「Sales Orders」）、name は単数形（例：「Sales Order」）、slug は単数形の snake_case（例：「sales_order」）にします
• 複雑なフォームには defaultEditFormTarget: "tab"、シンプルなフォームには "side" を使用します
• CRM タイプのデータソース（リード、連絡先、商談）では、pluginActivityView を有効にします
• コラボレーション用のデータソースでは、pluginComments を有効にします
• レコードにファイルを添付する必要がある場合は、pluginFile を有効にします
• レコードごとにリッチテキストドキュメントが必要な場合は、pluginDocyment を有効にします

フィールドの種類

• field-relation には relationDataSourceId が必要です。関連するデータソースの ID（UUID）、または一括操作の場合は同じバッチ内にある別のデータソースのスラッグを指定します
• field-list は子レコード（1 対多）を表示する仮想フィールドで、DB には保存されません
• field-select ／ field-tagSelect ／ field-status には列挙型のオプションが必要です：
  • create_fields では、フィールドの作成後に create_enums を呼び出します
  • create_data_sources_batch では、フィールド定義にインラインの enumOptions 配列を含めます
• field-formula は JSONata 式を使用します。最初に evaluate_jsonata でテストしてください
• field-inlineData はオブジェクトの配列を保存し、field-inlineForm は単一のネストされたオブジェクトを保存します
• フィールドの slug は、^[a-z][a-z0-9_]*$ に一致する snake_case である必要があります
• 列挙型オプションの slug は、^[a-z][a-z0-9_]*$ に一致する snake_case である必要があります（指定されていない場合は名前から自動生成されます）

一括操作

• create_data_sources_batch は、1 回のトランザクションで最大 20 個のデータソースを作成します
• バッチ内では、relationDataSourceId に他のデータソースの slug を指定して参照します
• バッチ外で作成された外部データソースには、relationDataSourceId として UUID を使用します
• データソースのスラッグはバッチ内で一意である必要があります（それ以外の場合は検証エラーになります）
• インラインの列挙型オプションは、フィールドごとに enumOptions 配列で定義します
• enumOptions 内の各列挙型オプションには、name、slug、color、icon、sortOrder を指定できます
• バッチ操作が失敗すると、すべての変更がロールバックされます（アトミックトランザクション）
• 関連するデータソースを作成するときは、API 呼び出しの回数を減らし、一貫性を確保するために、一括操作を使用してください

クエリ

• クエリ対象のデータソースを識別するには、dataSourceId（UUID）を使用します
• columns はフィールドスラッグをカンマ区切りで指定する文字列であり、配列ではありません
• 集計では、count の計算に必ず id フィールドを使用します
• リレーションの展開：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 の必須パラメーター

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

カスタムクエリのルール

• カスタムクエリの query の内容は、静的な SQL ではなく Handlebars SQL テンプレートとして扱います。
• 必要に応じて、テンプレート内の組み込みコンテキスト変数を使用します：TENANT_ID、TENANT_SCHEMA、USER_ID、USER_EMAIL、USER_FIRSTNAME、USER_LASTNAME、USER_FULLNAME。
• 任意の実行時フィルタリングには {{filter FILTERS.<slug> <column_expression>}} を使用します。実行時の値が指定されていない場合、ヘルパーは 1=1 に解決されます。
• create_custom_query ／ update_custom_query の filters 定義は、テンプレートでの使用方法に合わせます：
  • テンプレートでの使用方法：FILTERS.<slug>
  • 実行時ルールのフィールド：<slug>
  • フィルター定義のスラッグ：<slug>
• 負荷の高いクエリを実行する前に、simulate: true を指定して EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) の出力を確認することを推奨します。
• run_custom_query の実行時制限を守ってください：最大 50,000 行、通常実行時のタイムアウトは 15 秒、シミュレーションモードのタイムアウトは 30 秒です。
• delete_custom_query は完全削除ではなく、アーカイブ操作（論理削除）として使用します。
• JSONB を使用するシンプルなデータソースでは、カスタムフィールドに (table_alias."data"->>'field-uuid')::type でアクセスします。

参考資料

• データソースクエリガイド — query_data_source の最新のリファレンスです。列、フィルター、orderBy、ページネーション、計算、数式、ピボット、子クエリ、演算子の詳細を含みます。
• 数式設計ガイド（LLM） — クエリリクエストで使用する数式ペイロードの設計に関する最新のガイドです。
• カスタムクエリガイド — get_custom_queries、get_custom_query_by_id、create_custom_query、update_custom_query、delete_custom_query、run_custom_query のライフサイクル全体と実行に関するリファレンスです。