OpenTK Model Context Protocol Server

Instructions

Implementation Reference

• src/index.ts:682-764 (handler)

  The handler function executes the tool logic: validates input, calls apiService.search with {soorten: category} for category-specific search, sorts results by recency, paginates, formats to summary (id, title, category, date, url), returns structured JSON with pagination metadata or error handling.
  async ({ query, category, page = 1, limit = 20 }) => { try { // Validate and cap the limit const validatedLimit = Math.min(Math.max(1, limit), 100); const validatedPage = Math.max(1, page); const data = await apiService.search<{ results: any[], error?: string }>(query, { soorten: category }); // Check if there's an error message in the response if (data.error) { return { content: [ { type: "text", text: data.error }, { type: "text", text: JSON.stringify(data.results || [], null, 2) } ] }; } // If no results were found if (!data.results || data.results.length === 0) { return { content: [{ type: "text", text: `No results found for query: ${query} with category: ${category}. Try using different keywords or a different category.` }] }; } // Sort results by date (most recent first) const sortedResults = [...data.results].sort((a, b) => { // Parse dates from the 'datum' field (format: YYYY-MM-DDT00:00:00) const dateA = new Date(a.datum); const dateB = new Date(b.datum); return dateB.getTime() - dateA.getTime(); // Descending order (newest first) }); // Calculate pagination const totalResults = sortedResults.length; const totalPages = Math.ceil(totalResults / validatedLimit); const startIndex = (validatedPage - 1) * validatedLimit; const endIndex = Math.min(startIndex + validatedLimit, totalResults); const paginatedResults = sortedResults.slice(startIndex, endIndex); // Create pagination info const paginationInfo = { query, category, totalResults, page: validatedPage, limit: validatedLimit, totalPages, hasNextPage: validatedPage < totalPages, hasPreviousPage: validatedPage > 1 }; // Create a summary version with only essential fields const formattedResults = paginatedResults.map(item => ({ id: item.id, title: item.title, category: item.category, datum: item.datum, url: item.url })); // Return the paginated results with pagination info return { content: [{ type: "text", text: JSON.stringify({ pagination: paginationInfo, results: formattedResults }, null, 2) }] }; } catch (error: any) { return { content: [{ type: "text", text: `Error searching by category: ${error.message || 'Unknown error'}` }] }; } }
• src/index.ts:673-673 (registration)

  Registers the 'search_by_category' tool with the MCP server via mcp.tool(), providing name, long description, input schema, and handler reference.
  mcp.tool(
• src/index.ts:677-681 (schema)

  Zod schema defining input parameters: required query (string), category enum ['vragen','moties','alles'], optional page and limit (numbers).
  query: z.string().describe("Search term - any keyword, name, policy area, or quote you want to find in parliamentary records"), category: z.enum(["vragen", "moties", "alles"]).describe("Document category: 'vragen' for questions, 'moties' for motions, 'alles' for all document types"), page: z.number().optional().describe("Page number for paginated results (default: 1)"), limit: z.number().optional().describe("Maximum number of results to return per page (default: 20, max: 100)") },
• src/services/api.ts:151-287 (helper)

  apiService.search helper: performs HTTP POST to /search endpoint with FormData including 'soorten' for category filtering ('vragen', 'moties', 'alles'), handles complex error cases with retry on 500, returns {results, error?}.
  async search<T>(query: string, options: { twomonths?: boolean, soorten?: string } = {}): Promise<T> { try { // Don't sanitize quotes as they're important for exact phrase searches // Only sanitize backslashes which could cause issues const sanitizedQuery = query.replace(/\\/g, ' ').trim(); // Use FormData for multipart/form-data const formData = new FormData(); formData.append('q', sanitizedQuery); formData.append('twomonths', options.twomonths ? "true" : "false"); formData.append('soorten', options.soorten || "alles"); // Default to 'alles' const res = await fetch(`${BASE_URL}/search`, { method: "POST", headers: { // Remove explicit Content-Type, fetch will set it for FormData 'Accept': '*/*', 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36', 'Referer': `${BASE_URL}/search.html?q=${encodeURIComponent(sanitizedQuery)}&twomonths=${options.twomonths ? "true" : "false"}&soorten=${options.soorten || "alles"}`, 'Origin': BASE_URL, 'Host': 'berthub.eu', 'Connection': 'keep-alive', 'Sec-Fetch-Dest': 'empty', 'Sec-Fetch-Mode': 'cors', 'Sec-Fetch-Site': 'same-origin', 'sec-ch-ua': '"Chromium";v="135", "Not-A.Brand";v="8"', 'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"macOS"' }, body: formData, // Pass FormData object directly agent: ApiService.agent } as NodeRequestInit); if (!res.ok) { // If we get a 500 error, try to use a simplified query instead if (res.status === 500) { // API returned 500 error - let's investigate before simplifying let actualErrorContent = await res.text().catch(() => "Could not read error response body"); let errorMessage = `Initial request failed with 500: ${res.statusText}. Response: ${actualErrorContent.substring(0, 200)}...`; // Limit length // Optional: Try simplifying only if the error content suggests it, // otherwise, maybe just report the initial 500 error. // For now, we'll still try simplifying but provide better final message. const simplifiedQuery = sanitizedQuery.split(/\\s+/)[0]; // Initialize retry error message let retryErrorMessage = "Simplification/Retry not attempted or failed."; if (simplifiedQuery && simplifiedQuery !== sanitizedQuery) { // Retry with simplified query // Use FormData for the retry as well const simplifiedFormData = new FormData(); simplifiedFormData.append('q', simplifiedQuery); simplifiedFormData.append('twomonths', options.twomonths ? "true" : "false"); simplifiedFormData.append('soorten', options.soorten || "alles"); // Default to 'alles' try { const retryRes = await fetch(`${BASE_URL}/search`, { method: "POST", headers: { // Use same headers as initial, without Content-Type 'Accept': '*/*', 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36', 'Referer': `${BASE_URL}/search.html?q=${encodeURIComponent(simplifiedQuery)}&twomonths=${options.twomonths ? "true" : "false"}&soorten=${options.soorten || "alles"}`, 'Origin': BASE_URL, 'Host': 'berthub.eu', 'Connection': 'keep-alive', 'Sec-Fetch-Dest': 'empty', 'Sec-Fetch-Mode': 'cors', 'Sec-Fetch-Site': 'same-origin', 'sec-ch-ua': '"Chromium";v="135", "Not-A.Brand";v="8"', 'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"macOS"' }, body: simplifiedFormData, // Pass FormData object agent: ApiService.agent } as NodeRequestInit); if (retryRes.ok) { const retryText = await retryRes.text(); // Check for HTML in retry response too if (retryText.trim().startsWith('<!DOCTYPE')) { retryErrorMessage = "Retry attempt returned HTML instead of JSON."; } else { try { const retryData = JSON.parse(retryText); // Return only the parsed data, matching the expected type T return retryData as T; } catch (e) { retryErrorMessage = `Retry succeeded but failed to parse JSON response: ${e instanceof Error ? e.message : String(e)}. Response: ${retryText.substring(0, 200)}...`; } } } else { // Capture retry failure details const retryErrorBody = await retryRes.text().catch(() => "Could not read retry error body"); retryErrorMessage = `Retry with simplified query failed with status: ${retryRes.status} ${retryRes.statusText}. Response: ${retryErrorBody.substring(0, 200)}...`; } } catch (retryFetchError) { retryErrorMessage = `Fetch error during retry attempt: ${retryFetchError instanceof Error ? retryFetchError.message : String(retryFetchError)}`; } } else { retryErrorMessage = "Original query was already simple; retry not attempted."; } // If retry failed or wasn't applicable, return empty results with a more informative error // Combine initial error reason and retry outcome. const finalErrorMessage = `Search failed for query '${sanitizedQuery}'. Initial error: ${res.status} ${res.statusText}. ${retryErrorMessage}`; return { results: [], error: finalErrorMessage } as T; } // Handle non-500 errors const errorBody = await res.text().catch(() => "Could not read error response body"); throw new Error(`API error: ${res.status} ${res.statusText}. Response: ${errorBody.substring(0, 200)}...`); } // Check if the response is HTML const text = await res.text(); if (text.trim().startsWith('<!DOCTYPE')) { // The API returned HTML instead of JSON return { results: [] } as T; } // Parse JSON try { return JSON.parse(text) as T; } catch (error) { // Failed to parse JSON return { results: [] } as T; } } catch (error) { // Unexpected error in search throw error; } }