@husar.ai/cli 0.4.0 → 0.4.1

package/MCP_SERVER.md

@@ -49,6 +49,8 @@ Notes:
 
 ## Available Tools
 
+### Core CLI Tools
+
 - `husar_copy`:
   - Purpose: Parse a CMS file into a shape or model and upsert via CLI.
   - Inputs:
@@ -69,6 +71,96 @@ Notes:
     - `cms/zeus/index.ts`, `cms/zeus/const.ts`
     - `cms/host.ts`, `cms/ssr.ts`, `cms/react.ts`
 
+### Discovery & Schema Tools
+
+These tools help AI agents understand the CMS structure before making updates:
+
+- `listModels`: List all model definitions with their field structures.
+- `listViews`: List all view definitions with their field structures.
+- `listShapes`: List all available shape definitions.
+- `graphQLTypes`: Get the generated GraphQL SDL schema showing all input/output types. Essential for understanding the exact structure expected by `model.upsert` and `view.upsert`.
+
+### Combined "GetWithContent" Tools
+
+**Recommended workflow:** Always call the appropriate `getWithContent` tool BEFORE calling `upsert` to understand the exact data structure expected.
+
+- `model.getWithContent`:
+  - Purpose: Get complete model information including definition, fieldSet (expanded shapes), GraphQL types, and optionally current content.
+  - Inputs:
+    - `name` (required): Model name
+    - `slug` (optional): Document slug to fetch existing content
+    - `filter` (optional): Root params filter (e.g., `{ "_language": "en" }`)
+  - Returns: `{ definition, fieldSet, graphQLTypes, content }`
+
+- `view.getWithContent`:
+  - Purpose: Get complete view information including definition, fieldSet (expanded shapes), GraphQL types, and current content.
+  - Inputs:
+    - `name` (required): View name
+    - `filter` (optional): Root params filter (e.g., `{ "_language": "en" }`)
+  - Returns: `{ definition, fieldSet, graphQLTypes, content }`
+
+- `shape.getWithDefinition`:
+  - Purpose: Get complete shape information including definition, fieldSet (expanded nested shapes), and GraphQL types.
+  - Inputs:
+    - `name` (required): Shape name
+  - Returns: `{ definition, fieldSet, graphQLTypes }`
+
+### Model CRUD Tools
+
+- `model.model`: Return full model configuration
+- `model.previewFields`: Return expanded fields for model
+- `model.fieldSet`: Return admin page fieldset
+- `model.upsert`: Create or update a model content document
+  - **Important:** First call `model.getWithContent` to see the expected structure
+  - Inputs: `name`, `slug`, `args` (document content), `draft_version`, `filter`
+- `model.remove`: Remove a model entry
+- `model.list`: List model entries
+- `model.listPaginated`: List model entries with pagination
+- `model.one`: Get one model entry by slug
+- `model.listById`: Get entries by IDs
+
+### View CRUD Tools
+
+- `view.model`: Return full view configuration
+- `view.previewFields`: Return expanded fields for view
+- `view.fieldSet`: Return admin page fieldset for view
+- `view.upsert`: Create or update a view entry (singleton)
+  - **Important:** First call `view.getWithContent` to see the expected structure
+  - Inputs: `name`, `args` (view content), `draft_version`, `filter`, `formArgs`
+- `view.remove`: Remove a view entry
+- `view.list`: List view entries
+- `view.one`: Get one view entry
+
+### Shape Tools
+
+- `shape.model`: Return full shape configuration
+- `shape.previewFields`: Return expanded fields for shape
+- `shape.fieldSet`: Return admin page fieldset for shape
+
+### Form Tools
+
+- `form.model`, `form.previewFields`, `form.fieldSet`: Form configuration tools
+- `form.upsert`, `form.remove`, `form.list`, `form.one`: Form CRUD operations
+- `form.submitResponse`, `form.responses`, `form.response`, `form.removeResponse`, `form.responseFieldSet`: Form response handling
+
+### Definition Management Tools
+
+These tools manage CMS definitions (schemas), not content:
+
+- `upsertModel`, `removeModel`: Manage model definitions
+- `upsertView`, `removeView`: Manage view definitions
+- `upsertShape`, `removeShape`: Manage shape definitions
+- `upsertForm`, `removeForm`: Manage form definitions
+- `removeModelWithDocuments`: Remove a model and all its documents
+- `removeDocumentsWithParams`: Remove documents matching root params
+
+### AI Generation Tools
+
+- `generateContent`: Generate content using AI
+- `generateImage`: Generate an image
+- `translateDocument`, `translateView`, `translateForm`: Translation tools
+- `husarViewAgent`: Specialized agent for view creation/modification from natural language
+
 ## Troubleshooting
 
 - CLI not found: Ensure `@husar.ai/cli` is installed globally or that `husar.ai` is on PATH.