OpenTK Model Context Protocol Server

Instructions

Implementation Reference

• src/index.ts:26-55 (registration)

  MCP tool registration for 'get_overview', defining the tool name, long description, input schema (optional page number), and thin async handler that validates input and calls apiService.getOverview() to execute the logic, returning formatted text content.
  mcp.tool( "get_overview", "Provides a comprehensive overview of recent parliamentary activities, including the most recent documents and MPs celebrating birthdays today. The response contains structured data with two main sections: 'recentDocuments' (listing the latest parliamentary documents with their IDs, titles, types, dates, and URLs) and 'birthdays' (listing MPs celebrating birthdays today). The results are paginated with 10 documents per page. The tool supports iterative pagination - check the pagination.hasMoreDocuments field in the response to determine if additional pages are available. The response includes pagination information showing the current page, whether more documents are available, and the total number of documents retrieved. Applicable when general information about recent parliamentary activities is needed.", { page: z.number().optional().describe("Page number for paginated results (default: 1). Each page contains 10 documents.") }, async ({ page = 1 }) => { try { // Validate page number const validatedPage = Math.max(1, page); // Get overview data with pagination const overview = await apiService.getOverview(validatedPage); return { content: [{ type: "text", text: JSON.stringify(overview, null, 2) }] }; } catch (error: any) { return { content: [{ type: "text", text: `Error fetching overview: ${error.message || 'Unknown error'}` }] }; } } );
• src/services/api.ts:558-583 (handler)

  Primary handler function in ApiService class that fetches the main '/' HTML page, extracts structured overview data (recent documents and birthdays) using the html-parser utility with pagination support, and handles errors by returning empty data with error message.
  async getOverview(page: number = 1): Promise<any> { try { // Validate page number const validatedPage = Math.max(1, page); // Fetch the HTML of the main page const html = await this.fetchHtml("/"); // Extract overview data from the HTML with pagination const overviewData = extractOverviewFromHtml(html, BASE_URL, validatedPage); return overviewData; } catch (error) { return { recentDocuments: [], birthdays: [], lastUpdated: new Date().toISOString(), pagination: { currentPage: page, hasMoreDocuments: false, totalDocumentsRetrieved: 0 }, error: (error as Error).message || 'Unknown error' }; } }
• src/index.ts:29-31 (schema)

  Zod input schema for the get_overview tool, defining an optional 'page' parameter (number) for pagination with descriptive documentation.
  { page: z.number().optional().describe("Page number for paginated results (default: 1). Each page contains 10 documents.") },
• src/utils/html-parser.ts:646-809 (helper)

  Key helper utility that parses raw HTML from the main tkconv page to extract paginated recent documents (id, title, type, date, etc.) from table rows and today's birthdays from special section, returning structured OverviewData interface with pagination metadata. Used by apiService.getOverview.
  export function extractOverviewFromHtml(html: string, baseUrl: string, page: number = 1): OverviewData { if (!html) { return { recentDocuments: [], birthdays: [], lastUpdated: new Date().toISOString(), pagination: { currentPage: 1, hasMoreDocuments: false, totalDocumentsRetrieved: 0 } }; } const recentDocuments: RecentDocument[] = []; const birthdays: BirthdayPerson[] = []; let lastUpdated = new Date().toISOString(); // Extract the table containing recent documents const tableRegex = /<table[^>]*>[\s\S]*?<tbody>([\s\S]*?)<\/tbody>/i; const tableMatch = html.match(tableRegex); if (tableMatch && tableMatch[1]) { const tableContent = tableMatch[1]; // Extract each row (document) from the table const rowRegex = /<tr[^>]*>([\s\S]*?)<\/tr>/gi; let rowMatch; while ((rowMatch = rowRegex.exec(tableContent)) !== null) { if (!rowMatch[1]) continue; const rowContent = rowMatch[1]; // Extract cells const cellRegex = /<td[^>]*>([\s\S]*?)<\/td>/gi; const cells: string[] = []; let cellMatch; while ((cellMatch = cellRegex.exec(rowContent)) !== null) { if (cellMatch[1]) { cells.push(cellMatch[1].trim()); } } // Need at least date, updated, committee, subject, and title/type if (cells.length < 5) continue; // Extract date const date = cells[0] ? cells[0].replace(/<[^>]+>/g, "").trim() : ""; if (!date) continue; // Extract updated date const updated = cells[1] ? cells[1].replace(/<[^>]+>/g, "").trim() : ""; // Extract committee const committee = cells[2] ? cells[2].replace(/<[^>]+>/g, "").trim() : undefined; // Extract subject const subject = cells[3] ? cells[3].replace(/<[^>]+>/g, "").trim() : undefined; // Extract title, type, and document ID from the last cell const titleCell = cells[4] || ""; // Extract document ID and title from the link if present const docLinkMatch = titleCell.match(/<a href="document\.html\?nummer=([^"]+)">([\s\S]*?)<\/a>/i); let id = ""; let title = ""; let url = ""; if (docLinkMatch && docLinkMatch[1] && docLinkMatch[2]) { id = docLinkMatch[1]; title = docLinkMatch[2].trim(); url = new URL(`document.html?nummer=${id}`, baseUrl).href; } else { // If no link, just use the text content title = titleCell.replace(/<[^>]+>/g, "").trim(); // Generate a placeholder ID id = `unknown-${Date.now()}-${Math.floor(Math.random() * 1000)}`; url = baseUrl; } // Extract document type (usually on the next line after the title) const typeMatch = titleCell.match(/<br\s*\/?>\s*(.*?)(?:<|$)/i); const type = typeMatch && typeMatch[1] ? typeMatch[1].trim() : "Unknown"; // Add the document to the list recentDocuments.push({ id, title, type, date, updated, committee, subject, url }); // Limit to 20 documents to avoid overwhelming the response if (recentDocuments.length >= 20) break; } } // Extract birthdays const birthdayRegex = /Jarig vandaag\s*((?:<a[^>]*>[^<]*<\/a>\s*)+)/i; const birthdayMatch = html.match(birthdayRegex); if (birthdayMatch && birthdayMatch[1]) { const birthdayContent = birthdayMatch[1]; const birthdayLinkRegex = /<a href="persoon\.html\?nummer=([^"]+)">([\s\S]*?)<\/a>/gi; let birthdayLinkMatch; while ((birthdayLinkMatch = birthdayLinkRegex.exec(birthdayContent)) !== null) { if (birthdayLinkMatch[1] && birthdayLinkMatch[2]) { const id = birthdayLinkMatch[1]; const nameWithParty = birthdayLinkMatch[2].trim(); // Extract name and party if in format "Name (Party)" const namePartyMatch = nameWithParty.match(/(.*?)\s*\((.*?)\)\s*$/); let name = nameWithParty; let party = undefined; if (namePartyMatch && namePartyMatch[1] && namePartyMatch[2]) { name = namePartyMatch[1].trim(); party = namePartyMatch[2].trim(); } const url = new URL(`persoon.html?nummer=${id}`, baseUrl).href; birthdays.push({ id, name, party, url }); } } } // For pagination, we would normally need to fetch different pages from the server // Since the tkconv site doesn't have explicit pagination, we're simulating it by // limiting the number of documents per page and tracking which ones we've shown const documentsPerPage = 10; const startIndex = (page - 1) * documentsPerPage; const endIndex = startIndex + documentsPerPage; // Get the documents for the current page const paginatedDocuments = recentDocuments.slice(startIndex, endIndex); // Check if there are more documents available const hasMoreDocuments = endIndex < recentDocuments.length; return { recentDocuments: paginatedDocuments, birthdays, // Birthdays are always shown regardless of page lastUpdated, pagination: { currentPage: page, hasMoreDocuments, totalDocumentsRetrieved: recentDocuments.length } }; }
• src/utils/html-parser.ts:86-95 (schema)

  TypeScript interface defining the output structure/schema of the overview data returned by extractOverviewFromHtml and getOverview, including arrays of recent documents and birthdays with pagination info.
  interface OverviewData { recentDocuments: RecentDocument[]; birthdays: BirthdayPerson[]; lastUpdated: string; pagination: { currentPage: number; hasMoreDocuments: boolean; totalDocumentsRetrieved: number; }; }