@gsb-core/mcp-docs/src/docs/queryEntityDefs.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the queryEntityDefs operation
 */

/**
 * Returns documentation for the queryEntityDefs operation
 * @return {string} markdown documentation
 */
export function queryEntityDefsDocs(): string {
  return `
# QueryEntityDefs Operation

## General Description

The \`queryEntityDefs\` operation retrieves a paginated list of entity definitions.

## Detailed Description

This operation allows you to fetch multiple entity definitions with pagination support. It's useful for discovering available entity types, building data dictionaries, or creating administrative interfaces that manage entity definitions. The results are paginated to handle large numbers of entity definitions efficiently.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| searchTerm | string | Yes | The search term for entity definitions. |Can be left empty string to retrieve all entity definitions.
| page | number | Yes | The page number for pagination (0-based). |
| pageSize | number | Yes | The number of items per page. |
| includeSystem | boolean | No | Whether to include system entity definitions. Default is false. |
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "data": {
        "items": [
            // Array of entity definition objects
            {
                "id": "string",
                "name": "string",
                "displayName": "string",
                "description": "string",
                // Additional entity definition attributes
            }
        ],
        "totalCount": number,  // Total number of entity definitions
        "page": number,        // Current page number
        "pageSize": number     // Number of items per page
    }
}
\`\`\`

### Error Response

\`\`\`json
{
    "success": false,
    "error": "Error message describing what went wrong"
}
\`\`\`

## Example Usage

### Get First Page of Entity Definitions

\`\`\`typescript
const result = await queryEntityDefs({
  searchTerm: "",
  page: 0,
  pageSize: 10,
  token: "your-auth-token"
});

if (result.success) {
  const entityDefs = result.data.items;
  const totalCount = result.data.totalCount;
  console.log(\`Found \${totalCount} entity definitions, showing \${entityDefs.length}\`);
  
  // Display entity definition names
  entityDefs.forEach(def => {
    console.log(\`- \${def.displayName} (\${def.name}): \${def.description || 'No description'}\`);
  });
} else {
  console.error("Error:", result.error);
}
\`\`\`

## Additional Information

- The queryEntityDefs operation returns a paginated list of entity definitions.
- Use the page and pageSize parameters to navigate through the results.
- The response includes the total count of entity definitions, which can be used to calculate the total number of pages.
- Each entity definition in the results includes basic information but may not include all details.
- For getting complete details of a specific entity definition, use the getEntityDef operation.
- Entity definitions are typically returned sorted alphabetically by name.
- Access permissions are enforced based on the provided token.
- The user will only see entity definitions they have permission to access.
- For creating or modifying entity definitions, use the createEntityDef and updateEntityDef operations.
`;
}

/**
 * Returns a brief summary of the queryEntityDefs operation.
 * @return {string} A short description of the function.
 */
export function queryEntityDefsSummary(): string {
  return `
**Purpose**: Retrieves paginated list of entity definitions (schemas).

**When to use**:
- Discovering available entity types
- Building data dictionaries
- Creating schema management interfaces

**Inputs**:
- searchTerm: Filter entity definitions (empty for all)
- page: Page number (0-based)
- pageSize: Items per page
- includeSystem: Whether to include system entity definitions
- token (optional)
- tenantCode (optional)

**Returns**: List of entity definitions with pagination details.
`;
}

export default queryEntityDefsDocs;