Kolada MCP Server

Instructions

Implementation Reference

• src/tools/data-tools.ts:157-268 (handler)

  The main execution logic for the get_municipality_kpis tool. Validates municipality, fetches cached KPI catalog, filters by municipality type and operating area, limits results, groups by area, and returns structured JSON with KPIs list and summary.
  handler: async (args: z.infer<typeof getMunicipalityKpisSchema>): Promise<ToolResult> => { const startTime = Date.now(); const { municipality_id, operating_area, limit } = args; logger.toolCall('get_municipality_kpis', { municipality_id, operating_area, limit }); try { // Fetch municipality info to verify it exists and get type const municipalities = await dataCache.getOrFetch( 'municipalities-full', () => koladaClient.fetchAllData<Municipality>('/municipality'), 86400000 ); const municipality = municipalities.find((m) => m.id === municipality_id); if (!municipality) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'NOT_FOUND', message: `Kommun med ID "${municipality_id}" hittades inte`, suggestion: 'Använd search_municipalities för att hitta giltiga kommun-ID:n', }), }, ], isError: true, }; } // Fetch KPI catalog (cached) const allKpis = await dataCache.getOrFetch( 'kpi-catalog-full', () => koladaClient.fetchAllData<KPI>('/kpi'), 86400000 ); // Filter KPIs applicable to this municipality type let applicableKpis = allKpis.filter((k) => { // K = kommun, L = landsting/region, alla = alla typer if (municipality.type === 'K') { return k.municipality_type === 'K' || k.municipality_type === 'alla'; } else if (municipality.type === 'L') { return k.municipality_type === 'L' || k.municipality_type === 'alla'; } return true; }); // Filter by operating area if specified if (operating_area) { const areaLower = operating_area.toLowerCase(); applicableKpis = applicableKpis.filter((k) => k.operating_area?.toLowerCase().includes(areaLower) ); } // Group by operating area for summary const areaGroups: Record<string, number> = {}; for (const kpi of applicableKpis) { const area = kpi.operating_area || 'Övrigt'; areaGroups[area] = (areaGroups[area] || 0) + 1; } // Sort areas by count const sortedAreas = Object.entries(areaGroups) .sort((a, b) => b[1] - a[1]) .map(([name, count]) => ({ name, count })); // Limit results const totalApplicable = applicableKpis.length; const limitedKpis = applicableKpis.slice(0, limit); logger.toolResult('get_municipality_kpis', true, Date.now() - startTime); return { content: [ { type: 'text', text: JSON.stringify( { municipality: { id: municipality.id, name: municipality.title, type: municipality.type === 'K' ? 'Kommun' : 'Region', }, filter: operating_area || 'alla verksamhetsområden', total_applicable_kpis: totalApplicable, shown_kpis: limitedKpis.length, operating_areas_summary: sortedAreas, kpis: limitedKpis.map((k) => ({ id: k.id, title: k.title, operating_area: k.operating_area, is_divided_by_gender: k.is_divided_by_gender, })), next_steps: [ 'Använd get_kpi för detaljer om ett specifikt KPI', 'Använd get_kpi_data för att hämta faktiska värden', 'Filtrera på operating_area för att smalna av resultaten', ], }, null, 2 ), }, ], }; } catch (error) { logger.toolResult('get_municipality_kpis', false, Date.now() - startTime); throw error; } },
• src/tools/data-tools.ts:30-34 (schema)

  Zod input schema defining parameters: municipality_id (required), operating_area (optional filter), limit (1-50, default 20).
  const getMunicipalityKpisSchema = z.object({ municipality_id: z.string().describe('Kommun-ID (4-siffrig kod)'), operating_area: z.string().optional().describe('Filtrera på verksamhetsområde (t.ex. "Utbildning", "Vård"). Använd list_operating_areas för att se tillgängliga områden.'), limit: z.number().min(1).max(50).default(20).describe('Max antal KPIs att returnera (standard: 20, max: 50)'), });
• src/tools/data-tools.ts:153-269 (registration)

  Tool registration as part of the dataTools export object, including description, input schema reference, read-only annotations, and handler function.
  get_municipality_kpis: { description: 'Visa tillgängliga KPIs för en kommun. Filtrera på verksamhetsområde för att hitta relevanta nyckeltal. Snabb och pålitlig - använder cachad KPI-katalog.', inputSchema: getMunicipalityKpisSchema, annotations: READ_ONLY_ANNOTATIONS, handler: async (args: z.infer<typeof getMunicipalityKpisSchema>): Promise<ToolResult> => { const startTime = Date.now(); const { municipality_id, operating_area, limit } = args; logger.toolCall('get_municipality_kpis', { municipality_id, operating_area, limit }); try { // Fetch municipality info to verify it exists and get type const municipalities = await dataCache.getOrFetch( 'municipalities-full', () => koladaClient.fetchAllData<Municipality>('/municipality'), 86400000 ); const municipality = municipalities.find((m) => m.id === municipality_id); if (!municipality) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'NOT_FOUND', message: `Kommun med ID "${municipality_id}" hittades inte`, suggestion: 'Använd search_municipalities för att hitta giltiga kommun-ID:n', }), }, ], isError: true, }; } // Fetch KPI catalog (cached) const allKpis = await dataCache.getOrFetch( 'kpi-catalog-full', () => koladaClient.fetchAllData<KPI>('/kpi'), 86400000 ); // Filter KPIs applicable to this municipality type let applicableKpis = allKpis.filter((k) => { // K = kommun, L = landsting/region, alla = alla typer if (municipality.type === 'K') { return k.municipality_type === 'K' || k.municipality_type === 'alla'; } else if (municipality.type === 'L') { return k.municipality_type === 'L' || k.municipality_type === 'alla'; } return true; }); // Filter by operating area if specified if (operating_area) { const areaLower = operating_area.toLowerCase(); applicableKpis = applicableKpis.filter((k) => k.operating_area?.toLowerCase().includes(areaLower) ); } // Group by operating area for summary const areaGroups: Record<string, number> = {}; for (const kpi of applicableKpis) { const area = kpi.operating_area || 'Övrigt'; areaGroups[area] = (areaGroups[area] || 0) + 1; } // Sort areas by count const sortedAreas = Object.entries(areaGroups) .sort((a, b) => b[1] - a[1]) .map(([name, count]) => ({ name, count })); // Limit results const totalApplicable = applicableKpis.length; const limitedKpis = applicableKpis.slice(0, limit); logger.toolResult('get_municipality_kpis', true, Date.now() - startTime); return { content: [ { type: 'text', text: JSON.stringify( { municipality: { id: municipality.id, name: municipality.title, type: municipality.type === 'K' ? 'Kommun' : 'Region', }, filter: operating_area || 'alla verksamhetsområden', total_applicable_kpis: totalApplicable, shown_kpis: limitedKpis.length, operating_areas_summary: sortedAreas, kpis: limitedKpis.map((k) => ({ id: k.id, title: k.title, operating_area: k.operating_area, is_divided_by_gender: k.is_divided_by_gender, })), next_steps: [ 'Använd get_kpi för detaljer om ett specifikt KPI', 'Använd get_kpi_data för att hämta faktiska värden', 'Filtrera på operating_area för att smalna av resultaten', ], }, null, 2 ), }, ], }; } catch (error) { logger.toolResult('get_municipality_kpis', false, Date.now() - startTime); throw error; } }, },