@constructive-io/graphql-codegen 4.24.4 → 4.25.0

package/core/codegen/cli/docs-generator.d.ts

@@ -1,10 +1,9 @@
 import type { Table, Operation, TypeRegistry } from '../../../types/schema';
-import type { GeneratedDocFile, McpTool } from '../docs-utils';
+import type { GeneratedDocFile } from '../docs-utils';
 export { resolveDocsConfig } from '../docs-utils';
-export type { GeneratedDocFile, McpTool } from '../docs-utils';
+export type { GeneratedDocFile } from '../docs-utils';
 export declare function generateReadme(tables: Table[], customOperations: Operation[], toolName: string, registry?: TypeRegistry): GeneratedDocFile;
 export declare function generateAgentsDocs(tables: Table[], customOperations: Operation[], toolName: string, _registry?: TypeRegistry): GeneratedDocFile;
-export declare function getCliMcpTools(tables: Table[], customOperations: Operation[], toolName: string, registry?: TypeRegistry): McpTool[];
 export declare function generateSkills(tables: Table[], customOperations: Operation[], toolName: string, targetName: string, registry?: TypeRegistry): GeneratedDocFile[];
 export interface MultiTargetDocsInput {
     toolName: string;
@@ -24,5 +23,4 @@ export interface MultiTargetDocsInput {
 }
 export declare function generateMultiTargetReadme(input: MultiTargetDocsInput): GeneratedDocFile;
 export declare function generateMultiTargetAgentsDocs(input: MultiTargetDocsInput): GeneratedDocFile;
-export declare function getMultiTargetCliMcpTools(input: MultiTargetDocsInput): McpTool[];
 export declare function generateMultiTargetSkills(input: MultiTargetDocsInput): GeneratedDocFile[];

package/core/codegen/cli/docs-generator.js

@@ -3,11 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDocsConfig = void 0;
 exports.generateReadme = generateReadme;
 exports.generateAgentsDocs = generateAgentsDocs;
-exports.getCliMcpTools = getCliMcpTools;
 exports.generateSkills = generateSkills;
 exports.generateMultiTargetReadme = generateMultiTargetReadme;
 exports.generateMultiTargetAgentsDocs = generateMultiTargetAgentsDocs;
-exports.getMultiTargetCliMcpTools = getMultiTargetCliMcpTools;
 exports.generateMultiTargetSkills = generateMultiTargetSkills;
 const komoji_1 = require("komoji");
 const docs_utils_1 = require("../docs-utils");
@@ -103,6 +101,12 @@ function generateReadme(tables, customOperations, toolName, registry) {
             lines.push('| Subcommand | Description |');
             lines.push('|------------|-------------|');
             lines.push(`| \`list\` | List all ${singularName} records |`);
+            lines.push(`| \`find-first\` | Find first matching ${singularName} record |`);
+            const readmeSpecialGroups = (0, docs_utils_1.categorizeSpecialFields)(table, registry);
+            const readmeHasSearch = readmeSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding');
+            if (readmeHasSearch) {
+                lines.push(`| \`search <query>\` | Search ${singularName} records |`);
+            }
             lines.push(`| \`get\` | Get a ${singularName} by ${pk.name} |`);
             lines.push(`| \`create\` | Create a new ${singularName} |`);
             lines.push(`| \`update\` | Update an existing ${singularName} |`);
@@ -225,232 +229,6 @@ function generateAgentsDocs(tables, customOperations, toolName, _registry) {
         content: lines.join('\n'),
     };
 }
-function getCliMcpTools(tables, customOperations, toolName, registry) {
-    const tools = [];
-    tools.push({
-        name: `${toolName}_context_create`,
-        description: 'Create a named API context pointing at a GraphQL endpoint',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Context name' },
-                endpoint: { type: 'string', description: 'GraphQL endpoint URL' },
-            },
-            required: ['name', 'endpoint'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_context_list`,
-        description: 'List all configured API contexts',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_context_use`,
-        description: 'Set the active API context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Context name to activate' },
-            },
-            required: ['name'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_context_current`,
-        description: 'Show the currently active API context',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_context_delete`,
-        description: 'Delete an API context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Context name to delete' },
-            },
-            required: ['name'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_auth_set_token`,
-        description: 'Store a bearer token for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                token: { type: 'string', description: 'Bearer token value' },
-            },
-            required: ['token'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_auth_status`,
-        description: 'Show authentication status for all contexts',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_auth_logout`,
-        description: 'Remove credentials for the current context',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_config_get`,
-        description: 'Get a config variable value for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Variable name' },
-            },
-            required: ['key'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_config_set`,
-        description: 'Set a config variable value for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Variable name' },
-                value: { type: 'string', description: 'Variable value' },
-            },
-            required: ['key', 'value'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_config_list`,
-        description: 'List all config variables for the current context',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_config_delete`,
-        description: 'Delete a config variable for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Variable name to delete' },
-            },
-            required: ['key'],
-        },
-    });
-    for (const table of tables) {
-        const { singularName } = (0, utils_1.getTableNames)(table);
-        const kebab = (0, komoji_1.toKebabCase)(singularName);
-        const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
-        const scalarFields = (0, utils_1.getScalarFields)(table);
-        const editableFields = (0, docs_utils_1.getEditableFields)(table, registry);
-        const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
-        const requiredCreateFieldNames = editableFields
-            .filter((f) => !defaultFields.has(f.name))
-            .map((f) => f.name);
-        tools.push({
-            name: `${toolName}_${kebab}_list`,
-            description: `List all ${table.name} records`,
-            inputSchema: { type: 'object', properties: {} },
-        });
-        tools.push({
-            name: `${toolName}_${kebab}_get`,
-            description: `Get a single ${table.name} record by ${pk.name}`,
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    [pk.name]: {
-                        type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(pk.gqlType),
-                        description: `${table.name} ${pk.name}`,
-                    },
-                },
-                required: [pk.name],
-            },
-        });
-        const createProps = {};
-        for (const f of editableFields) {
-            createProps[f.name] = {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
-                description: `${table.name} ${f.name}`,
-            };
-        }
-        tools.push({
-            name: `${toolName}_${kebab}_create`,
-            description: `Create a new ${table.name} record`,
-            inputSchema: {
-                type: 'object',
-                properties: createProps,
-                ...(requiredCreateFieldNames.length > 0 ? { required: requiredCreateFieldNames } : {}),
-            },
-        });
-        const updateProps = {
-            [pk.name]: {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(pk.gqlType),
-                description: `${table.name} ${pk.name}`,
-            },
-        };
-        for (const f of editableFields) {
-            updateProps[f.name] = {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
-                description: `${table.name} ${f.name}`,
-            };
-        }
-        tools.push({
-            name: `${toolName}_${kebab}_update`,
-            description: `Update an existing ${table.name} record`,
-            inputSchema: {
-                type: 'object',
-                properties: updateProps,
-                required: [pk.name],
-            },
-        });
-        tools.push({
-            name: `${toolName}_${kebab}_delete`,
-            description: `Delete a ${table.name} record by ${pk.name}`,
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    [pk.name]: {
-                        type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(pk.gqlType),
-                        description: `${table.name} ${pk.name}`,
-                    },
-                },
-                required: [pk.name],
-            },
-        });
-        tools.push({
-            name: `${toolName}_${kebab}_fields`,
-            description: `List available fields for ${table.name}`,
-            inputSchema: { type: 'object', properties: {} },
-            _meta: {
-                fields: scalarFields.map((f) => ({
-                    name: f.name,
-                    type: (0, docs_utils_1.cleanTypeName)(f.type.gqlType),
-                    editable: editableFields.some((ef) => ef.name === f.name),
-                    primaryKey: f.name === pk.name,
-                })),
-            },
-        });
-    }
-    for (const op of customOperations) {
-        const kebab = (0, komoji_1.toKebabCase)(op.name);
-        const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
-        const props = {};
-        const required = [];
-        for (const a of flat) {
-            props[a.flag] = {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(a.type),
-                description: a.description || a.flag,
-            };
-            if (a.required) {
-                required.push(a.flag);
-            }
-        }
-        tools.push({
-            name: `${toolName}_${kebab}`,
-            description: op.description || op.name,
-            inputSchema: {
-                type: 'object',
-                properties: props,
-                ...(required.length > 0 ? { required } : {}),
-            },
-        });
-    }
-    return tools;
-}
 function generateSkills(tables, customOperations, toolName, targetName, registry) {
     const files = [];
     const skillName = `cli-${targetName}`;
@@ -560,6 +338,12 @@ function generateSkills(tables, customOperations, toolName, targetName, registry
                 description: skillSpecialDesc,
                 usage: [
                     `${toolName} ${kebab} list`,
+                    `${toolName} ${kebab} list --where.<field>.<op> <value> --orderBy <values>`,
+                    `${toolName} ${kebab} list --limit 10 --after <cursor>`,
+                    `${toolName} ${kebab} find-first --where.<field>.<op> <value>`,
+                    ...(skillSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding')
+                        ? [`${toolName} ${kebab} search <query>`]
+                        : []),
                     `${toolName} ${kebab} get --${pk.name} <${(0, docs_utils_1.cleanTypeName)(pk.gqlType)}>`,
                     `${toolName} ${kebab} create ${createFlags}`,
                     `${toolName} ${kebab} update --${pk.name} <${(0, docs_utils_1.cleanTypeName)(pk.gqlType)}> ${editableFields.map((f) => `[--${f.name} <${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)}>]`).join(' ')}`,
@@ -567,9 +351,35 @@ function generateSkills(tables, customOperations, toolName, targetName, registry
                 ],
                 examples: [
                     {
-                        description: `List all ${singularName} records`,
+                        description: `List ${singularName} records`,
                         code: [`${toolName} ${kebab} list`],
                     },
+                    {
+                        description: `List ${singularName} records with pagination`,
+                        code: [`${toolName} ${kebab} list --limit 10 --offset 0`],
+                    },
+                    {
+                        description: `List ${singularName} records with cursor pagination`,
+                        code: [`${toolName} ${kebab} list --limit 10 --after <cursor>`],
+                    },
+                    {
+                        description: `Find first matching ${singularName}`,
+                        code: [`${toolName} ${kebab} find-first --where.${pk.name}.equalTo <value>`],
+                    },
+                    {
+                        description: `List ${singularName} records with field selection`,
+                        code: [`${toolName} ${kebab} list --fields id,${pk.name}`],
+                    },
+                    {
+                        description: `List ${singularName} records with filtering and ordering`,
+                        code: [`${toolName} ${kebab} list --where.${pk.name}.equalTo <value> --orderBy ${pk.name.replace(/([A-Z])/g, '_$1').toUpperCase()}_ASC`],
+                    },
+                    ...(skillSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding')
+                        ? [{
+                                description: `Search ${singularName} records`,
+                                code: [`${toolName} ${kebab} search "query text" --limit 10 --fields id,searchScore`],
+                            }]
+                        : []),
                     {
                         description: `Create a ${singularName}`,
                         code: [
@@ -824,6 +634,12 @@ function generateMultiTargetReadme(input) {
             lines.push('| Subcommand | Description |');
             lines.push('|------------|-------------|');
             lines.push(`| \`list\` | List all ${singularName} records |`);
