get_education_data_summary
Retrieve aggregated education statistics from the Urban Institute's API to analyze data on schools, districts, and universities by applying filters and grouping variables.
Instructions
Retrieve aggregated education data from the Urban Institute's Education Data API
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | API data level to query | |
| source | Yes | API data source to query | |
| topic | Yes | API data topic to query | |
| subtopic | No | Optional additional parameters (only applicable to certain endpoints) | |
| stat | Yes | Summary statistic to calculate (e.g., 'sum', 'avg', 'count', 'median') | |
| var | Yes | Variable to be summarized | |
| by | Yes | Variables to group results by | |
| filters | No | Optional query filters |
Implementation Reference
- src/index.ts:380-475 (handler)Handler for the 'get_education_data_summary' tool. Parses arguments, validates required params (level, source, topic, stat, var, by), constructs API URL with /summaries endpoint, adds query parameters for stat, var, by, filters, and makes GET request to Education Data API. Handles errors with appropriate MCP errors.
case "get_education_data_summary": { const args = request.params.arguments || {}; const level = String(args.level || ''); const source = String(args.source || ''); const topic = String(args.topic || ''); const subtopic = args.subtopic ? String(args.subtopic) : undefined; const stat = String(args.stat || ''); const variable = String(args.var || ''); const by = args.by || []; const filters = args.filters || {}; if (!level || !source || !topic || !stat || !variable || !by) { throw new McpError( ErrorCode.InvalidParams, "Missing required parameters: level, source, topic, stat, var, and by are required" ); } try { // Construct the API URL let url = `${API_BASE_URL}/${level}/${source}/${topic}`; // Add subtopic if provided if (subtopic) { url += `/${subtopic}`; } // Add summaries endpoint url += "/summaries"; // Add query parameters const queryParams = new URLSearchParams(); queryParams.append("stat", stat); queryParams.append("var", variable); if (Array.isArray(by)) { queryParams.append("by", by.join(",")); } else { queryParams.append("by", String(by)); } // Add filters if (filters && typeof filters === "object") { Object.entries(filters).forEach(([key, value]) => { if (Array.isArray(value)) { queryParams.append(key, value.join(",")); } else { queryParams.append(key, String(value)); } }); } // Add mode=R to match the R package behavior queryParams.append("mode", "R"); // Make the API request const response = await axios.get(`${url}?${queryParams.toString()}`); // Return the results return { content: [ { type: "text", text: JSON.stringify(response.data.results || response.data, null, 2) } ] }; } catch (error) { if (axios.isAxiosError(error)) { const statusCode = error.response?.status; const message = error.response?.data?.message || error.message; if (statusCode === 404) { throw new McpError( ErrorCode.InvalidRequest, `Summary endpoint not found: ${level}/${source}/${topic}${subtopic ? `/${subtopic}` : ''}/summaries` ); } else if (statusCode === 400) { throw new McpError( ErrorCode.InvalidParams, `API error: ${message}` ); } throw new McpError( ErrorCode.InternalError, `API error (${statusCode}): ${message}` ); } throw new McpError( ErrorCode.InternalError, `Error: ${error instanceof Error ? error.message : String(error)}` ); } } - src/index.ts:238-282 (schema)Input schema definition for the 'get_education_data_summary' tool, including properties for level, source, topic, subtopic, stat, var, by, filters, with required fields specified.
{ name: "get_education_data_summary", description: "Retrieve aggregated education data from the Urban Institute's Education Data API", inputSchema: { type: "object", properties: { level: { type: "string", description: "API data level to query" }, source: { type: "string", description: "API data source to query" }, topic: { type: "string", description: "API data topic to query" }, subtopic: { type: "string", description: "Optional additional parameters (only applicable to certain endpoints)" }, stat: { type: "string", description: "Summary statistic to calculate (e.g., 'sum', 'avg', 'count', 'median')" }, var: { type: "string", description: "Variable to be summarized" }, by: { type: "array", items: { type: "string" }, description: "Variables to group results by" }, filters: { type: "object", description: "Optional query filters" } }, required: ["level", "source", "topic", "stat", "var", "by"] } } - src/index.ts:194-285 (registration)Registration of the 'get_education_data_summary' tool in the list_tools response handler, including its name, description, and input schema.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "get_education_data", description: "Retrieve education data from the Urban Institute's Education Data API", inputSchema: { type: "object", properties: { level: { type: "string", description: "API data level to query (e.g., 'schools', 'school-districts', 'college-university')" }, source: { type: "string", description: "API data source to query (e.g., 'ccd', 'ipeds', 'crdc')" }, topic: { type: "string", description: "API data topic to query (e.g., 'enrollment', 'directory')" }, subtopic: { type: "array", items: { type: "string" }, description: "Optional list of grouping parameters (e.g., ['race', 'sex'])" }, filters: { type: "object", description: "Optional query filters (e.g., {year: 2008, grade: [9,10,11,12]})" }, add_labels: { type: "boolean", description: "Add variable labels when applicable (default: false)" }, limit: { type: "number", description: "Limit the number of results (default: 100)" } }, required: ["level", "source", "topic"] } }, { name: "get_education_data_summary", description: "Retrieve aggregated education data from the Urban Institute's Education Data API", inputSchema: { type: "object", properties: { level: { type: "string", description: "API data level to query" }, source: { type: "string", description: "API data source to query" }, topic: { type: "string", description: "API data topic to query" }, subtopic: { type: "string", description: "Optional additional parameters (only applicable to certain endpoints)" }, stat: { type: "string", description: "Summary statistic to calculate (e.g., 'sum', 'avg', 'count', 'median')" }, var: { type: "string", description: "Variable to be summarized" }, by: { type: "array", items: { type: "string" }, description: "Variables to group results by" }, filters: { type: "object", description: "Optional query filters" } }, required: ["level", "source", "topic", "stat", "var", "by"] } } ] }; });