gufi-cli 0.1.21 → 0.1.22

package/dist/mcp.js

@@ -122,30 +122,29 @@ async function developerRequest(path, options = {}, retry = true) {
     return res.json();
 }
 // ════════════════════════════════════════════════════════════════════════════
-// Tool Definitions
+// Tool Definitions - Descriptions loaded from docs/mcp/tool-descriptions.json
 // ════════════════════════════════════════════════════════════════════════════
+// Load tool descriptions from centralized documentation
+const TOOL_DESCRIPTIONS_PATH = path.join(DOCS_MCP_PATH, "tool-descriptions.json");
+let toolDescriptions = {};
+try {
+    const content = fs.readFileSync(TOOL_DESCRIPTIONS_PATH, "utf-8");
+    toolDescriptions = JSON.parse(content);
+}
+catch (err) {
+    console.error(`Warning: Could not load tool descriptions from ${TOOL_DESCRIPTIONS_PATH}`);
+}
+// Helper to get description from JSON or use fallback
+function getDesc(toolName, fallback = "") {
+    return toolDescriptions[toolName]?.description || fallback;
+}
 const TOOLS = [
     // ─────────────────────────────────────────────────────────────────────────
     // Context & Info
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_context",
-        description: `Generate intelligent context about a Gufi project. This is the FIRST tool to use when starting work on a Gufi project - it provides a complete overview of modules, entities, fields, automations, and relationships.
-
-Use cases:
-- Starting work on a package: gufi_context({ package_id: "14" })
-- Understanding a view: gufi_context({ view_id: "13" })
-- Exploring a company: gufi_context({ company_id: "116" })
-
-The context includes:
-- All modules and their entities (tables) with physical table names
-- Field definitions with types, constraints, and options
-- Available automations and their trigger types
-- DataSources mappings for views (viewSpec.mainTable, etc.)
-- Environment variables available
-- Useful CLI commands for the project
-
-Returns markdown-formatted context optimized for Claude.`,
+        description: getDesc("gufi_context"),
         inputSchema: {
             type: "object",
             properties: {
@@ -158,20 +157,12 @@ Returns markdown-formatted context optimized for Claude.`,
     },
     {
         name: "gufi_whoami",
-        description: "Get current user info and environment (local/prod). Use this to verify authentication status before making changes.",
+        description: getDesc("gufi_whoami"),
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "gufi_schema",
-        description: `Get the database schema of a company - lists all modules, entities (tables), and their fields.
-
-Returns for each entity:
-- id: Entity ID
-- name: Entity name
-- table: Physical table name (m{moduleId}_t{entityId})
-- fields: Array of {name, type, label}
-
-Use this to understand the data structure before creating queries or modifications.`,
+        description: getDesc("gufi_schema"),
         inputSchema: {
             type: "object",
             properties: {
@@ -182,26 +173,7 @@ Use this to understand the data structure before creating queries or modificatio
     },
     {
         name: "gufi_docs",
-        description: `Read documentation about Gufi. Use this when you need detailed information about specific topics.
-
-Available topics:
-- "overview" - Overview and workflow (start here)
-- "architecture" - Technical architecture
-- "modules" - Module system and entities
-- "fields" - Field types and CB builders (IMPORTANT for data operations)
-- "views" - View system, SDK, and React components
-- "automations" - Automations and worker
-- "api" - API endpoints reference
-- "packages" - Packages and marketplace
-- "errors" - Common errors and solutions
-- "examples" - Practical code examples
-
-You can also search across all docs with the search parameter.
-
-Examples:
-- gufi_docs({ topic: "fields" }) - Read about field types
-- gufi_docs({ topic: "errors" }) - Common errors and fixes
-- gufi_docs({ search: "currency" }) - Search for currency info`,
+        description: getDesc("gufi_docs"),
         inputSchema: {
             type: "object",
             properties: {
@@ -215,12 +187,12 @@ Examples:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_companies",
-        description: "List all companies the user has access to. Returns company IDs, names, and creation dates.",
+        description: getDesc("gufi_companies"),
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "gufi_company_create",
-        description: "Create a new company. Returns the new company ID.",
+        description: getDesc("gufi_company_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -234,7 +206,7 @@ Examples:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_modules",
-        description: "List all modules of a company. Modules define the data structure (entities, fields, relations). Returns module IDs, names, and entity counts.",
+        description: getDesc("gufi_modules"),
         inputSchema: {
             type: "object",
             properties: {
@@ -245,26 +217,7 @@ Examples:
     },
     {
         name: "gufi_module",
-        description: `Get the full JSON definition of a module. Auto-detects company from module ID.
-
-Returns the complete module structure:
-- name, displayName, icon
-- submodules[]: Array of submodules
-  - entities[]: Array of entities (tables)
-    - name, label, kind
-    - fields[]: Array of fields with type, label, required, options, etc.
-
-Field types (from @gufi/column-types):
-- Text: text, email, url, barcode
-- Numbers: number_int, number_float, percentage
-- Date/Time: date, datetime, time
-- Boolean: boolean
-- Selection: select (single), multiselect (array)
-- Relations: relation (FK), reversed_relation (virtual), users (array of user IDs)
-- Complex (JSONB): currency, phone, location, file, signature, json
-- Computed: formula, mirror
-
-Each type has specific format. Use gufi.CB.* builders for correct format.`,
+        description: getDesc("gufi_module"),
         inputSchema: {
             type: "object",
             properties: {
@@ -275,33 +228,7 @@ Each type has specific format. Use gufi.CB.* builders for correct format.`,
     },
     {
         name: "gufi_module_update",
-        description: `Update a module's JSON definition. Use this to add/modify entities, fields, relations.
-
-IMPORTANT: Always read the module first with gufi_module, modify the JSON, then update.
-
-Common modifications:
-- Add a field: Add to entity.fields array
-- Add an entity: Add to submodule.entities array
-- Modify field: Change properties like type, label, required, options
-
-Example field definition:
-{
-  "name": "fecha_entrega",
-  "type": "date",
-  "label": "Fecha de Entrega",
-  "required": false
-}
-
-For select fields, include options:
-{
-  "name": "estado",
-  "type": "select",
-  "label": "Estado",
-  "options": [
-    { "value": "pendiente", "label": "Pendiente", "color": "yellow" },
-    { "value": "completado", "label": "Completado", "color": "green" }
-  ]
-}`,
+        description: getDesc("gufi_module_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -313,28 +240,7 @@ For select fields, include options:
     },
     {
         name: "gufi_module_create",
-        description: `Create a new module in a company.
-
-Example module structure:
-{
-  "name": "inventory",
-  "displayName": "Inventario",
-  "icon": "Package",
-  "submodules": [{
-    "name": "products",
-    "label": "Productos",
-    "entities": [{
-      "name": "productos",
-      "label": "Productos",
-      "kind": "table",
-      "fields": [
-        { "name": "nombre", "type": "text", "label": "Nombre", "required": true },
-        { "name": "precio", "type": "currency", "label": "Precio" },
-        { "name": "stock", "type": "number_int", "label": "Stock" }
-      ]
-    }]
-  }]
-}`,
+        description: getDesc("gufi_module_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -349,14 +255,7 @@ Example module structure:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_automations",
-        description: `List all automation scripts of a company. Automations are JavaScript functions that run on events.
-
-Trigger types:
-- on_create: Runs when a row is created
-- on_update: Runs when a row is updated
-- on_delete: Runs when a row is deleted
-- on_click: Manually triggered from UI buttons
-- schedule: Runs on a cron schedule`,
+        description: getDesc("gufi_automations"),
         inputSchema: {
             type: "object",
             properties: {
@@ -367,7 +266,7 @@ Trigger types:
     },
     {
         name: "gufi_automation",
-        description: "Get the JavaScript code and metadata of an automation script. Returns id, name, description, company_id, and the full JS code.",
+        description: getDesc("gufi_automation"),
         inputSchema: {
             type: "object",
             properties: {
@@ -378,32 +277,7 @@ Trigger types:
     },
     {
         name: "gufi_automation_create",
-        description: `Create or update an automation script. If a script with the same name exists, it will be updated.
-
-IMPORTANT: api.query() returns rows directly, NOT { rows }:
-  const rows = await api.query("SELECT * FROM table");  // ✅ Correct
-  const { rows } = await api.query(...);                // ❌ Wrong!
-
-Available API methods:
-- api.query(sql, params) - Execute SQL, returns rows array
-- api.getOne(table, id) - Get single row
-- api.getList(table, { filters, sort, limit }) - Get multiple rows
-- api.create(table, data) - Create row, returns { id }
-- api.update(table, id, data) - Update row
-- api.delete(table, id) - Delete row
-- api.log(message) - Log for debugging
-- api.sendEmail({ to, subject, body }) - Send email
-- api.sendWhatsApp({ to, template, params }) - Send WhatsApp
-
-Example automation:
-async function send_welcome_email({ record, api }) {
-  const { email, nombre } = record;
-  await api.sendEmail({
-    to: email,
-    subject: "Bienvenido!",
-    body: \`Hola \${nombre}, gracias por registrarte.\`
-  });
-}`,
+        description: getDesc("gufi_automation_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -417,7 +291,7 @@ async function send_welcome_email({ record, api }) {
     },
     {
         name: "gufi_entity_automations",
-        description: "Get the automation triggers configured for an entity. Shows which scripts run on create, update, delete, or click events.",
+        description: getDesc("gufi_entity_automations"),
         inputSchema: {
             type: "object",
             properties: {
@@ -428,19 +302,7 @@ async function send_welcome_email({ record, api }) {
     },
     {
         name: "gufi_entity_automations_update",
-        description: `Update the automation triggers for an entity. Configure which scripts run on which events.
-
-Example configuration:
-{
-  "on_create": ["send_welcome_email"],
-  "on_update": ["sync_to_external", "notify_changes"],
-  "on_delete": [],
-  "on_click": [
-    { "function_name": "generate_report", "label": "Generar Reporte", "icon": "FileText" }
-  ]
-}
-
-For on_click, you can specify label and icon for the button that triggers it.`,
+        description: getDesc("gufi_entity_automations_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -455,7 +317,7 @@ For on_click, you can specify label and icon for the button that triggers it.`,
     },
     {
         name: "gufi_automations_executions",
-        description: "Get the execution history of automations. Useful for debugging - shows success/failure, duration, and error messages.",
+        description: getDesc("gufi_automations_executions"),
         inputSchema: {
             type: "object",
             properties: {
@@ -471,13 +333,7 @@ For on_click, you can specify label and icon for the button that triggers it.`,
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_rows",
-        description: `List rows from a table. Table names follow the pattern m{moduleId}_t{entityId}.
-Company is auto-detected from the module ID in the table name.
-
-Supports:
-- Pagination: limit (default 20), offset (default 0)
-- Sorting: sort (field name), order (ASC/DESC)
-- Filtering: filter="field=value"`,
+        description: getDesc("gufi_rows"),
         inputSchema: {
             type: "object",
             properties: {
@@ -493,7 +349,7 @@ Supports:
     },
     {
         name: "gufi_row",
-        description: "Get a single row by ID. Returns all fields including relations and computed values.",
+        description: getDesc("gufi_row"),
         inputSchema: {
             type: "object",
             properties: {
@@ -505,35 +361,7 @@ Supports:
     },
     {
         name: "gufi_row_create",
-        description: `Create a new row in a table. Data should match the entity's field schema.
-
-Field formats (from @gufi/column-types):
-
-SIMPLE TYPES:
-- text/email/url/barcode: "string value"
-- number_int: 42 (integer)
-- number_float: 3.14 (decimal)
-- percentage: 0.75 (decimal, displayed as 75%)
-- boolean: true/false
-- date: "2024-01-15" (ISO date)
-- datetime: "2024-01-15T10:30:00Z" (ISO)
-- time: "14:30:00"
-- select: "value" (option value, not label)
-- relation: 123 (FK integer)
-
-ARRAY TYPES:
-- multiselect: ["value1", "value2"]
-- users: [16, 23] (array of user IDs)
-
-JSONB TYPES (complex objects):
-- currency: { "currency": "EUR", "amount": 150.00 }
-- phone: { "prefix": "+34", "number": "612345678" }
-- location: { "street": "Mayor", "number": "15", "city": "Madrid", "lat": 40.41, "lng": -3.70 }
-- file: [{ "url": "company_130/uuid.pdf", "name": "doc.pdf" }] or ["company_130/photo.jpg"]
-- signature: "data:image/png;base64,..." (base64 data URL)
-- json: { any: "object" }
-
-In views, use gufi.CB.* builders for correct formatting.`,
+        description: getDesc("gufi_row_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -545,20 +373,7 @@ In views, use gufi.CB.* builders for correct formatting.`,
     },
     {
         name: "gufi_row_update",
-        description: `Update an existing row. Only include fields you want to change.
-
-IMPORTANT for select/relation fields:
-When updating a select or relation field, you must update BOTH:
-- The field value: "estado": "completado"
-- The display value: "estado__display": "Completado"
-
-Example:
-{
-  "estado": "completado",
-  "estado__display": "Completado",
-  "cliente": 123,
-  "cliente__display": "Empresa ABC"
-}`,
+        description: getDesc("gufi_row_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -571,7 +386,7 @@ Example:
     },
     {
         name: "gufi_row_delete",
-        description: "Delete a row from a table. This is permanent and cannot be undone.",
+        description: getDesc("gufi_row_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -586,7 +401,7 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_env",
-        description: "List environment variables of a company. These are used in automations via process.env.KEY.",
+        description: getDesc("gufi_env"),
         inputSchema: {
             type: "object",
             properties: {
@@ -596,7 +411,7 @@ Example:
     },
     {
         name: "gufi_env_set",
-        description: "Create or update an environment variable. Used for API keys, secrets, and configuration.",
+        description: getDesc("gufi_env_set"),
         inputSchema: {
             type: "object",
             properties: {
@@ -608,7 +423,7 @@ Example:
     },
     {
         name: "gufi_env_delete",
-        description: "Delete an environment variable.",
+        description: getDesc("gufi_env_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -622,7 +437,7 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_view_files",
-        description: "Get all files of a marketplace view. Returns the React/TypeScript code, CSS, and configuration files.",
+        description: getDesc("gufi_view_files"),
         inputSchema: {
             type: "object",
             properties: {
@@ -633,7 +448,7 @@ Example:
     },
     {
         name: "gufi_view_file_update",
-        description: "Update a single file in a marketplace view. Use for modifying React components, styles, or configuration.",
+        description: getDesc("gufi_view_file_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -646,7 +461,7 @@ Example:
     },
     {
         name: "gufi_view_files_update",
-        description: "Update multiple files in a marketplace view at once. More efficient than updating one by one.",
+        description: getDesc("gufi_view_files_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -672,12 +487,12 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_packages",
-        description: "List all packages owned by the user. Packages bundle modules and views for distribution in the Marketplace.",
+        description: getDesc("gufi_packages"),
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "gufi_package",
-        description: "Get detailed information about a package including its modules, views, and publication status.",
+        description: getDesc("gufi_package"),
         inputSchema: {
             type: "object",
             properties: {
@@ -688,7 +503,7 @@ Example:
     },
     {
         name: "gufi_package_create",
-        description: "Create a new package. After creation, add modules and views to it.",
+        description: getDesc("gufi_package_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -700,7 +515,7 @@ Example:
     },
     {
         name: "gufi_package_delete",
-        description: "Delete a package. Only works if the package is not published.",
+        description: getDesc("gufi_package_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -711,7 +526,7 @@ Example:
     },
     {
         name: "gufi_package_add_module",
-        description: "Import a module into a package. The module will be snapshotted for distribution.",
+        description: getDesc("gufi_package_add_module"),
         inputSchema: {
             type: "object",
             properties: {
@@ -724,7 +539,7 @@ Example:
     },
     {
         name: "gufi_package_remove_module",
-        description: "Remove a module from a package.",
+        description: getDesc("gufi_package_remove_module"),
         inputSchema: {
             type: "object",
             properties: {
@@ -736,7 +551,7 @@ Example:
     },
     {
         name: "gufi_package_add_view",
-        description: "Add a marketplace view to a package.",
+        description: getDesc("gufi_package_add_view"),
         inputSchema: {
             type: "object",
             properties: {
@@ -748,7 +563,7 @@ Example:
     },
     {
         name: "gufi_package_remove_view",
-        description: "Remove a view from a package.",
+        description: getDesc("gufi_package_remove_view"),
         inputSchema: {
             type: "object",
             properties: {
@@ -760,7 +575,7 @@ Example:
     },
     {
         name: "gufi_package_publish",
-        description: "Publish a package to the Marketplace. Makes it available for installation by other companies.",
+        description: getDesc("gufi_package_publish"),
         inputSchema: {
             type: "object",
             properties: {
@@ -771,7 +586,7 @@ Example:
     },
     {
         name: "gufi_package_unpublish",
-        description: "Unpublish a package from the Marketplace.",
+        description: getDesc("gufi_package_unpublish"),
         inputSchema: {
             type: "object",
             properties: {
@@ -782,7 +597,7 @@ Example:
     },
     {
         name: "gufi_package_sync",
-        description: "Sync package version - updates module snapshots and increments version number.",
+        description: getDesc("gufi_package_sync"),
         inputSchema: {
             type: "object",
             properties: {
@@ -793,7 +608,7 @@ Example:
     },
     {
         name: "gufi_package_check",
-        description: "Check if package modules have changes that need syncing.",
+        description: getDesc("gufi_package_check"),
         inputSchema: {
             type: "object",
             properties: {
@@ -807,7 +622,7 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_package_migrations",
-        description: "List SQL migrations for a package. Migrations run when clients update to new versions.",
+        description: getDesc("gufi_package_migrations"),
         inputSchema: {
             type: "object",
             properties: {
@@ -818,7 +633,7 @@ Example:
     },
     {
         name: "gufi_package_migration_create",
-        description: "Create a SQL migration for a package. Use placeholders: {tableName}, {entityId}, {companyId}.",
+        description: getDesc("gufi_package_migration_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -834,7 +649,7 @@ Example:
     },
     {
         name: "gufi_package_migration_delete",
-        description: "Delete a migration (only if not yet applied to any installation).",
+        description: getDesc("gufi_package_migration_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -846,7 +661,7 @@ Example:
     },
     {
         name: "gufi_package_entities",
-        description: "List entities available in a package. Use for target_entity in migrations.",
+        description: getDesc("gufi_package_entities"),
         inputSchema: {
             type: "object",
             properties: {
@@ -1354,6 +1169,15 @@ const toolHandlers = {
                 content: f.content,
                 is_entry_point: f.is_entry_point,
             })),
+            _hint: {
+                cli_workflow: [
+                    `gufi view:pull ${params.view_id}  # Download files to local folder`,
+                    "# Edit files locally with your editor",
+                    "gufi view:push                    # Upload changes back to Gufi",
+                    "gufi view:watch                   # Auto-sync on file changes",
+                ],
+                note: "For large views, consider using CLI commands instead of MCP tools",
+            },
         };
     },
     async gufi_view_file_update(params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gufi-cli",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "CLI for developing Gufi Marketplace views locally with Claude Code",
   "bin": {
     "gufi": "./bin/gufi.js"