+            lines.push(`| \`find-first\` | Find first matching ${singularName} record |`);
+            const mtReadmeSpecialGroups = (0, docs_utils_1.categorizeSpecialFields)(table, registry);
+            const mtReadmeHasSearch = mtReadmeSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding');
+            if (mtReadmeHasSearch) {
+                lines.push(`| \`search <query>\` | Search ${singularName} records |`);
+            }
             lines.push(`| \`get\` | Get a ${singularName} by ${pk.name} |`);
             lines.push(`| \`create\` | Create a new ${singularName} |`);
             lines.push(`| \`update\` | Update an existing ${singularName} |`);
@@ -961,248 +777,6 @@ function generateMultiTargetAgentsDocs(input) {
         content: lines.join('\n'),
     };
 }
-function getMultiTargetCliMcpTools(input) {
-    const { toolName, builtinNames, targets, registry } = input;
-    const tools = [];
-    const contextEndpointProps = {
-        name: { type: 'string', description: 'Context name' },
-    };
-    for (const tgt of targets) {
-        contextEndpointProps[`${tgt.name}_endpoint`] = {
-            type: 'string',
-            description: `${tgt.name} GraphQL endpoint (default: ${tgt.endpoint})`,
-        };
-    }
-    tools.push({
-        name: `${toolName}_${builtinNames.context}_create`,
-        description: 'Create a named API context with per-target endpoint overrides',
-        inputSchema: {
-            type: 'object',
-            properties: contextEndpointProps,
-            required: ['name'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.context}_list`,
-        description: 'List all configured API contexts',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.context}_use`,
-        description: 'Set the active API context (switches all targets at once)',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Context name to activate' },
-            },
-            required: ['name'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.context}_current`,
-        description: 'Show the currently active API context',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.context}_delete`,
-        description: 'Delete an API context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Context name to delete' },
-            },
-            required: ['name'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.auth}_set_token`,
-        description: 'Store a bearer token for the current context (shared across all targets)',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                token: { type: 'string', description: 'Bearer token value' },
-            },
-            required: ['token'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.auth}_status`,
-        description: 'Show authentication status for all contexts',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.auth}_logout`,
-        description: 'Remove credentials for the current context',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.config}_get`,
-        description: 'Get a config variable value for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Variable name' },
-            },
-            required: ['key'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.config}_set`,
-        description: 'Set a config variable value for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Variable name' },
-                value: { type: 'string', description: 'Variable value' },
-            },
-            required: ['key', 'value'],
-        },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.config}_list`,
-        description: 'List all config variables for the current context',
-        inputSchema: { type: 'object', properties: {} },
-    });
-    tools.push({
-        name: `${toolName}_${builtinNames.config}_delete`,
-        description: 'Delete a config variable for the current context',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Variable name to delete' },
-            },
-            required: ['key'],
-        },
-    });
-    for (const tgt of targets) {
-        for (const table of tgt.tables) {
-            const { singularName } = (0, utils_1.getTableNames)(table);
-            const kebab = (0, komoji_1.toKebabCase)(singularName);
-            const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
-            const scalarFields = (0, utils_1.getScalarFields)(table);
-            const editableFields = (0, docs_utils_1.getEditableFields)(table, registry);
-            const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
-            const requiredCreateFieldNames = editableFields
-                .filter((f) => !defaultFields.has(f.name))
-                .map((f) => f.name);
-            const prefix = `${toolName}_${tgt.name}_${kebab}`;
-            tools.push({
-                name: `${prefix}_list`,
-                description: `List all ${table.name} records (${tgt.name} target)`,
-                inputSchema: { type: 'object', properties: {} },
-            });
-            tools.push({
-                name: `${prefix}_get`,
-                description: `Get a single ${table.name} record by ${pk.name} (${tgt.name} target)`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        [pk.name]: {
-                            type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(pk.gqlType),
-                            description: `${table.name} ${pk.name}`,
-                        },
-                    },
-                    required: [pk.name],
-                },
-            });
-            const createProps = {};
-            for (const f of editableFields) {
-                createProps[f.name] = {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
-                    description: `${table.name} ${f.name}`,
-                };
-            }
-            tools.push({
-                name: `${prefix}_create`,
-                description: `Create a new ${table.name} record (${tgt.name} target)`,
-                inputSchema: {
-                    type: 'object',
-                    properties: createProps,
-                    ...(requiredCreateFieldNames.length > 0 ? { required: requiredCreateFieldNames } : {}),
-                },
-            });
-            const updateProps = {
-                [pk.name]: {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(pk.gqlType),
-                    description: `${table.name} ${pk.name}`,
-                },
-            };
-            for (const f of editableFields) {
-                updateProps[f.name] = {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
-                    description: `${table.name} ${f.name}`,
-                };
-            }
-            tools.push({
-                name: `${prefix}_update`,
-                description: `Update an existing ${table.name} record (${tgt.name} target)`,
-                inputSchema: {
-                    type: 'object',
-                    properties: updateProps,
-                    required: [pk.name],
-                },
-            });
-            tools.push({
-                name: `${prefix}_delete`,
-                description: `Delete a ${table.name} record by ${pk.name} (${tgt.name} target)`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        [pk.name]: {
-                            type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(pk.gqlType),
-                            description: `${table.name} ${pk.name}`,
-                        },
-                    },
-                    required: [pk.name],
-                },
-            });
-            tools.push({
-                name: `${prefix}_fields`,
-                description: `List available fields for ${table.name} (${tgt.name} target)`,
-                inputSchema: { type: 'object', properties: {} },
-                _meta: {
-                    fields: scalarFields.map((f) => ({
-                        name: f.name,
-                        type: (0, docs_utils_1.cleanTypeName)(f.type.gqlType),
-                        editable: editableFields.some((ef) => ef.name === f.name),
-                        primaryKey: f.name === pk.name,
-                    })),
-                },
-            });
-        }
-        for (const op of tgt.customOperations) {
-            const kebab = (0, komoji_1.toKebabCase)(op.name);
-            const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
-            const props = {};
-            const required = [];
-            for (const a of flat) {
-                props[a.flag] = {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(a.type),
-                    description: a.description || a.flag,
-                };
-                if (a.required) {
-                    required.push(a.flag);
-                }
-            }
-            if (tgt.isAuthTarget && op.kind === 'mutation') {
-                props['save_token'] = {
-                    type: 'boolean',
-                    description: 'Auto-save returned token to credentials',
-                };
-            }
-            tools.push({
-                name: `${toolName}_${tgt.name}_${kebab}`,
-                description: `${op.description || op.name} (${tgt.name} target)`,
-                inputSchema: {
-                    type: 'object',
-                    properties: props,
-                    ...(required.length > 0 ? { required } : {}),
-                },
-            });
-        }
-    }
-    return tools;
-}
 function generateMultiTargetSkills(input) {
     const { toolName, builtinNames, targets, registry } = input;
     const files = [];
@@ -1362,6 +936,12 @@ function generateMultiTargetSkills(input) {
                     description: mtSkillSpecialDesc,
                     usage: [
                         `${toolName} ${cmd} list`,
+                        `${toolName} ${cmd} list --where.<field>.<op> <value> --orderBy <values>`,
+                        `${toolName} ${cmd} list --limit 10 --after <cursor>`,
+                        `${toolName} ${cmd} find-first --where.<field>.<op> <value>`,
+                        ...(mtSkillSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding')
+                            ? [`${toolName} ${cmd} search <query>`]
+                            : []),
                         `${toolName} ${cmd} get --${pk.name} <${(0, docs_utils_1.cleanTypeName)(pk.gqlType)}>`,
                         `${toolName} ${cmd} create ${createFlags}`,
                         `${toolName} ${cmd} update --${pk.name} <${(0, docs_utils_1.cleanTypeName)(pk.gqlType)}> ${editableFields.map((f) => `[--${f.name} <${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)}>]`).join(' ')}`,
@@ -1369,9 +949,31 @@ function generateMultiTargetSkills(input) {
                     ],
                     examples: [
                         {
-                            description: `List all ${singularName} records`,
+                            description: `List ${singularName} records`,
                             code: [`${toolName} ${cmd} list`],
                         },
+                        {
+                            description: `List ${singularName} records with pagination`,
+                            code: [`${toolName} ${cmd} list --limit 10 --offset 0`],
+                        },
+                        {
+                            description: `List ${singularName} records with cursor pagination`,
+                            code: [`${toolName} ${cmd} list --limit 10 --after <cursor>`],
+                        },
+                        {
+                            description: `Find first matching ${singularName}`,
+                            code: [`${toolName} ${cmd} find-first --where.${pk.name}.equalTo <value>`],
+                        },
+                        {
+                            description: `List ${singularName} records with filtering and ordering`,
+                            code: [`${toolName} ${cmd} list --where.${pk.name}.equalTo <value> --orderBy ${pk.name.replace(/([A-Z])/g, '_$1').toUpperCase()}_ASC`],
+                        },
+                        ...(mtSkillSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding')
+                            ? [{
+                                    description: `Search ${singularName} records`,
+                                    code: [`${toolName} ${cmd} search "query text" --limit 10 --fields id,searchScore`],
+                                }]
+                            : []),
                         {
                             description: `Create a ${singularName}`,
                             code: [

package/core/codegen/cli/index.d.ts

@@ -58,9 +58,9 @@ export { generateConfigCommand } from './config-command-generator';
 export { generateHelpersFile } from './helpers-generator';
 export type { HelpersGeneratorInput } from './helpers-generator';
 export { generateContextCommand, generateAuthCommand, generateMultiTargetContextCommand, generateAuthCommandWithName, } from './infra-generator';
-export { generateReadme, generateAgentsDocs, getCliMcpTools, generateSkills, generateMultiTargetReadme, generateMultiTargetAgentsDocs, getMultiTargetCliMcpTools, generateMultiTargetSkills, } from './docs-generator';
+export { generateReadme, generateAgentsDocs, generateSkills, generateMultiTargetReadme, generateMultiTargetAgentsDocs, generateMultiTargetSkills, } from './docs-generator';
 export type { MultiTargetDocsInput } from './docs-generator';
 export { resolveDocsConfig } from '../docs-utils';
-export type { GeneratedDocFile, McpTool } from '../docs-utils';
+export type { GeneratedDocFile } from '../docs-utils';
 export { generateUtilsFile, generateEntryPointFile } from './utils-generator';
 export type { GeneratedFile, MultiTargetExecutorInput } from './executor-generator';

package/core/codegen/cli/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateEntryPointFile = exports.generateUtilsFile = exports.resolveDocsConfig = exports.generateMultiTargetSkills = exports.getMultiTargetCliMcpTools = exports.generateMultiTargetAgentsDocs = exports.generateMultiTargetReadme = exports.generateSkills = exports.getCliMcpTools = exports.generateAgentsDocs = exports.generateReadme = exports.generateAuthCommandWithName = exports.generateMultiTargetContextCommand = exports.generateAuthCommand = exports.generateContextCommand = exports.generateHelpersFile = exports.generateConfigCommand = exports.generateMultiTargetCommandMap = exports.generateCommandMap = exports.generateCustomCommand = exports.generateTableCommand = exports.generateMultiTargetExecutorFile = exports.generateExecutorFile = void 0;
+exports.generateEntryPointFile = exports.generateUtilsFile = exports.resolveDocsConfig = exports.generateMultiTargetSkills = exports.generateMultiTargetAgentsDocs = exports.generateMultiTargetReadme = exports.generateSkills = exports.generateAgentsDocs = exports.generateReadme = exports.generateAuthCommandWithName = exports.generateMultiTargetContextCommand = exports.generateAuthCommand = exports.generateContextCommand = exports.generateHelpersFile = exports.generateConfigCommand = exports.generateMultiTargetCommandMap = exports.generateCommandMap = exports.generateCustomCommand = exports.generateTableCommand = exports.generateMultiTargetExecutorFile = exports.generateExecutorFile = void 0;
 exports.generateCli = generateCli;
 exports.resolveBuiltinNames = resolveBuiltinNames;
 exports.generateMultiTargetCli = generateMultiTargetCli;
@@ -192,11 +192,9 @@ Object.defineProperty(exports, "generateAuthCommandWithName", { enumerable: true
 var docs_generator_1 = require("./docs-generator");
 Object.defineProperty(exports, "generateReadme", { enumerable: true, get: function () { return docs_generator_1.generateReadme; } });
 Object.defineProperty(exports, "generateAgentsDocs", { enumerable: true, get: function () { return docs_generator_1.generateAgentsDocs; } });
-Object.defineProperty(exports, "getCliMcpTools", { enumerable: true, get: function () { return docs_generator_1.getCliMcpTools; } });
 Object.defineProperty(exports, "generateSkills", { enumerable: true, get: function () { return docs_generator_1.generateSkills; } });
 Object.defineProperty(exports, "generateMultiTargetReadme", { enumerable: true, get: function () { return docs_generator_1.generateMultiTargetReadme; } });
 Object.defineProperty(exports, "generateMultiTargetAgentsDocs", { enumerable: true, get: function () { return docs_generator_1.generateMultiTargetAgentsDocs; } });
-Object.defineProperty(exports, "getMultiTargetCliMcpTools", { enumerable: true, get: function () { return docs_generator_1.getMultiTargetCliMcpTools; } });
 Object.defineProperty(exports, "generateMultiTargetSkills", { enumerable: true, get: function () { return docs_generator_1.generateMultiTargetSkills; } });
 var docs_utils_1 = require("../docs-utils");
 Object.defineProperty(exports, "resolveDocsConfig", { enumerable: true, get: function () { return docs_utils_1.resolveDocsConfig; } });