opengov-mcp-server

Instructions

Implementation Reference

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

  Primary handler function for the 'get_data' tool. It parses the input parameters, validates requirements for certain operations, and dispatches to specialized sub-handlers based on the 'type' field (catalog, categories, tags, dataset-metadata, column-info, data-access, site-metrics).

  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:253-337 (schema)

  Detailed input schema for the 'get_data' tool, defining all parameters including required 'type' enum for operation selection, optional domain, datasetId, various SoQL query parameters for data-access, pagination (limit/offset), and descriptions for each.

  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/index.ts:49-52 (registration)

  Dispatch/registration point in the MCP CallToolRequest handler where tool calls named 'get_data' are routed to the handleSocrataTool implementation.

  if (name === 'get_data') {
    // Handle the unified data retrieval tool
    result = await handleSocrataTool(args || {});

• src/index.ts:117-120 (registration)

  Registration of the 'get_data' tool (via SOCRATA_TOOLS/enhancedTools) in the MCP ListToolsRequest handler, making it discoverable to clients.

  // Update the tools handler
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: enhancedTools,
  }));

• src/tools/socrata-tools.ts:178-231 (helper)

  Key helper function invoked by 'get_data' handler for 'data-access' type, responsible for querying and retrieving actual data records from Socrata datasets using SoQL parameters.

  async function handleDataAccess(params: { 
    datasetId: string; 
    domain?: string;
    query?: string;
    limit?: number;
    offset?: number;
    select?: string;
    where?: string;
    order?: string;
    group?: string;
    having?: string;
    q?: string;
  }): Promise<Record<string, unknown>[]> {
    const { 
      datasetId, 
      domain = getDefaultDomain(),
      query,
      limit = 10,
      offset = 0,
      select,
      where,
      order,
      group,
      having,
      q
    } = params;
    
    const apiParams: Record<string, unknown> = {
      $limit: limit,
      $offset: offset,
    };
    
    // Handle comprehensive query parameter if provided
    if (query) {
      apiParams.$query = query;
    } else {
      // Otherwise handle individual SoQL parameters
      if (select) apiParams.$select = select;
      if (where) apiParams.$where = where;
      if (order) apiParams.$order = order;
      if (group) apiParams.$group = group;
      if (having) apiParams.$having = having;
      if (q) apiParams.$q = q;
    }
    
    const baseUrl = `https://${domain}`;
    const response = await fetchFromSocrataApi<Record<string, unknown>[]>(
      `/resource/${datasetId}.json`, 
      apiParams,
      baseUrl
    );
    
    return response;
  }