mcp-nordic

Instructions

Implementation Reference

• src/servers/finnish-companies.js:168-207 (handler)

  The 'fi_search_companies' tool is defined and implemented here using 'server.tool'. The handler function extracts query parameters, calls an internal 'apiFetch' function, and formats the results.

  server.tool(
    "fi_search_companies",
    "Search Finnish company registry (PRH/YTJ) by name, location, business ID, or company form. Free government API.",
    {
      name: z.string().optional().describe("Company name to search for"),
      location: z.string().optional().describe("Town or city (e.g., 'Helsinki', 'Tampere', 'Espoo')"),
      business_id: z.string().optional().describe("Finnish Business ID (Y-tunnus), e.g., '0112038-9'"),
      company_form: z.string().optional().describe("Company form code: OY (ltd), OYJ (public ltd), KY (limited partnership), AY (general partnership), OK (cooperative), SÄÄ (foundation)"),
      business_line: z.string().optional().describe("Main line of business - TOL 2008 code (e.g., '62010') or text description"),
      post_code: z.string().optional().describe("Postal code"),
      page: z.number().optional().default(1).describe("Page number (100 results per page)"),
    },
    async ({ name, location, business_id, company_form, business_line, post_code, page }) => {
      if (!name && !location && !business_id && !company_form && !business_line && !post_code) {
        return { content: [{ type: "text", text: "Please provide at least one search criterion (name, location, business_id, company_form, business_line, or post_code)." }] };
      }
  
      const params = {};
      if (name) params.name = name;
      if (location) params.location = location;
      if (business_id) params.businessId = business_id;
      if (company_form) params.companyForm = company_form;
      if (business_line) params.mainBusinessLine = business_line;
      if (post_code) params.postCode = post_code;
      if (page && page > 1) params.page = page;
  
      const data = await apiFetch("/companies", params);
      const companies = data.companies || [];
      const total = data.totalResults || 0;
  
      if (companies.length === 0) {
        return { content: [{ type: "text", text: "No companies found matching your criteria." }] };
      }
  
      const header = `Found ${total.toLocaleString()} companies (showing ${companies.length}, page ${page || 1}):\n`;
      const results = companies.map((c, i) => `${i + 1}. ${formatCompanySummary(c)}`).join("\n\n");
  
      return { content: [{ type: "text", text: header + "\n" + results }] };
    }
  );