@restforgejs/mcp-server 1.2.0

package/dist/tools/codegen/list-tables.js

@@ -0,0 +1,220 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenListTables(server) {
+    server.registerTool('codegen_list_tables', {
+        title: 'List Database Tables',
+        description: `List all tables (and views) in the project's configured database, by wrapping restforge schema 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 schema list --config=<config> [--schema=<schema>] [--include-system=<bool>] 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/platform 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.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder (must contain node_modules/@restforgejs/platform and the config file)'),
+            config: z
+                .string()
+                .min(1)
+                .default('db-connection.env')
+                .describe('Config file name relative to the project, used by the CLI to connect to the database'),
+            schema: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Filter to a specific database schema/owner. Postgres: schema name (e.g. public); MySQL: database name; Oracle: owner (uppercase). When omitted, lists tables from all user-owned schemas.'),
+            includeSystem: z
+                .boolean()
+                .optional()
+                .describe("Default false. When true, include system tables (Postgres: pg_catalog, information_schema; MySQL: mysql, performance_schema, sys; Oracle: SYS, SYSTEM, etc). Most users do NOT want this."),
+        },
+        annotations: {
+            title: 'List Database Tables',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, config, schema, includeSystem }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be present in node_modules.
+        // Treated as a non-error precondition per the authoring guide §3.4.
+        try {
+            await access(join(projectCwd, 'node_modules', '@restforgejs', 'platform'));
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge package is not installed in this project.
+
+Project path: ${projectCwd}
+Expected location: node_modules/@restforgejs/platform
+Requested config: ${config}
+Requested schema filter: ${schema ?? 'all user-owned schemas'}
+Requested includeSystem: ${includeSystem ?? false}
+
+For the assistant:
+- The user needs to install the RESTForge package before the database table list can be retrieved.
+- Suggest installing the package first, then retry listing the tables.
+- When explaining to the user, say something like "the RESTForge package isn't installed yet — should I install it first?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Forward only the arguments the user supplied. CLI defaults remain in
+        // effect when the user does not specify them. per §3.5
+        const cliArgs = [
+            'restforge',
+            'schema',
+            'list',
+            `--config=${config}`,
+        ];
+        if (schema !== undefined)
+            cliArgs.push(`--schema=${schema}`);
+        if (includeSystem !== undefined)
+            cliArgs.push(`--include-system=${includeSystem}`);
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 30_000,
+            env: { NODE_ENV: 'production' },
+            stripFinalNewline: true,
+        });
+        // Branch C: CLI failure — real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to list database tables.
+
+Project path: ${projectCwd}
+Config: ${config}
+Schema filter: ${schema ?? 'all user-owned schemas'}
+includeSystem: ${includeSystem ?? false}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- CLI output ---
+stdout:
+${result.stdout}
+
+stderr:
+${result.stderr}
+--- end CLI output ---
+
+For the assistant:
+- Tell the user that listing the database tables did not complete successfully.
+- Summarise the most likely cause from the CLI output in plain language. Common causes:
+  * Config file not found — suggest verifying the path and that the file exists in the project.
+  * Database connection failed — suggest verifying the credentials, that the host is reachable, and that the port is open.
+  * Unknown command 'schema list' — the installed RESTForge version may be older than this CLI subcommand; suggest upgrading the package.
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.
+- Offer to retry once the underlying issue is resolved.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Branch D: JSON parse failure — real error per §3.4 (CLI succeeded but produced invalid output).
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to parse the database table list as JSON.
+
+Project path: ${projectCwd}
+Config: ${config}
+Reason: ${msg}
+
+--- Raw stdout ---
+${result.stdout}
+--- end Raw stdout ---
+
+For the assistant:
+- The CLI returned output that is not valid JSON.
+- Summarise this to the user in plain language; do not paste the raw stdout unless they explicitly ask.
+- Suggest checking that the installed RESTForge package version is compatible. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Defensive labeled facts: if the JSON shape changes upstream, fall back to 'unknown' / 'n/a'
+        // rather than crashing. Mirror the catalog tools pattern.
+        const root = (parsed ?? {});
+        const summary = (root.summary ?? {});
+        const totalTables = typeof summary.totalTables === 'number' ? summary.totalTables : 'unknown';
+        const databaseType = typeof summary.database === 'string' ? summary.database : 'unknown';
+        const schemasInResult = Array.isArray(summary.schemas)
+            ? `[${summary.schemas.map((s) => JSON.stringify(s)).join(', ')}]`
+            : 'unknown';
+        const prettyJson = JSON.stringify(parsed, null, 2);
+        // Branch B: success — one-line summary + labeled facts + fenced JSON output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Database tables retrieved successfully.
+
+Project path: ${projectCwd}
+Config: ${config}
+Database: ${databaseType}
+Schema filter: ${schema ?? 'all user-owned schemas'}
+totalTables: ${totalTables}
+schemas in result: ${schemasInResult}
+
+--- Database Tables (JSON) ---
+${prettyJson}
+--- end Database Tables (JSON) ---
+
+For the assistant:
+- Confirm to the user that the table list was retrieved. Mention the database type and the total count in plain language.
+- If a specific table was named in the user's question, find it in the list and confirm whether it exists; if not found, say so explicitly.
+- Do not paste the full JSON unless the user asks. Summarise instead — for many tables, group by schema or list only the names relevant to the user's task.
+- This is a read-only operation: it queries the database catalog tables (information_schema / pg_catalog / all_tables) without modifying anything.
+- For deeper details on a specific table (columns, primary key, foreign keys, indexes), suggest the table-describe action as the next step. Do not mention internal tool names.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=list-tables.js.map

package/dist/tools/codegen/list-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-tables.js","sourceRoot":"","sources":["../../../src/tools/codegen/list-tables.ts"],"names":[],"mappings":"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"}

package/dist/tools/codegen/sync-payload.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenSyncPayload(server: McpServer): void;

package/dist/tools/codegen/sync-payload.js

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenSyncPayload(server) {
+    server.registerTool('codegen_sync_payload', {
+        title: 'Sync Payload',
+        description: `Apply schema drift to existing payload spec files in a project, archiving the previous version of each updated file, by running restforge 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 payload --sync --config=<config> [--table=<table>] [--output=<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 '<filename>.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/platform 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.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder (must contain node_modules/@restforgejs/platform and the config file)'),
+            config: z
+                .string()
+                .min(1)
+                .default('db-connection.env')
+                .describe('Config file name (relative to project) used by the CLI to connect to the database'),
+            table: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Specific table name to sync (e.g. supplier or core.supplier). When omitted, all payload files in the output directory are synced.'),
+            output: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Payload directory relative to project (e.g. payload). When omitted, the CLI uses its default (payload/).'),
+        },
+        annotations: {
+            title: 'Sync Payload',
+            readOnlyHint: false, // tool menulis ulang file payload + membuat file archive
+            idempotentHint: false, // memanggil ulang dapat menambah file archive baru jika DB berubah lagi di antara panggilan
+        },
+    }, async ({ cwd, config, table, output }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be present in node_modules.
+        // Treated as a non-error precondition per the authoring guide §3.4.
+        try {
+            await access(join(projectCwd, 'node_modules', '@restforgejs', 'platform'));
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge package is not installed in this project.
+
+Project path: ${projectCwd}
+Expected location: node_modules/@restforgejs/platform
+Requested table: ${table ?? 'all'}
+Requested config: ${config}
+Requested output: ${output ?? 'default (payload/)'}
+
+For the assistant:
+- The user needs to install the RESTForge package before payload files can be synced with the database schema.
+- Use the appropriate package-installation tool to do this, then retry syncing the payload.
+- When explaining to the user, say something like "the RESTForge package isn't installed yet — should I install it first?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Forward only the arguments the user supplied. Defaults inside restforge
+        // (e.g. payload/ as the default output dir, all files when --table is omitted)
+        // should remain in effect when the user does not specify them. per §3.5
+        const args = ['restforge', 'payload', 'sync', `--config=${config}`];
+        if (table)
+            args.push(`--table=${table}`);
+        if (output)
+            args.push(`--output=${output}`);
+        // Timeout raised to 60s (vs 30s for validate/diff): sync writes payload files
+        // and renames each previous version to a sequential archive, which can take
+        // longer than read-only operations on projects with many payload files.
+        const result = await execProcess('npx', args, { cwd: projectCwd, timeout: 60_000 });
+        // CLI failure: real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to sync payload.
+
+Project path: ${projectCwd}
+Config: ${config}
+Table: ${table ?? 'all'}
+Output: ${output ?? 'default (payload/)'}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- CLI output ---
+stdout:
+${result.stdout}
+
+stderr:
+${result.stderr}
+--- end CLI output ---
+
+For the assistant:
+- Tell the user that updating the payload files did not complete successfully.
+- Summarise the likely cause from the CLI output in plain language (common causes: the config file is missing or has incomplete credentials, the database is unreachable, the requested table does not exist, or the payload directory is empty). Do not paste the raw stdout/stderr unless the user explicitly asks.
+- Reassure the user: when a sync run fails, the CLI automatically restores any payload file that was just archived back to its original name, so the active payload files are not left in a corrupted state.
+- Offer to retry once the underlying issue is resolved. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Success: one-line summary + labeled facts + fenced raw output per §3.5.
+        // The CLI prints per-file status lines ([SKIP] / [ARCHIVE] / [SYNCED]) and a
+        // Summary section with totals. The model should extract the counts and the
+        // archive filenames from stdout when talking to the user. per §5.2 cross-ref
+        // back to validate/diff.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Payload sync completed.
+
+Project path: ${projectCwd}
+Config: ${config}
+Table: ${table ?? 'all'}
+Output: ${output ?? 'default (payload/)'}
+Command: ${result.command}
+
+--- CLI output ---
+${result.stdout}
+--- end CLI output ---
+
+For the assistant:
+- Read the Summary section in the CLI output above and tell the user how many payload files were SYNCED and how many were SKIPPED (already in sync). Do not paste the raw CLI output unless the user explicitly asks.
+- For each file that was updated, the previous version of the file was renamed to '<filename>.archive.NNN' (NNN is a sequential number, starting at 001) in the same payload directory. Mention this to the user in plain language so they know the old version is still on disk and available for manual rollback if needed. If the CLI output lists specific archive filenames, you may relay them to the user.
+- Important: warn the user that any module or endpoint that was previously generated from the older payload still reflects the old schema. To bring those endpoints in line with the new schema, the user needs to regenerate the endpoint code from the updated payload as a follow-up step. Describe this in plain language; do not name the internal tool.
+- If no files were synced (every file was SKIPPED because it was already in sync), confirm in plain language that the payload files already match the database and no changes were applied.
+- Keep the reply concise. Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=sync-payload.js.map

package/dist/tools/codegen/sync-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-payload.js","sourceRoot":"","sources":["../../../src/tools/codegen/sync-payload.ts"],"names":[],"mappings":"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"}

package/dist/tools/codegen/validate-dashboard-payload.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenValidateDashboardPayload(server: McpServer): void;