Education Data MCP Server

Instructions

Implementation Reference

• src/index.ts:380-475 (handler)

  Handler implementation for the get_education_data_summary tool within the CallToolRequestSchema switch statement. It validates input parameters, constructs the API URL for the summaries endpoint (e.g., /level/source/topic/summaries or with subtopic), appends query parameters (stat, var, by, filters, mode=R), fetches data using axios, and returns JSON-formatted results or 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, provided in the ListToolsRequestSchema handler. Specifies the structure, properties, descriptions, and required fields for tool arguments.
  { 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)

  The ListToolsRequestSchema handler registers the get_education_data_summary tool by including it in the returned tools list, along with its schema and description.
  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"] } } ] }; });