| health_pingA | Simple smoke test tool to verify the MCP server is up and responsive.
Not related to RESTForge operations — purely for verifying MCP transport. USE WHEN: Verifying that the MCP server itself is reachable and responsive Checking if the server can receive and respond to tool calls Diagnosing whether a problem is in the MCP transport layer or in a specific tool The user asks things like "ping the MCP server", "is the MCP server alive",
"cek MCP server", "MCP server jalan tidak", "test the MCP connection",
"apakah MCP-nya nyala", "smoke test the server"
DO NOT USE FOR: Validating the RESTForge license or database connection -> use 'setup_validate_config' Reading the active configuration of a project -> use 'setup_read_env' Anything related to RESTForge state, configuration, or project setup
This tool runs in-process: it does not touch the filesystem, network, or any RESTForge component.
Output: "pong" with ISO 8601 timestamp and server version, plus the optional echoed message. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "verify the MCP server is responsive", "validate the configuration"). Speak in plain language. Confirm that the MCP server is responsive and report the timestamp and server version. Keep the reply concise; this is a smoke test, not a diagnostic dump.
|
| setup_create_folderA | Create a new folder to serve as the root of a RESTForge project. The folder will host node_modules (restforgejs), config/, payload/, and generated src/. USE WHEN: The user wants to set up a new RESTForge project working folder Starting a RESTForge project from scratch in a specific location The user says things like "buat folder project baru", "create a new project folder",
"siapkan folder untuk project baru", "make a directory for my new RESTForge project",
"bikinkan project baru di folder X", "scaffold a new restforge project" A safe mkdir with collision detection is needed
DO NOT USE FOR: Installing the restforgejs package -> use 'setup_install_package' Generating skeleton config -> use 'setup_init_config' Writing credentials -> use 'setup_write_env'
This is typically the very first step in setting up a new RESTForge project.
The natural next step after this is 'setup_install_package' to install the
RESTForge package into the new folder. // per §5.2 This tool runs: fs.mkdir(/, { recursive: true })
Output: absolute path of the created folder. Pass this path as 'cwd' to subsequent setup_* tools. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "set up the initial config"). Speak in plain language. Confirm the folder was created and state the absolute path. When the folder already exists and force was not set, frame it as a choice or question, not as a hard error.
|
| setup_install_packageA | Install the restforgejs package into the project's node_modules via npm. USE WHEN: The user wants to install RESTForge (restforgejs) into a project The project folder exists but does not yet have restforgejs in node_modules Setting up a new project before the configuration stage Updating restforgejs to a specific tag or version The user says things like "install restforge", "tambahkan restforgejs",
"pasang package restforge", "set up the package", "siapkan project ini",
"upgrade restforgejs", "ganti versi restforge"
DO NOT USE FOR: Creating a new project folder -> use 'setup_create_folder' Generating config skeleton -> use 'setup_init_config' Filling in credentials -> use 'setup_write_env' Validating the configuration -> use 'setup_validate_config'
This tool sits in the middle of the new-project setup chain: typically run
after 'setup_create_folder' creates the project folder, and before
'setup_init_config' which generates the configuration skeleton. 'setup_init_config'
will return a precondition message if this tool has not been run first. // per §5.2 This tool runs: npm install restforgejs@ in the given cwd (local install, not global).
Default version is "beta" because RESTForge is currently a public pre-release. Use "latest" once stable, or a specific version (e.g. "1.2.3"). PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "create the project folder", "generate the initial config", "fill in the credentials"). Speak in plain language. Summarise the result; do not paste raw npm output unless the user explicitly asks. When a precondition is not met (e.g. the project folder is missing), frame it as a question or next-step suggestion rather than an error.
|
| setup_init_configA | Generate skeleton config and sample payloads in the project folder via restforge-cli. USE WHEN: The project has restforgejs installed in node_modules The config/ and payload/ folders do not exist yet, or you want to reset them to the default template Starting RESTForge project configuration from scratch
DO NOT USE FOR: This tool runs: npx restforge-cli init in the given cwd.
Output: config/db-connection.env (empty template), payload/samples.json, payload/query/samples-datatables.sql. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "fill in the credentials"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| setup_write_envA | Write license, server settings, and database credentials into config/db-connection.env using a partial-merge strategy that preserves all other parameters and comments in the file. USE WHEN: The user provides a complete set of license + database credentials in one go The user is doing initial credential setup (first time filling in the empty template) You need to fill in or update ALL core connection fields together (license,
server, database) — even if some values are already set, this tool will
overwrite them consistently The user says things like "isi credentials", "setup koneksi database",
"fill in the connection info", "atur license dan database"
DO NOT USE FOR: Generating the initial config skeleton -> use 'setup_init_config' Changing only one or two fields (e.g. just the password, or toggle a flag) -> use 'setup_update_env' Validating license/connection -> use 'setup_validate_config'
Behavior: read existing file, update LICENSE/SERVER_/DB_ entries in place, append any missing keys at the bottom, and write back. Comments, blank lines, and unrelated parameters are preserved verbatim. Output file: /config/db-connection.env. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "set up the initial config", "update a single value", "validate the connection"). Speak in plain language. Summarise what was written; do not paste the full field list unless the user explicitly asks. Do not echo sensitive values (license keys, passwords) into chat even when they appear masked in the response. Confirm only that they were set. When a precondition is not met (e.g. config file is missing), frame it as a question or next-step suggestion rather than an error.
|
| setup_read_envA | Read and parse the config/db-connection.env file, returning all parameters as KEY=value lines. Sensitive fields (LICENSE, DB_PASSWORD, REDIS_PASSWORD, KAFKA_SASL_PASSWORD) are masked by default. USE WHEN: The user asks to see the active/current configuration, parameters,
settings, or env values of a RESTForge project The user asks questions like "tampilkan parameter yang aktif",
"config apa yang sudah di-set", "show current settings", "cek konfigurasi",
"what's configured in this project" Verifying the current configuration before calling 'setup_write_env' or
'setup_update_env' to make changes Auditing the active config after a change Listing every parameter present in the file (including optional sections
like Live Sync, Redis, Kafka, Logging) Checking whether a RESTForge project has been set up at all (this tool
returns a clear "file not found" precondition if not)
DO NOT USE FOR: This tool is READ-ONLY and safe to call repeatedly. Pass unmask=true to see real values of sensitive fields (use with care). PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "set up the initial config", "fill in the credentials", "update a single value", "validate the connection"). Speak in plain language. Summarise the result; do not paste the full KEY=value list unless the user explicitly asks for it. Even when unmask=true, do not echo sensitive values (license keys, passwords) into chat unless the user explicitly asks. Prefer to confirm presence and length only. When a precondition is not met (e.g. config file is missing), frame it as a question or next-step suggestion rather than an error.
|
| setup_update_envA | Apply a partial update to config/db-connection.env. Accepts an arbitrary set of key/value pairs and merges them into the existing file, preserving comments, blank lines, and untouched parameters. USE WHEN: Toggling individual feature flags (e.g. LIVE_SYNC_ENABLED, REDIS_ENABLED, KAFKA_ENABLED) Adjusting one or two values without restating the whole core connection Adding a new optional parameter that is not in the template
DO NOT USE FOR: Generating the initial config skeleton -> use 'setup_init_config' Bulk write of license + DB credentials -> use 'setup_write_env' Validating connection -> use 'setup_validate_config'
Behavior: read existing file, replace matching keys (preserving inline comments), append non-existing keys at the bottom, write back. Values may be string, number, or boolean (booleans serialize as 'true'/'false'). Values containing spaces, '=' or '#' are auto-quoted. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "set up the initial config", "fill in the credentials", "validate the connection"). Speak in plain language. Summarise the result by counting and naming the changed keys; do not paste the full diff block unless the user explicitly asks. Do not echo sensitive values (license keys, passwords) into chat even when they appear masked in the response. Confirm presence and length only. When a precondition is not met (e.g. config file is missing), frame it as a question or next-step suggestion rather than an error.
|
| setup_validate_configA | Validate the RESTForge license and connections to database, redis, and kafka based on the config file. USE WHEN: The db-connection.env file has been filled in (license + DB credentials) After credentials have been written or updated, to verify they actually work Before starting runtime or codegen operations Verifying license and access to external services before deploy Diagnosing configuration issues The user asks things like "test connection", "cek license", "validate config",
"apakah config sudah benar", "is the database reachable", "tes koneksi",
"verify the configuration", "cek apakah license valid" Before validating, consider calling 'setup_read_env' to confirm what is
currently set — especially when the user describes the validation relative
to a recent change (e.g. "cek apakah license barunya valid"). // per §5.3 The user wants to validate CONFIGURATION (license, database connection, kafka, redis), not payload files
DO NOT USE FOR: Writing the config file -> use 'setup_write_env' Adjusting individual fields -> use 'setup_update_env' Generating module code -> use codegen_* domain tools Checking if payload JSON files are still in sync with the database schema -> use 'codegen_validate_payload'
Often called as the final step after 'setup_write_env' or 'setup_update_env'
has filled in or changed credentials, to confirm that they actually work. // per §5.2 This tool runs: npx restforge validate --config= in the given cwd.
This tool is READ-ONLY and safe to call repeatedly. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "fill in the credentials", "update a single value", "set up the initial config"). Speak in plain language. Summarise the validation result by component (license, database, optional redis/kafka); do not paste the raw CLI output unless the user explicitly asks. The CLI output may contain license fragments, host names, or user names. Do not echo license keys, passwords, or full connection URIs into chat. Confirm validation status only. When a precondition is not met (e.g. config file is missing), frame it as a question or next-step suggestion rather than an error.
|
| setup_get_config_schemaA | Get JSON schema of all parameters available in db-connection.env template.
Schema includes parameter name, section, type (string/integer/boolean), default value,
description, and required status. USE WHEN: The agent needs to know what parameters are configurable before writing config Listing available config options for user reference Building a dynamic UI or validator from the schema The user asks things like "what parameters are available", "list all config options",
"parameter apa saja yang bisa di-set", "tampilkan schema config", "what can I configure",
"show me the configurable fields", "field apa saja yang valid"
DO NOT USE FOR: Reading actual current config values -> use 'setup_read_env' Writing config -> use 'setup_write_env' or 'setup_update_env' Getting raw template text -> use 'setup_get_init_template'
This tool runs: npx restforge-cli config:schema in the given cwd.
The schema is sourced from restforge-cli (single source of truth) so it stays
in sync with the restforge runtime version installed in the project.
Requires restforgejs >= 2.3.1. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "fill in the credentials"). Speak in plain language. Summarise the schema (number of parameters, sections present, key required fields); do not paste the entire JSON unless the user explicitly asks for it. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| setup_get_init_templateA | Get raw template content of db-connection.env without writing any file.
Useful as reference after current file has been modified, or for comparing
current config against template defaults (drift detection). USE WHEN: The agent needs to see template defaults after the current file has been modified Comparing current config with template (drift detection) Restoring template content reference without re-running init The user asks things like "show me the default template", "lihat template config default",
"apa isi template defaultnya", "what does the default config look like",
"bandingkan dengan template asli", "compare against the original template"
DO NOT USE FOR: Generating new config files in the project -> use 'setup_init_config' Reading current config -> use 'setup_read_env' Getting structured schema (JSON) -> use 'setup_get_config_schema'
This tool runs: npx restforge-cli config:template in the given cwd.
This tool is READ-ONLY and safe to call repeatedly. No file is written.
Requires restforgejs >= 2.3.1. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "set up the initial config", "show the active configuration"). Speak in plain language. Summarise what the template contains (sections present, total parameters); do not paste the entire template body unless the user explicitly asks for it. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| codegen_generate_payloadA | Generate a payload spec file (metadata, fields, action specs) from a database table by introspecting its schema via restforge-cli. USE WHEN: The user asks to generate a payload, payload spec, or payload metadata file from a database table The user asks things like "buatkan payload dari table X", "generate payload guest_book", "scan schema table to JSON", "create payload for endpoint generation" The user wants to "introspect" or "scan" a database table into a JSON spec Starting CLI codegen workflow after the project config has been validated Re-generating payload after a schema change in the database
DO NOT USE FOR: Filling in credentials in db-connection.env -> use 'setup_write_env' Validating config before generating payload -> use 'setup_validate_config' Creating the project / endpoint code from a payload -> that is the next CLI step (will be wrapped in a future tool, not yet available)
This tool runs: npx restforge-cli payload --table= --config= in the given cwd.
The CLI connects to the database described in the config file, reads the table schema,
and writes a payload JSON file (e.g. table 'guest_book' -> 'guest-book.json' with underscore
mapped to hyphen). The payload file is the input for the next codegen step (project + endpoint creation). Preconditions: The project must have restforgejs installed in node_modules. The config file (default 'db-connection.env') must exist in the project and contain valid
database credentials. This tool does not pre-check that — if the CLI fails, the failure response
will surface the underlying cause.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "fill in the credentials", "generate the payload"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_validate_payloadA | Validate that existing payload spec files in a project are still in sync with the current database schema, by running restforge-cli payload --validate. USE WHEN: The user asks to validate, check, or verify whether existing payload files are still in sync with the current database schema The user asks things like "cek drift payload", "validate semua payload", "apakah payload masih sinkron", "is the schema in sync", "check schema drift" The user mentions ALTER TABLE in the database and wants to know which payloads are affected Routine drift check after pulling new database migrations Periodic audit of payload files in a project Often called before 'codegen_diff_payload' as a quick overall status pass; if a file shows DRIFT, follow up with 'codegen_diff_payload' to see column-level details. The user wants to validate PAYLOAD FILES against the database schema, not configuration credentials
DO NOT USE FOR: Seeing the per-column detail of what changed -> use 'codegen_diff_payload' Generating a payload from scratch for a table that has no payload yet -> use 'codegen_generate_payload' Updating payload files to match the database -> use 'codegen_sync_payload' Checking the database connection, license, or other config credentials -> use 'setup_validate_config'
This tool runs: npx restforge-cli payload --validate --config= [--table=] [--output=] in the given cwd.
The CLI reads existing payload JSON files from the output directory, connects to the database described
in the config file, and reports per-file status (typically OK / DRIFT / ERROR) without modifying any file. Preconditions: The project must have restforgejs installed in node_modules. The config file (default 'db-connection.env') must exist in the project and contain valid
database credentials. This tool does not pre-check that — if the CLI fails, the failure response
will surface the underlying cause.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "validate the payload files", "see the column-level differences", "sync the payload files"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_diff_payloadA | Show the column-level differences between existing payload spec files and the current database schema, by running restforge-cli payload --diff. USE WHEN: The user asks to see the detailed differences between a payload file and the current database schema (column-level) The user asks things like "tunjukkan diff payload", "apa yang berubah di table X", "kolom apa saja yang baru", "show schema diff", "what columns changed" After 'codegen_validate_payload' reported DRIFT and the user wants to know what specifically changed Pre-flight inspection before deciding whether to run sync Often called after 'codegen_validate_payload' once a DRIFT status is reported, to drill into the column-level differences for the affected file.
DO NOT USE FOR: Quick overall status (OK / DRIFT / ERROR per file) -> use 'codegen_validate_payload' Generating a payload from scratch for a table that has no payload yet -> use 'codegen_generate_payload' Applying the changes to payload files -> use 'codegen_sync_payload'
This tool runs: npx restforge-cli payload --diff --config= [--table=] [--output=] in the given cwd.
The CLI reads existing payload JSON files from the output directory, connects to the database described
in the config file, and prints a per-column diff (added, removed, or type-changed columns) without
modifying any file. The CLI typically uses '[+]' for added columns, '[-]' for removed columns,
and '[~]' for type-changed columns. Preconditions: The project must have restforgejs installed in node_modules. The config file (default 'db-connection.env') must exist in the project and contain valid
database credentials. This tool does not pre-check that — if the CLI fails, the failure response
will surface the underlying cause.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "see the column-level differences", "do a quick overall validation", "sync the payload files"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_sync_payloadA | Apply schema drift to existing payload spec files in a project, archiving the previous version of each updated file, by running restforge-cli payload --sync. USE WHEN: The user asks to apply schema drift changes to payload files, sync payload files with the database, or update payload JSON files to match the current schema The user asks things like "sinkronisasi payload", "update payload sesuai database", "apply schema drift", "sync payload files", "terapkan perubahan schema", "samakan payload dengan database" After 'codegen_diff_payload' reported column-level differences and the user has reviewed them, wanting to apply the changes After ALTER TABLE in the database when the user wants to bring all payload files in line with the new schema The user mentions creating an archive of the previous payload before regenerating endpoints Before applying changes, strongly consider calling 'codegen_diff_payload' first to confirm what will change in each file (read-before-write per §5.3 — sync overwrites the active payload file and produces an archive that the user may want to inspect later).
DO NOT USE FOR: Just checking which payload files have drift (without modifying anything) -> use 'codegen_validate_payload' Looking at the per-column differences without applying them -> use 'codegen_diff_payload' Generating a payload from scratch for a table that has no payload yet -> use 'codegen_generate_payload' Cleaning up or deleting old '.archive.NNN' files — this tool does not handle archive cleanup; the user must remove archive files manually if desired
This tool runs: npx restforge-cli payload --sync --config= [--table=] [--output=] in the given cwd.
The CLI reads existing payload JSON files from the output directory, connects to the database described
in the config file, and rewrites each payload file whose schema has drifted. Before overwriting, the
previous file content is renamed to '.archive.NNN' (NNN is a sequential number starting at 001).
Files that are already in sync are not touched. The CLI prints a per-file status (typically [SKIP],
[ARCHIVE], [SYNCED]) followed by a Summary section with totals. If the sync run fails partway through (e.g. database connection drops), the CLI restores the archived
file back to its original name so the active payload is not left corrupted. Preconditions: The project must have restforgejs installed in node_modules. The config file (default 'db-connection.env') must exist in the project and contain valid
database credentials. This tool does not pre-check that — if the CLI fails, the failure response
will surface the underlying cause.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "update the payload files", "see the column-level differences first", "regenerate the endpoint code from the updated payload"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_get_field_validation_catalogA | Get authoritative JSON catalog of field validation spec (data types, constraints, format presets, audit columns convention, message override pattern) used in payload fieldValidation arrays. USE WHEN: The user asks about valid field validation constraints, types, format presets, or audit columns convention in payload JSON The user asks things like "constraint apa yang valid untuk tipe X", "list field validation constraints", "tampilkan catalog validasi", "what validation rules can I use", "format preset apa saja", "show me the validation spec" Before generating or editing the fieldValidation array in a payload file — to ground constraint names, scope correctness, and the message override pattern. Often called before 'codegen_generate_payload' for grounding the initial generation, or before manual editing of an existing payload. The user mentions adding validation to a payload field but is unsure which constraint name to use The user asks about audit columns convention (auditColumns: false, override custom names, valid/rejected values, etc.) The user asks about the message override pattern ({constraintName}Message) The user reports a typo-like error such as maxLenght or wonders whether minLength works on a number field — fetch the catalog to ground the answer The user wants to add validation rules at APPLICATION LAYER in payload JSON (validation runs in generated model code, returns HTTP 400 with structured error before the request reaches the database), NOT native SQL DDL constraints (NOT NULL, UNIQUE, CHECK at database level)
DO NOT USE FOR: Validating actual payload files against the database schema -> use 'codegen_validate_payload' Validating config (license, database connection) -> use 'setup_validate_config' Reading the active database connection config schema -> use 'setup_get_config_schema' Generating a payload from scratch -> use 'codegen_generate_payload' Applying changes to payload files -> use 'codegen_sync_payload' Generating SQL DDL constraints (NOT NULL, UNIQUE, CHECK, REFERENCES, ALTER TABLE, CREATE INDEX) — these are database-level and out of scope for RESTForge field validation. They require direct SQL or a database migration tool.
This tool runs: npx restforge-cli field-validation:catalog in the given cwd.
The catalog is sourced from restforge-cli (single source of truth) so it stays in sync with
the restforge runtime version installed in the project.
Requires restforgejs >= 2.4.0. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "generate the payload", "edit the validation rules"). Speak in plain language. Summarise the catalog (number of types, constraints, format presets); do not paste the entire JSON unless the user explicitly asks for it. If the user uses SQL DDL terminology (NOT NULL, UNIQUE, CHECK, ALTER TABLE, REFERENCES, CREATE INDEX), do not silently map it to payload validation. First clarify which layer the user wants: application-layer validation in payload (this catalog applies, response 400 with structured error) versus database-level DDL constraints (out of scope here, requires direct SQL or migration tool). The two layers can co-exist for the same field but behave differently. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| codegen_get_query_declarative_catalogA | Get authoritative JSON catalog of query declarative spec (5 query properties, 7 endpoint resolution rules, file reference convention with database-specific placeholders) used in payload query declarations such as datatablesQuery, viewQuery, viewName, exportQuery, and masterDetail.detailConfig.detailQuery. USE WHEN: The user asks about query declaration in payload, query properties, or how endpoints resolve queries The user mentions specific property names: datatablesQuery, viewQuery, viewName, exportQuery, detailQuery, atau masterDetail Pertanyaan dalam bentuk seperti "bagaimana cara declare query di payload", "what's the difference between viewQuery and viewName", "kapan pakai viewName vs tableName" The user asks about endpoint query resolution: "query apa yang dipakai untuk /datatables", "what query does /export use", "resolusi query untuk /read-composite" The user asks about file: prefix convention or SQL file references in payload The user asks about database placeholder differences (PostgreSQL $1, MySQL ?, Oracle :1) in detailQuery or other file-referenced SQL Before generating or editing query-related properties in payload JSON — to ground property naming, resolution priority, and file reference convention. Often called before 'codegen_generate_payload' for grounding the initial generation, or before manual editing of an existing payload. Sibling of 'codegen_get_field_validation_catalog' (catalog-style tool, different scope). The user asks about master-detail composite read query setup (detailQuery placement, foreign key placeholder)
DO NOT USE FOR: Validating actual payload files against the database schema -> use 'codegen_validate_payload' Generating a payload from scratch -> use 'codegen_generate_payload' Applying changes to payload files -> use 'codegen_sync_payload' Validating fieldValidation array -> use 'codegen_get_field_validation_catalog' Reading the active database connection config schema -> use 'setup_get_config_schema' Auto SQL conversion details (PostgreSQL -> MySQL/Oracle) — not in catalog scope; refer to the documentationUrl returned in the response Subquery wrapping behavior for JOIN/CTE queries — not in catalog scope; refer to documentationUrl Master-detail full structure outside detailQuery (e.g. enabled, detailTable, foreignKey, detailConfig.tableName) — not in catalog scope; refer to documentationUrl Use case examples and decision guides ("kapan pakai X vs Y") — refer to documentationUrl for narrative explanation
This tool runs: npx restforge-cli query-declarative:catalog in the given cwd.
The catalog is sourced from restforge-cli (single source of truth) so it stays in sync with
the restforge runtime version installed in the project. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "look up the query catalog", "edit the query declaration", "install the package"). Speak in plain language. Summarise the catalog (number of query properties, endpoints, database placeholders); do not paste the entire JSON unless the user explicitly asks for it. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| codegen_get_dashboard_catalogA | Get authoritative JSON catalog of dashboard payload spec (payload shape with discriminator, widget structure with mutex query/queries, params contract with allowed types, scalar collapse rules, naming convention with dash- prefix, URL pattern POST /api/{project}/{name}/dashboard, file reference convention, placeholder convention with :paramName). USE WHEN: The user asks about dashboard payload structure, widget definition, or how dashboard endpoints work The user mentions specific dashboard concepts: widgets, params, query vs queries, scalar collapse, dashboard prefix dash- Pertanyaan dalam bentuk seperti "bagaimana struktur payload dashboard", "apa beda dashboard dengan endpoint biasa", "kapan pakai query vs queries", "kenapa nama dashboard harus pakai dash-" The user asks about the URL pattern for dashboard endpoints (POST /api/{project}/{name}/dashboard) The user asks why dashboard names must start with dash- prefix The user asks about response shape: when is value a scalar, when is it object, when is it array (scalar collapse rules) The user asks about placeholder :paramName in widget SQL — declaration requirements, escaping (:: Postgres cast) Before authoring a dashboard payload manually (via Write tool) — to ground field naming, allowed/forbidden fields, widget structure Before invoking 'codegen_validate_dashboard_payload' or 'codegen_create_dashboard' — to verify payload conforms to schema The user is unsure whether their use case is a dashboard or a CRUD endpoint
DO NOT USE FOR: Validating an actual dashboard payload file -> use 'codegen_validate_dashboard_payload' Generating a dashboard module from a payload -> use 'codegen_create_dashboard' Looking up CRUD payload field validation rules -> use 'codegen_get_field_validation_catalog' Looking up CRUD query declarative spec (datatablesQuery, viewQuery, viewName, exportQuery, detailQuery) -> use 'codegen_get_query_declarative_catalog' Generating a CRUD payload from a database table -> use 'codegen_generate_payload' Validating CRUD payload drift against the database -> use 'codegen_validate_payload' Common widget patterns examples (Metric+Donut, Metric+Sparkline, Metric+Goal) — not in catalog scope; refer to the documentationUrl returned in the response Frontend integration examples (Metronic, AdminLTE, etc.) — not in catalog scope; refer to documentationUrl Separation of Concerns rationale for forbidden frontend fields — not in catalog scope; refer to documentationUrl Multi-database SQL dialect adaptation inside widget queries — not in catalog scope; refer to documentationUrl Performance characteristics (Promise.allSettled execution, in-memory SQL embedding) — not in catalog scope; refer to documentationUrl
This tool runs: npx restforge-cli dashboard:catalog in the given cwd.
The catalog is sourced from restforge-cli (single source of truth) so it stays in sync with
the restforge runtime version installed in the project. PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "look up the dashboard catalog", "edit the dashboard payload", "install the package"). Speak in plain language. Summarise the catalog (number of allowed top-level fields, forbidden frontend fields, param types, scalar collapse rules); do not paste the entire JSON unless the user explicitly asks for it. When the user is unsure whether their use case is dashboard or CRUD, briefly explain the discriminator: widgets array means dashboard (multi-query aggregator), tableName means CRUD (single-table REST endpoint). They cannot mix. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| codegen_create_endpointA | Generate a project + endpoint module (submodule, model, metadata, demo files, optional audit migration) from an existing payload spec by wrapping restforge-cli create. URL pattern produced: /api/{project}/{endpoint}/{action}. This tool is DESTRUCTIVE: it spawns the CLI which writes / overwrites files in 'src/modules//', 'src/models//', 'metadata//', 'examples///', and updates '.restforge/projects.json'. Single-call semantics: the tool always executes; there is no preview mode. Internally the tool always passes '--force=true' to the CLI to bypass the CLI's interactive y/N readline prompt (which would deadlock in a no-TTY subprocess). Safety net: when the CLI overwrites an existing module, model, or query directory, it FIRST renames the previous version to '.archive.NNN' (NNN is a sequential generation number starting at 001) inside the same folder. Rollback by restoring the most recent archive is always possible. AI responsibility — IMPORTANT: because this tool always executes and may overwrite generated files, you MUST confirm intent with the user in plain language BEFORE invoking the tool. You do NOT need to detect file conflicts programmatically — the CLI handles that and the archive mechanism keeps the previous version safe. Just confirm intent. Examples of good confirmation phrasing in user-facing chat: "Saya akan generate endpoint di project ({database}). Kalau modul/model lama sudah ada, versi sebelumnya akan disimpan sebagai '.archive.NNN'. Lanjut?" "I will generate under project using . Existing files will be archived as .archive.NNN before being overwritten. Proceed?"
USE WHEN: The user asks to generate, create, or scaffold an endpoint, resource, or module from a payload (e.g. "buatkan endpoint untuk product", "generate resource users", "create endpoint dari payload X", "scaffold a new endpoint") The user mentions "endpoint", "resource", "module" or the URL pattern /api/{project}/{resource}/{action} and wants to register it as runnable code The user has authored a payload file (e.g. via 'codegen_generate_payload' or manually) and now wants to materialise it as runnable code in the project Pertanyaan dalam bentuk: "tambahkan endpoint X ke project Y", "buat module baru di project Z", "scaffold endpoint baru pakai payload ini", "generate kode dari payload ini" The user asks to add a new endpoint to an existing project (registry already has the project, just adding more endpoints) The user asks to bootstrap a brand-new project together with its first endpoint The user asks about regenerating an existing endpoint after the payload changed (this triggers overwrite + archive flow inside the CLI; previous versions become '.archive.NNN' in place) After 'codegen_validate_payload' confirmed the payload is valid — this is the natural follow-up that turns a verified payload into runnable code
DO NOT USE FOR: Generating the payload JSON itself from a database table -> use 'codegen_generate_payload' Validating a payload before generation -> use 'codegen_validate_payload' Inspecting per-column differences between payload and database -> use 'codegen_diff_payload' Syncing payload changes back into existing payload files after schema drift -> use 'codegen_sync_payload' Looking up the field validation catalog before authoring the payload -> use 'codegen_get_field_validation_catalog' Looking up the query declarative catalog before authoring the payload -> use 'codegen_get_query_declarative_catalog' Deleting a project or endpoint — out of scope; the user must run 'npx restforge-cli drop' manually Generating a processor (Kafka consumer, etc.) — out of scope; the CLI has separate 'processor' and 'consumer-create' subcommands not covered by this MCP server yet Generating a dashboard endpoint — out of scope; the CLI has a separate 'dashboard' subcommand Listing all registered projects in the registry — out of scope here; use the CLI's 'list' subcommand directly Database DDL changes (CREATE TABLE, ALTER TABLE) — not in this tool's scope. The audit migration sub-step DOES create a single audit table when the payload uses the 'audit' fieldPolicy strategy, but that is the only DDL it touches.
Preconditions: The project must have restforgejs installed in node_modules. The payload file must exist at /payload/.json before calling this tool. The CLI itself rejects reserved project names (src, lib, node_modules, config, utils, models, controllers, middleware, routes) and reserved endpoint names (health, status, admin, api, auth, login, logout, register, index, main, app, config, test, docs, swagger, graphql, websocket, socket). When in doubt, ask the user to pick a different name before invoking this tool.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "the endpoint generator", "the project generator", "generate the payload first", "validate the payload first"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. This tool is destructive: it can overwrite existing module / model / query files. BEFORE invoking this tool, ALWAYS confirm with the user in plain language. Example: "Saya akan generate endpoint di project . Kalau file lama sudah ada, akan ditimpa (versi lama disimpan sebagai .archive.NNN). Lanjut?". Do not detect conflicts programmatically; the CLI handles that and creates the archive. After the tool runs, summarise the result. Read the CLI output and identify any archive activity (the CLI uses the '.archive.NNN' naming convention in the filesystem and reports archive activity in its output, but the exact wording may evolve). When archives are created, tell the user that previous versions are preserved in case rollback is needed. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_create_dashboardA | Generate a multi-widget dashboard endpoint module from a payload spec by wrapping restforge-cli dashboard. URL pattern produced: POST /api/{project}/{name}/dashboard. Dashboards differ structurally from CRUD endpoints: there is no table, no fieldValidation, no CRUD actions. The payload declares a 'widgets' array — each widget owns SQL aggregation queries that are embedded into the generated module file and executed in parallel at request time, returning a JSON envelope keyed by widget id. This tool is DESTRUCTIVE: it spawns the CLI which writes / overwrites files in 'src/modules/.js' and 'src/modules//.js', plus 'metadata//.json' and updates '.restforge/projects.json'. Single-call semantics: the tool always executes; there is no preview mode. Internally the tool always passes '--force=true' to the CLI to bypass the CLI's interactive y/N readline prompt (which would deadlock in a no-TTY subprocess). Safety net: when the CLI overwrites an existing dashboard module, it FIRST renames the previous version to '.archive.NNN' (NNN is a sequential generation number starting at 001) inside the same folder. Rollback by restoring the most recent archive is always possible. AI responsibility — IMPORTANT: because this tool always executes and may overwrite generated files, you MUST confirm intent with the user in plain language BEFORE invoking the tool. You do NOT need to detect file conflicts programmatically — the CLI handles that and the archive mechanism keeps the previous version safe. Just confirm intent. Examples of good confirmation phrasing in user-facing chat: "Saya akan generate dashboard di project . Kalau modul lama sudah ada, versi sebelumnya akan disimpan sebagai '.archive.NNN'. Lanjut?" "I will generate under project . Existing files will be archived as .archive.NNN before being overwritten. Proceed?"
USE WHEN: The user asks to generate, create, or scaffold a dashboard endpoint, multi-widget aggregator, or analytics endpoint (e.g. "buatkan dashboard X di project Y", "generate dashboard sales", "scaffold dashboard inbound dengan payload Z") The user mentions "dashboard", "widget aggregator", "multi-widget", "POST .../dashboard", or terms like "donut breakdown", "metric card", "sparkline" in the context of generating an endpoint The user has authored a payload file with a 'widgets' array (not a CRUD 'tableName' shape) and wants to materialise it as a runnable endpoint Pertanyaan dalam bentuk: "buatkan dashboard X di project Y", "generate dashboard sales", "scaffold dashboard inbound dengan payload Z" The user mentions the URL pattern POST /api///dashboard and wants to register it as runnable code The user explicitly references dashboard concepts: scalar collapse rules, widget id, query versus queries, params contract, file:query/*.sql references inside widgets After 'codegen_validate_payload' confirmed a dashboard-shape payload — this is the natural follow-up that turns it into runnable code The user asks to regenerate an existing dashboard after the payload changed (overwrite + archive flow handled by the CLI)
DO NOT USE FOR: Generating a CRUD endpoint (payload has 'tableName', 'fieldName', 'action') -> use 'codegen_create_endpoint' Generating the payload JSON itself from a database table -> use 'codegen_generate_payload' (note: codegen_generate_payload targets CRUD payloads — dashboard payloads are typically authored manually) Validating a payload before generation -> use 'codegen_validate_payload' Inspecting per-column differences between payload and database -> use 'codegen_diff_payload' Syncing payload changes back into existing payload files after schema drift -> use 'codegen_sync_payload' Looking up the field validation catalog (dashboards do not have field validation) -> use 'codegen_get_field_validation_catalog' only if discussing CRUD payload fields Looking up the query declarative catalog (dashboards have their own query structure with widgets[].query and widgets[].queries) -> use 'codegen_get_query_declarative_catalog' only if discussing CRUD payload queries Generating a processor (Kafka consumer, etc.) — out of scope; the CLI has separate 'processor' subcommand not covered by this MCP server yet Deleting a dashboard or project — out of scope; the user must run 'npx restforge-cli drop' manually Changing widget visual presentation (widgetType, layout, color, title, subtitle) — those are frontend concerns and forbidden in the dashboard payload (separation of concerns); they belong in the frontend code, not in this generator
Cross-reference: this tool is sibling of 'codegen_create_endpoint'. Both generate runnable code from payload JSON, but they consume different payload shapes (CRUD vs dashboard) and produce different artefacts (full module + model vs single dashboard module with embedded SQL). Preconditions: The project must have restforgejs installed in node_modules. The payload file must exist at /payload/.json before calling this tool. The payload must follow the dashboard schema: a 'widgets' array (NOT a CRUD payload with 'tableName'). The CLI's DashboardValidator rejects payloads that mix shapes, declare forbidden frontend fields (widgetType, layout, title, subtitle, color), have widgets without 'id', have duplicate widget ids, declare both 'query' AND 'queries' in the same widget, declare neither, or use placeholders not declared in 'params'. The dashboard name MUST start with 'dash-' prefix (e.g. dash-sales, dash-inbound). The prefix is required by the CLI and becomes part of the URL segment.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "the dashboard generator", "validate the payload first", "draft the payload first"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. This tool is destructive: it can overwrite an existing dashboard module file. BEFORE invoking this tool, ALWAYS confirm with the user in plain language. Example: "Saya akan generate dashboard di project . Kalau modul lama sudah ada, akan ditimpa (versi sebelumnya disimpan sebagai .archive.NNN). Lanjut?". Do not detect conflicts programmatically; the CLI handles that and creates the archive. After the tool runs, summarise the result. Surface the resulting endpoint URL (POST /api///dashboard) so the user knows where to call it. Read the CLI output and identify any archive activity using the '.archive.NNN' filesystem convention; surface to the user when archives exist. If the user is confused about the difference between a dashboard and a CRUD endpoint: dashboards aggregate data from multiple SQL queries (widgets) and return a JSON envelope with widget keys; CRUD endpoints expose actions like /datatables, /read, /create, /update, /delete on a single table. Suggest the right tool based on what the user is actually building. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_validate_dashboard_payloadA | Validate the structural correctness of a dashboard payload spec WITHOUT generating any file, by wrapping restforge-cli dashboard --validate-only=true. Dashboards have a different shape than CRUD endpoints (widgets array, no tableName, no fieldValidation). The CLI's DashboardValidator checks: widgets array shape, allowed/forbidden fields per level, the 'query' vs 'queries' mutual exclusion, params contract (each ':placeholder' used in SQL must be declared in 'params'), 'file:query/.sql' reference resolution, and that no frontend-only fields (widgetType, layout, title, subtitle, color) leak into the payload. This tool is READ-ONLY: it does NOT write any file, does NOT touch the database, does NOT update the project registry. It only reports whether the payload structure is valid. Re-running with the same input gives the same result (idempotent). Workflow positioning: this is the natural pre-flight before 'codegen_create_dashboard'. When the AI authors a dashboard payload (manually via Write), call this tool first to surface validation errors cheaply — before invoking the generator that performs filesystem writes. Gap closed: the general 'codegen_validate_payload' tool silently skips dashboard payloads (it filters on 'tableName' and 'fieldName'). This tool fills that gap for the dashboard shape. USE WHEN: The user asks to validate, check, or verify the structure of a dashboard payload before generating The user has authored a dashboard payload (with 'widgets' array) and wants to confirm it parses correctly before invoking the generator Pertanyaan dalam bentuk: "cek dashboard payload saya valid?", "validate dashboard config", "is this dashboard schema correct?", "apakah payload dashboard ini OK?" Before invoking 'codegen_create_dashboard' — pre-flight to surface validation errors early (cheaper than failing inside the generator stage, which performs filesystem writes) The user reports that 'codegen_create_dashboard' failed with a validation-related error and wants to fix the payload iteratively The user mentions specific dashboard validation rules: forbidden frontend fields (widgetType, layout, title, subtitle, color), 'query' vs 'queries' mutex, params placeholder declaration After the user manually edited a dashboard payload and wants a quick sanity check before re-running the generator The user is unsure whether their payload follows dashboard shape (widgets) or CRUD shape (tableName) and wants verification
DO NOT USE FOR: Validating a CRUD payload (with 'tableName' and 'fieldName') against database schema -> use 'codegen_validate_payload' Generating the dashboard module after validation -> use 'codegen_create_dashboard' Inspecting drift between CRUD payload and database -> use 'codegen_validate_payload' (this dashboard validator does NOT touch the database) Generating a payload from scratch -> use 'codegen_generate_payload' for CRUD; for dashboard, the user authors manually Looking up the field validation catalog -> use 'codegen_get_field_validation_catalog' (different scope; dashboard payloads have no fieldValidation) Validating SQL syntax inside a widget query — the validator only checks placeholder declarations and structural shape, not SQL semantics. SQL errors will only surface when the dashboard endpoint is actually called at runtime.
Cross-reference: this tool is the read-only sibling of 'codegen_create_dashboard'. Both have nearly identical input schemas, but this tool only validates and does NOT generate any file. Preconditions: The project must have restforgejs installed in node_modules. The payload file must exist at /payload/.json before calling this tool. The dashboard name MUST start with 'dash-' prefix (CLI requirement). For validate-only mode, this is checked at the argument-parser level even though the value is not used to write any file.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "validate the dashboard payload", "generate the dashboard module"). Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks. This tool is read-only: it validates payload structure without writing files or touching the database. Safe to invoke proactively before 'codegen_create_dashboard' to give the user faster feedback on payload errors. If validation passes, briefly confirm the result and offer to proceed with generation. If validation fails, surface the specific error in plain language and offer to help fix it. Do not paste raw CLI output unless the user explicitly asks. When a precondition is not met, frame it as a question or next-step suggestion rather than an error.
|
| codegen_list_tablesA | List all tables (and views) in the project's configured database, by wrapping restforge-cli dbschema:list. Live introspection — the CLI connects to the database and queries the catalog (information_schema in Postgres/MySQL, all_tables in Oracle). USE WHEN: The user asks "what tables exist in the database?" or any equivalent question Pertanyaan dalam bentuk seperti "tabel apa saja yang ada di database", "list table di database project", "show me the tables", "ada tabel apa aja" Before authoring any SQL query (dashboard widget query, ad-hoc query, CRUD payload generation) and the table catalog is unknown — ground the query in the live database state instead of guessing The user mentions a specific table name and the AI is unsure whether it actually exists in the project's database The user is exploring an unfamiliar database before deciding what to build (e.g. picking a target table for a new endpoint or dashboard) The user asks to filter by schema or namespace (e.g. "list tables in core schema only", "tabel di schema public saja") The user asks for a read-only inspection without modifying anything Before invoking 'codegen_describe_table' — to discover candidate table names first
DO NOT USE FOR: Detailed column / primary key / foreign key / index information for a specific table -> use 'codegen_describe_table' Listing payload spec files on the filesystem (the payload/ folder) -> use generic Read or filesystem tools Validating whether a payload file is in sync with the database -> use 'codegen_validate_payload' Querying the actual row data inside tables -> out of scope; this tool returns only the table catalog (names + type), not row content Modifying the database schema (CREATE/ALTER/DROP TABLE) -> out of scope Listing schemas or databases themselves -> out of scope; this tool returns the tables WITHIN a schema, not the schemas themselves
This tool runs: npx restforge-cli dbschema:list --config= [--schema=] [--include-system=] in the given cwd.
The CLI connects to the database described in the config file, queries the catalog, and emits a JSON envelope with summary counts and a tables array. Preconditions: The project must have restforgejs installed in node_modules. The config file (default 'db-connection.env') must exist in the project and contain valid database credentials. This tool does not pre-check that — if the CLI fails, the failure response will surface the underlying cause.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "list the database tables", "describe a specific table", "install the package"). Speak in plain language. Summarise the result (database type and total table count); do not paste the raw JSON unless the user explicitly asks. This is a live introspection: the tool actively queries the database catalog (information_schema in Postgres/MySQL, all_tables in Oracle). The result reflects the database state at query time. Database type is auto-detected from the config file. The schema filter is dialect-aware (Postgres schema vs MySQL database vs Oracle owner) and uppercase is required for Oracle owners. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| codegen_describe_tableA | Describe a single database table — columns (with dialect-specific types), primary key, foreign keys, and indexes — by wrapping restforge-cli dbschema:describe. Live introspection — the CLI connects to the database and queries the catalog. USE WHEN: The user asks about the columns, primary key, foreign keys, or indexes of a specific table Pertanyaan dalam bentuk seperti "kolom apa saja di tabel X", "describe tabel sales_order", "show schema for users table", "tabel X punya FK ke mana", "ada index apa di tabel Y" Before authoring a SQL JOIN — to discover the foreign key path between two tables and write the JOIN clause correctly Before authoring a dashboard widget query — to confirm column names and types before composing the SELECT The user wants to verify whether a specific column exists in a table The user asks "what type is column X in table Y" — column type is dialect-specific so live introspection is more reliable than guessing Before invoking 'codegen_create_dashboard' (with widget SQL) — to ground SQL identifiers in the live schema After 'codegen_list_tables' returned a candidate name and the user wants the per-column details
DO NOT USE FOR: Listing all tables in the database -> use 'codegen_list_tables' Querying the actual row data inside a table -> out of scope; this tool returns metadata (columns, PK, FK, indexes) only, not row content Validating a payload spec file against the database schema (file-level diff) -> use 'codegen_validate_payload' or 'codegen_diff_payload' Modifying the schema (ALTER TABLE) -> out of scope Inspecting the SQL definition behind a database view -> out of scope; only column-level info is returned for views Cross-database introspection (multiple databases at once) -> out of scope; a single config = a single connection
Cross-reference: this tool is the sibling of 'codegen_list_tables'. Use list-tables first to discover candidate names, then describe-table for the per-column details. This tool runs: npx restforge-cli dbschema:describe --config= --table= [--include-foreign-keys=] [--include-indexes=] in the given cwd.
The CLI connects to the database described in the config file, queries the catalog, and emits a JSON envelope with the table metadata. Preconditions: The project must have restforgejs installed in node_modules. The config file (default 'db-connection.env') must exist in the project and contain valid database credentials. This tool does not pre-check that — if the CLI fails, the failure response will surface the underlying cause. The named table must exist in the database; otherwise the CLI fails with a "Table 'X' not found" error.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "describe the table", "list the database tables", "install the package"). Speak in plain language. Summarise the result; do not paste the raw JSON unless the user explicitly asks. This is a live introspection: the tool actively queries the database catalog. The result reflects the schema state at query time. Column types are dialect-specific (Postgres: 'character varying(N)', MySQL: 'varchar(N)', Oracle: 'VARCHAR2(N)'). Use the type as-is when the user asks about column constraints; do not normalise. Foreign key 'references' field is the JOIN target — when the user asks "how do I join A and B", look at FK paths in both directions to compose the JOIN clause. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| codegen_validate_sqlA | Validate a SELECT (or WITH/CTE) SQL statement against the live database — checks syntax, column references, function existence, type compatibility, and JOIN resolution — by wrapping restforge-cli query:validate. Live introspection — the CLI runs EXPLAIN against the configured database without executing any rows. USE WHEN: The user asks "is this SQL valid?", "check my SQL", "validate this query", "cek SQL ini bener atau salah" Before invoking 'codegen_create_dashboard' with widget queries — to verify each widget SQL passes against the live database before committing the payload file After authoring a complex SQL (multi-table JOIN, CTE, window function) — to catch column reference errors, ambiguous columns, dialect-specific function mismatches before runtime The user reports a dashboard widget failed at runtime with a database error — to confirm whether the SQL is the cause and identify the specific error code/message Iterating on SQL: validate, fix, re-validate (the tool is idempotent and read-only) After 'codegen_describe_table' suggested column names but the user wants a final correctness check on a draft SQL
DO NOT USE FOR: Validating the JSON shape of a payload file -> use 'codegen_validate_payload' or 'codegen_validate_dashboard_payload' Checking whether the SQL result shape matches a widget query key's expected shape (scalar/object/array) -> out of scope; that is checked by the dashboard payload validator separately Running INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE — these statements are rejected before any database connection is opened (this tool is read-only) Listing tables in the database -> use 'codegen_list_tables' Describing a table's columns/PK/FK -> use 'codegen_describe_table' Performance/query plan analysis -> out of scope; the tool only reports validation pass/fail, not the query plan
Cross-reference: this tool complements 'codegen_list_tables' and 'codegen_describe_table'. Use list/describe to ground SQL on the live schema, then validate-sql to confirm the composed SQL is correct before commit. This tool runs: npx restforge-cli query:validate --config= --sql= --pretty=false in the given cwd.
The CLI runs EXPLAIN (PostgreSQL/MySQL) or EXPLAIN PLAN FOR (Oracle) against the configured database, without executing any rows. Preconditions: The project must have restforgejs installed in node_modules (>= 2.4.8 for query:validate support). The config file (default 'db-connection.env') must exist in the project (or in cwd/config/) and contain valid database credentials. The CLI auto-fallbacks to the config/ subfolder if the file is not found at the top level.
PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "validate the SQL", "list the database tables"). Speak in plain language. For success: confirm the SQL is valid in one sentence. For failure: summarise the error category in plain language (e.g. "the column 'x' doesn't exist in this table"), and suggest the next action (revise SQL based on error, re-validate). This is a live introspection: the tool actively runs EXPLAIN against the database. The result reflects the database state at query time. Zero rows are executed; the planner only parses and resolves references. For SELECT-only rejection (when the SQL starts with INSERT/UPDATE/DELETE/etc), explain that the validator is read-only by design and ask the user to revise to a SELECT statement. Error codes are dialect-specific: Postgres uses 5-char SQLSTATE (e.g. '42703'), MySQL uses ER_* names or numeric errno, Oracle uses 'ORA-XXXXX'. When relevant, mention the category in plain language (column not found, ambiguous reference, function mismatch, etc) instead of citing the raw code. When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.
|
| runtime_detect_projectA | Detect RESTForge project names by scanning the conventional 'src/modules/' folder. Each .js file in that folder represents one RESTForge project; the filename without extension is the project name. USE WHEN: The user asks "which projects are available?", "what RESTForge projects are in this folder?", "list project saya" Before generating a launcher script — to confirm the project name to pass as --project= Before invoking 'runtime_generate_launcher' — to determine whether the user must specify a project name or one can be auto-detected The user requests to run the server but the project name is unknown or ambiguous
DO NOT USE FOR: Listing config files -> use 'runtime_detect_config' Listing payload spec files -> use generic Read or filesystem tools Listing database tables -> use 'codegen_list_tables' Validating runtime preflight -> use 'runtime_validate_preflight'
Preconditions: PRESENTATION GUIDANCE: Match the user's language. If the user writes in Indonesian, respond in Indonesian. Never mention internal tool names in the reply to the user. When exactly one project is found, proceed without asking. When multiple are found, ask the user to pick one before generating the launcher. The project name comes from the filename in src/modules/ (without the .js extension); explain this in plain language if asked. When a precondition is not met (folder missing), frame it as a question or next-step suggestion rather than an error.
|
| runtime_detect_configA | Detect RESTForge configuration files by scanning the 'config/' folder for .env files. Each .env file is a candidate config to pass via --config= when invoking the RESTForge runtime. USE WHEN: The user asks "which config files are available?", "config apa saja yang ada", "list .env" Before generating a launcher script — to confirm which config file to pass Before invoking 'runtime_generate_launcher' — to know if a config exists at all The user mentions running the server but the config file is unknown or ambiguous
DO NOT USE FOR: Listing project names -> use 'runtime_detect_project' Reading content of a specific .env file -> use 'setup_read_env' Validating connection credentials in a config -> use 'setup_validate_config' or 'runtime_validate_preflight'
Preconditions: PRESENTATION GUIDANCE: Match the user's language. Never mention internal tool names. When exactly one config file is found, proceed without asking. When multiple are found, ask the user which environment they want. The filename is what gets passed as --config=; the runtime will resolve it relative to the config/ folder automatically. When a precondition is not met (folder missing or empty), frame it as a question or next-step suggestion rather than an error.
|
| runtime_validate_preflightA | Run a runtime preflight check before generating a launcher. Wraps 'npx restforge validate --config=' (license + database + redis/kafka) and additionally inspects: (1) .restforge/server.pid to detect a possibly-running server, (2) optional local port availability via Node net binding. USE WHEN: Before invoking 'runtime_generate_launcher' — to verify the project is ready to launch The user asks "is this ready to run?", "preflight check", "cek apakah server bisa dijalankan" After changing config or installing a new license — to verify everything still works The user reports the server fails to start — to identify the failing component
DO NOT USE FOR: Validating ONLY the config (license/database) without runtime context -> use 'setup_validate_config' Listing or reading config values -> use 'setup_read_env' Generating launcher files -> use 'runtime_generate_launcher'
This tool runs: npx restforge validate --config= in the given cwd, plus filesystem checks (PID file, optional port). Preconditions: PRESENTATION GUIDANCE: Match the user's language. Never mention internal tool names. Summarise by component: license, database, optional redis/kafka, PID file presence, port availability. Do not echo license keys, passwords, or full connection URIs from the CLI output. Preflight failure is informational, not a blocker. The user can still proceed to generate the launcher (with a warning recorded). Port check is best-effort: a "free" result on this machine does not guarantee the port is free for the eventual server bind address (which may differ).
|
| runtime_check_launcher_existsA | Check whether the launcher files that would be produced by 'runtime_generate_launcher' already exist in the project root. Read-only — does not create or overwrite anything. USE WHEN: Before invoking 'runtime_generate_launcher' — to detect potential overwrites and ask the user for confirmation The user wants to know which files would be created without committing The user is debugging an existing setup and wants to confirm what files exist
DO NOT USE FOR: Generating launcher files -> use 'runtime_generate_launcher' Reading the content of an existing launcher -> use generic Read tools Checking if the server is currently running -> use 'runtime_check_status'
The list of files depends on os + mode (file names are FIXED, not user-customisable): windows + host: server-start.bat, server-stop.bat windows + pm2: server-start.bat, server-stop.bat, ecosystem.config.js linux + host: server-start.sh, server-stop.sh linux + pm2: server-start.sh, server-stop.sh, ecosystem.config.js
PRESENTATION GUIDANCE: Match the user's language. Never mention internal tool names. When at least one file already exists, ask the user whether to overwrite (then call generate with overwrite=true). Do not echo the JSON unless explicitly asked.
|
| runtime_generate_launcherA | Generate a launcher script for the RESTForge Server in the project root. This tool does NOT run the server — it produces a .bat or .sh script that the user must execute themselves. This is intentional: a server launched by the AI session would terminate when the session ends; a script executed by the user lives in the user's terminal/session and persists independently. Files produced (depending on os + mode) — file names are FIXED, not user-customisable: windows + host: server-start.bat, server-stop.bat windows + pm2: server-start.bat (calls 'pm2 start ecosystem.config.js'), server-stop.bat, ecosystem.config.js linux + host: server-start.sh, server-stop.sh linux + pm2: server-start.sh (calls 'pm2 start ecosystem.config.js'), server-stop.sh, ecosystem.config.js
For host mode the start script runs 'npx restforge ...' in the foreground (or 'exec' on Linux). The stop script kills the process by port via netstat/taskkill on Windows or lsof/fuser+kill on Linux — no PID file is required. For PM2 mode the ecosystem points 'script' directly at './node_modules/restforgejs/server.js' to bypass the npx shim and avoid PM2's default node interpreter mis-parsing a .cmd file. USE WHEN: The user asks "run the server", "jalankan server", "start RESTForge" After confirming OS, mode, project, config, and port with the user (typically via 'runtime_detect_project', 'runtime_detect_config', and direct questions) After 'runtime_check_launcher_exists' returned no conflicts, OR the user confirmed overwrite
DO NOT USE FOR: Actually starting or stopping the server -> the user runs the generated script themselves Modifying database schema or payload files -> out of scope Running one-off commands -> out of scope; this tool is launcher-scaffolding only
Preconditions: PRESENTATION GUIDANCE: Match the user's language. Never mention internal tool names. Refer to the produced files by their visible names (e.g. 'server-start.bat'). Tell the user clearly that the AI does NOT execute the script — they must run it themselves so the server keeps running after the AI session ends. For PM2 mode: warn the user that PM2 must be installed globally first (npm install -g pm2). Do not auto-install. After generation, summarise: location, files produced, how to start, how to stop. Do not paste the JSON envelope unless explicitly asked. If the user asks for a different mode (Windows Service, Docker, systemd) — those are out of scope V1; suggest using host or pm2 instead.
|
| runtime_check_statusA | Check whether the RESTForge Server is currently running. Inspects (in order): (1) .restforge/server.pid file (legacy launchers), (2) port-based detection — tries to bind to the configured port; if the bind fails the port is in use and a host-mode server is presumed running, (3) PM2 process list via 'pm2 jlist', (4) optional HTTP health endpoint probe. USE WHEN: The user asks "is the server running?", "apakah server jalan?", "cek status server", "server saya kenapa tidak respond" After running the launcher (server-start.bat or equivalent) — to confirm the server actually came up Before invoking other tools that talk to the running server — to verify it's reachable The user reports the server appears to be down — to diagnose stale PID file vs PM2 app issue vs not started
DO NOT USE FOR: Generating launcher files -> use 'runtime_generate_launcher' Validating preflight before starting -> use 'runtime_validate_preflight' Starting or stopping the server -> the user runs server-start.bat / server-stop.bat themselves Calling specific business endpoints to test functionality -> out of scope; this only checks server liveness
Detection modes: 'auto' (default): try host mode first (PID file then port-based), fall back to pm2 mode 'host': only inspect .restforge/server.pid and the port (skip PM2 entirely) 'pm2': only inspect 'pm2 jlist' output (skip PID file and port). Requires 'project' parameter to locate the right app.
Note on host-mode detection: Current launcher scripts (generated by 'runtime_generate_launcher') do NOT write .restforge/server.pid. Detection therefore relies primarily on the port-based bind probe — pass 'port' to enable it. The PID-file path is still inspected for backward compatibility with launchers generated by older versions. The port probe binds locally on host_address (default 127.0.0.1). If the server binds to a different interface, pass host_address accordingly. A port shown 'in use' confirms a process is listening, but does not guarantee it is the RESTForge server.
Optional HTTP health probe: if 'health_path' is set, the tool performs an HTTP GET against http://<host_address>:<health_path> and reports status code + response time. Without health_path, only process liveness is checked. Preconditions: The cwd folder must exist. For host mode port-based detection: 'port' must be provided. For pm2 mode: PM2 must be installed and running on the user machine. For HTTP probe: 'port' must be provided alongside 'health_path'.
PRESENTATION GUIDANCE: Match the user's language. Never mention internal tool names. Summarise the state in one sentence: running, dead_pid (stale), http_unreachable (process up but endpoint dead), or not_running. For 'dead_pid': suggest the user run the stop launcher (or 'pm2 delete' for PM2 mode) to clean up before starting again. For 'http_unreachable': process is alive but the HTTP probe failed — usually a config mismatch (wrong port or path) or server still booting. Suggest re-trying after a moment or checking server logs. For 'not_running': the server isn't currently running. Suggest generating a launcher (if not already done) and asking the user to execute it. Do not echo the JSON envelope unless explicitly asked. The HTTP probe targets the local machine by default (127.0.0.1). If the server binds to a different address (SERVER_ADDRESS in .env), the user can pass host_address to override.
|
