Skolverket MCP Server

Instructions

Implementation Reference

• src/tools/syllabus/courses.ts:28-76 (handler)

  Main execution logic for the 'search_courses' tool. Calls syllabus API, limits results, formats JSON response with courses data.

  export async function searchCourses(params: {
    schooltype?: string;
    timespan?: 'LATEST' | 'FUTURE' | 'EXPIRED' | 'MODIFIED';
    date?: string;
    subjectCode?: string;
    limit?: number;
  }) {
    try {
      const result = await syllabusApi.searchCourses(params);
  
      // Begränsa antal resultat för att undvika stora responses
      const maxResults = Math.min(params.limit || 50, 200);
      const limitedCourses = result.courses.slice(0, maxResults);
      const hasMore = result.totalElements > maxResults;
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              totalElements: result.totalElements,
              returned: limitedCourses.length,
              hasMore: hasMore,
              message: hasMore ? `Visar ${limitedCourses.length} av ${result.totalElements} kurser. Använd subjectCode eller andra filter för att begränsa resultatet.` : undefined,
              courses: limitedCourses.map(c => ({
                code: c.code,
                name: c.name,
                subjectCode: c.subjectCode,
                schoolType: c.schoolType,
                points: c.points,
                version: c.version,
                description: c.description?.substring(0, 150) + (c.description && c.description.length > 150 ? '...' : '')
              }))
            }, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text' as const,
            text: `Fel vid sökning av kurser: ${error instanceof Error ? error.message : String(error)}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/syllabus/courses.ts:9-15 (schema)

  Zod schema defining input parameters and descriptions for the search_courses tool.

  export const searchCoursesSchema = {
    schooltype: z.string().optional().describe('Skoltyp (t.ex. "GY" för gymnasium)'),
    timespan: z.enum(['LATEST', 'FUTURE', 'EXPIRED', 'MODIFIED']).default('LATEST').describe('Tidsperiod: LATEST (gällande), FUTURE (framtida), EXPIRED (utgångna), MODIFIED (ändrade)'),
    date: z.string().optional().describe('Datum i formatet YYYY-MM-DD för att hämta kurser som var giltiga vid det datumet'),
    subjectCode: z.string().optional().describe('Ämneskod för att filtrera kurser'),
    limit: z.number().optional().default(50).describe('Max antal resultat att returnera (default: 50, max: 200)')
  };

• src/http-server.ts:56-56 (registration)

  Maps the 'search_courses' tool name to the searchCourses handler function in the central tools registry.

  search_courses: searchCourses,

• src/http-server.ts:23-23 (registration)

  Imports the searchCourses handler from its implementation file for use in tool registration.

  import { searchCourses, getCourseDetails, getCourseVersions } from './tools/syllabus/courses.js';

• src/api/syllabus-client.ts:60-62 (helper)

  Underlying API client method called by the tool handler to fetch course data from Skolverket's syllabus API.

  async searchCourses(params: CourseSearchParams = {}): Promise<CoursesResponse> {
    return this.get<CoursesResponse>('/v1/courses', params);
  }