get_company

Instructions

Implementation Reference

• src/index.ts:68-71 (schema)

  TypeScript interface defining the input args for the get_company tool: jurisdiction_code and company_number, both strings.

  interface GetCompanyArgs {
    jurisdiction_code: string;
    company_number: string;
  }

• src/index.ts:113-131 (registration)

  Tool registration in ListToolsRequestSchema handler: defines tool name 'get_company', description, and input JSON schema specifying required jurisdiction_code and company_number.

  {
    name: "get_company",
    description:
      "Get full details for a specific company by jurisdiction code and company number. Returns name, status, incorporation date, registered address, officers, and filings.",
    inputSchema: {
      type: "object",
      properties: {
        jurisdiction_code: {
          type: "string",
          description: "Jurisdiction code (e.g. 'us_de', 'gb', 'de')",
        },
        company_number: {
          type: "string",
          description: "Company registration number",
        },
      },
      required: ["jurisdiction_code", "company_number"],
    },
  },

• src/index.ts:222-266 (handler)

  Tool handler for 'get_company' in the CallToolRequestSchema switch statement. Fetches company details from OpenCorporates API via /companies/{jurisdiction_code}/{company_number}, extracts and formats company info including officers (up to 20) and recent filings (up to 5).

  case "get_company": {
    const { jurisdiction_code, company_number } = args as unknown as GetCompanyArgs;
    if (!jurisdiction_code || !company_number)
      throw new Error("Parameters 'jurisdiction_code' and 'company_number' are required");
  
    const data = (await apiFetch(
      `/companies/${jurisdiction_code}/${encodeURIComponent(company_number)}`
    )) as { results: { company: Record<string, unknown> } };
  
    const c = data.results?.company;
    if (!c) return textResult("Company not found.");
  
    const officers =
      (c["officers"] as Array<{ officer: Record<string, unknown> }> | undefined) ?? [];
    const filings =
      (c["filings"] as Array<{ filing: Record<string, unknown> }> | undefined) ?? [];
  
    const out = {
      name: c["name"],
      company_number: c["company_number"],
      jurisdiction_code: c["jurisdiction_code"],
      status: c["current_status"],
      company_type: c["company_type"],
      incorporation_date: c["incorporation_date"],
      dissolution_date: c["dissolution_date"],
      registered_address: formatAddress(c["registered_address"]),
      agent_name: c["agent_name"],
      agent_address: c["agent_address"],
      opencorporates_url: c["opencorporates_url"],
      officers: officers.slice(0, 20).map(({ officer: o }) => ({
        name: o["name"],
        position: o["position"],
        start_date: o["start_date"],
        end_date: o["end_date"],
        inactive: o["inactive"],
      })),
      filings_count: filings.length,
      recent_filings: filings.slice(0, 5).map(({ filing: f }) => ({
        title: f["title"],
        date: f["date"],
        filing_type: f["filing_type"],
      })),
    };
    return textResult(JSON.stringify(out, null, 2));
  }

• src/index.ts:12-26 (helper)

  Helper buildUrl function that constructs API URLs with optional API key and query parameters - used by the handler to build the request URL.

  function buildUrl(
    path: string,
    params: Record<string, string | number | undefined> = {}
  ): string {
    const url = new URL(`${BASE_URL}${path}`);
    if (API_KEY) {
      url.searchParams.set("api_token", API_KEY);
    }
    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined && String(value) !== "") {
        url.searchParams.set(key, String(value));
      }
    }
    return url.toString();
  }

• src/index.ts:28-46 (helper)

  Helper apiFetch function that performs HTTP requests to the OpenCorporates API and handles error responses - used by the handler to fetch company data.

  async function apiFetch(
    path: string,
    params: Record<string, string | number | undefined> = {}
  ): Promise<unknown> {
    const url = buildUrl(path, params);
    const response = await fetch(url, {
      headers: {
        "Accept": "application/json",
        "User-Agent": "cc-suite/1.0 (gonzih@gmail.com; +https://github.com/Gonzih/mcp-opencorporates)",
      },
    });
    if (!response.ok) {
      const body = await response.text().catch(() => "");
      throw new Error(
        `OpenCorporates API error ${response.status}: ${body.slice(0, 200)}`
      );
    }
    return response.json();
  }