get_data

Instructions

Implementation Reference

• src/index.ts:50-55 (registration)

  Registration/call-site: Routes the 'get_data' tool call to handleSocrataTool in the CallToolRequestHandler

  if (name === 'get_data') {
    // Handle the unified data retrieval tool
    result = await handleSocrataTool(args || {});
  } else {
    throw new Error(`Unknown tool: ${name}`);
  }

• src/tools/socrata-tools.ts:341-390 (handler)

  Main handler for the get_data tool - routes to sub-handlers (catalog, categories, tags, dataset-metadata, column-info, data-access, site-metrics) based on the 'type' parameter

  export async function handleSocrataTool(params: Record<string, unknown>): Promise<unknown> {
    const { type } = params;
    
    switch (type) {
      case 'catalog':
        return handleCatalog(params as { query?: string; domain?: string; limit?: number; offset?: number });
      case 'categories':
        return handleCategories(params as { domain?: string });
      case 'tags':
        return handleTags(params as { domain?: string });
      case 'dataset-metadata':
        // Validate required parameters
        if (!params.datasetId) {
          throw new Error('datasetId is required for dataset-metadata operation');
        }
        return handleDatasetMetadata(params as { datasetId: string; domain?: string });
      case 'column-info':
        // Validate required parameters
        if (!params.datasetId) {
          throw new Error('datasetId is required for column-info operation');
        }
        return handleColumnInfo(params as { datasetId: string; domain?: string });
      case 'data-access':
        // Validate required parameters
        if (!params.datasetId) {
          throw new Error('datasetId is required for data-access operation');
        }
        // Map soqlQuery to query for consistency with the handler
        if (params.soqlQuery) {
          params.query = params.soqlQuery;
        }
        return handleDataAccess(params as { 
          datasetId: string; 
          domain?: string; 
          query?: string; 
          limit?: number; 
          offset?: number;
          select?: string;
          where?: string;
          order?: string;
          group?: string;
          having?: string;
          q?: string;
        });
      case 'site-metrics':
        return handleSiteMetrics(params as { domain?: string });
      default:
        throw new Error(`Unknown operation type: ${type}`);
    }
  }

• src/tools/socrata-tools.ts:250-338 (schema)

  Schema/Tool definition for 'get_data' - defines the unified tool with all input parameters

  export const UNIFIED_SOCRATA_TOOL: Tool = {
    name: 'get_data',
    description: 'Access data and metadata to learn more about the city and its underlying information.',
    inputSchema: {
      type: 'object',
      properties: {
        type: {
          type: 'string',
          enum: ['catalog', 'categories', 'tags', 'dataset-metadata', 'column-info', 'data-access', 'site-metrics'],
          description: 'The type of operation to perform:' +
            '\n- catalog: List datasets with optional search' +
            '\n- categories: List all dataset categories' + 
            '\n- tags: List all dataset tags' +
            '\n- dataset-metadata: Get detailed metadata for a specific dataset' +
            '\n- column-info: Get column details for a specific dataset' +
            '\n- data-access: Access records from a dataset (with query support)' +
            '\n- site-metrics: Get portal-wide statistics',
        },
        domain: {
          type: 'string',
          description: 'Optional domain (hostname only, without protocol). Used with all operation types.',
        },
        // Search and query parameters
        query: {
          type: 'string',
          description: 'Search or query string with different uses depending on operation type:' +
            '\n- For type=catalog: Search query to filter datasets' +
            '\n- For type=data-access: SoQL query string for complex data filtering',
        },
        // Dataset specific parameters
        datasetId: {
          type: 'string',
          description: 'Dataset identifier required for the following operations:' +
            '\n- For type=dataset-metadata: Get dataset details' +
            '\n- For type=column-info: Get column information' +
            '\n- For type=data-access: Specify which dataset to query (e.g., 6zsd-86xi)',
        },
        // Data access specific parameters
        soqlQuery: {
          type: 'string',
          description: 'For type=data-access only. Optional SoQL query string for filtering data.' +
            '\nThis is an alias for the query parameter and takes precedence if both are provided.',
        },
        // Additional SoQL parameters for data-access
        select: {
          type: 'string',
          description: 'For type=data-access only. Specifies which columns to return in the result set.',
        },
        where: {
          type: 'string',
          description: 'For type=data-access only. Filters the rows to be returned (e.g., "magnitude > 3.0").',
        },
        order: {
          type: 'string',
          description: 'For type=data-access only. Orders the results based on specified columns (e.g., "date DESC").',
        },
        group: {
          type: 'string',
          description: 'For type=data-access only. Groups results for aggregate functions.',
        },
        having: {
          type: 'string',
          description: 'For type=data-access only. Filters for grouped results, similar to where but for grouped data.',
        },
        // Full-text search parameter
        q: {
          type: 'string',
          description: 'For type=data-access only. Full text search parameter for free-text searching across the dataset.',
        },
        // Pagination parameters
        limit: {
          type: 'number',
          description: 'Maximum number of results to return:' +
            '\n- For type=catalog: Limits dataset results' +
            '\n- For type=data-access: Limits data records returned',
          default: 10,
        },
        offset: {
          type: 'number',
          description: 'Number of results to skip for pagination:' +
            '\n- For type=catalog: Skips dataset results' +
            '\n- For type=data-access: Skips data records for pagination',
          default: 0,
        },
      },
      required: ['type'],
      additionalProperties: false,
    },
  };

• src/tools/socrata-tools.ts:15-41 (helper)

  Helper: handleCatalog - sub-handler for the 'catalog' operation type (list datasets with optional search)

  async function handleCatalog(params: { 
    query?: string; 
    domain?: string;
    limit?: number; 
    offset?: number; 
  }): Promise<DatasetMetadata[]> {
    const { query, domain = getDefaultDomain(), limit = 10, offset = 0 } = params;
    
    const apiParams: Record<string, unknown> = {
      limit,
      offset,
      search_context: domain // Add search_context parameter with the domain
    };
    
    if (query) {
      apiParams.q = query;
    }
  
    const baseUrl = `https://${domain}`;
    const response = await fetchFromSocrataApi<{ results: DatasetMetadata[] }>(
      '/api/catalog/v1', 
      apiParams,
      baseUrl
    );
    
    return response.results;
  }

• src/tools/socrata-tools.ts:234-247 (helper)

  Helper: handleSiteMetrics - sub-handler for the 'site-metrics' operation type (get portal-wide statistics)

  async function handleSiteMetrics(params: { 
    domain?: string; 
  }): Promise<PortalMetrics> {
    const { domain = getDefaultDomain() } = params;
    
    const baseUrl = `https://${domain}`;
    const response = await fetchFromSocrataApi<PortalMetrics>(
      '/api/site_metrics.json', 
      {},
      baseUrl
    );
    
    return response;
  }