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; }