MCP Power - Knowledge Search Server

Instructions

Implementation Reference

• src/tools/listDatasets.ts:61-197 (handler)

  Main handler function that executes the knowledge.listDatasets tool: validates input, retrieves datasets from registry, formats list with metadata and statistics, handles errors.

  export async function handleListDatasets(
    args: unknown
  ): Promise<{
    content: Array<{ type: string; text: string }>;
    isError?: boolean;
  }> {
    const startTime = Date.now();
    
    try {
      // Validate arguments
      const parseResult = ListDatasetsArgsSchema.safeParse(args);
      if (!parseResult.success) {
        logger.warn(
          { errors: parseResult.error.errors, args },
          'Invalid arguments for knowledge.listDatasets'
        );
        return {
          content: [
            {
              type: 'text',
              text: `Invalid arguments: ${parseResult.error.errors
                .map((e) => `${e.path.join('.')}: ${e.message}`)
                .join(', ')}`,
            },
          ],
          isError: true,
        };
      }
  
      const { includeErrors } = parseResult.data;
  
      logger.info({ includeErrors }, 'Listing datasets');
  
      // Get dataset registry
      const registry = getDatasetRegistry();
  
      // Get ready datasets
      const readyDatasets = registry.listReady();
      const results: DatasetListItem[] = readyDatasets.map((dataset) => ({
        id: dataset.id,
        name: dataset.name,
        description: dataset.description || '',
        status: 'ready' as const,
      }));
  
      // Optionally include datasets with errors
      if (includeErrors) {
        const errors = registry.getErrors();
        for (const error of errors) {
          // Extract dataset ID from manifest path (e.g., /path/to/datasets/my-dataset/manifest.json -> my-dataset)
          const pathParts = error.manifestPath.split('/');
          const datasetId = pathParts[pathParts.length - 2] || 'unknown';
          
          results.push({
            id: datasetId,
            name: datasetId, // Use ID as name fallback
            description: 'Failed to load dataset',
            status: 'error' as const,
            error: error.error,
          });
        }
      }
  
      // Calculate statistics
      const totalCount = results.length;
      const readyCount = results.filter((d) => d.status === 'ready').length;
      const errorCount = results.filter((d) => d.status === 'error').length;
  
      // Format response text
      let responseText = `Found ${totalCount} dataset${totalCount !== 1 ? 's' : ''}`;
      if (includeErrors && errorCount > 0) {
        responseText += ` (${readyCount} ready, ${errorCount} with errors)`;
      }
      responseText += ':\n\n';
  
      // Add dataset details
      for (const dataset of results.sort((a, b) => a.id.localeCompare(b.id))) {
        responseText += `**${dataset.id}**\n`;
        responseText += `  Name: ${dataset.name}\n`;
        responseText += `  Description: ${dataset.description}\n`;
        responseText += `  Status: ${dataset.status}\n`;
        if (dataset.error) {
          responseText += `  Error: ${dataset.error}\n`;
        }
        responseText += '\n';
      }
  
      // Add summary footer
      const duration = Date.now() - startTime;
      responseText += `---\n`;
      responseText += `Total: ${totalCount} datasets | Ready: ${readyCount}`;
      if (includeErrors && errorCount > 0) {
        responseText += ` | Errors: ${errorCount}`;
      }
      responseText += ` | Retrieved in ${duration}ms`;
  
      logger.info(
        {
          totalCount,
          readyCount,
          errorCount,
          duration,
        },
        'Listed datasets successfully'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: responseText,
          },
        ],
      };
    } catch (error) {
      const duration = Date.now() - startTime;
      logger.error(
        {
          error: error instanceof Error ? error.message : String(error),
          duration,
        },
        'Failed to list datasets'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: `Error listing datasets: ${
              error instanceof Error ? error.message : 'Unknown error'
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/listDatasets.ts:19-24 (schema)

  Zod schema defining the input arguments for the tool: optional 'includeErrors' boolean to show failed datasets.

  export const ListDatasetsArgsSchema = z
    .object({
      /** Include datasets that failed to load (for diagnostics) */
      includeErrors: z.boolean().optional().default(false),
    })
    .strict();

• src/server.ts:136-143 (registration)

  Tool registration in the ListToolsRequestHandler: defines name, description, and basic input schema.

  {
    name: 'knowledge.listDatasets',
    description: 'List all registered knowledge datasets available for searching',
    inputSchema: {
      type: 'object',
      properties: {}
    }
  }

• src/server.ts:159-160 (registration)

  Handler dispatch in CallToolRequestHandler switch statement: routes 'knowledge.listDatasets' calls to the handler function.

  case 'knowledge.listDatasets':
    return await handleListDatasets(args);

• src/server.ts:12-12 (registration)

  Import of the handleListDatasets function for use in server tool handling.

  import { handleListDatasets } from './tools/listDatasets.js';