search_officers

Instructions

Implementation Reference

• src/index.ts:72-76 (schema)

  TypeScript interface defining the input arguments for the search_officers tool: search query 'q' (required), optional jurisdiction_code, and optional page number.

  interface SearchOfficersArgs {
    q: string;
    jurisdiction_code?: string;
    page?: number;
  }

• src/index.ts:132-148 (registration)

  Registration of the 'search_officers' tool in the ListToolsRequestSchema handler, defining its name, description, and JSON Schema input specification.

  {
    name: "search_officers",
    description:
      "Search for officers (directors, shareholders, agents) across all companies in OpenCorporates.",
    inputSchema: {
      type: "object",
      properties: {
        q: { type: "string", description: "Officer name or search query" },
        jurisdiction_code: {
          type: "string",
          description: "Jurisdiction code to filter results (e.g. 'us_de', 'gb')",
        },
        page: { type: "number", description: "Page number for pagination (default 1)" },
      },
      required: ["q"],
    },
  },

• src/index.ts:268-301 (handler)

  Handler logic for the 'search_officers' tool: calls the OpenCorporates API /officers/search endpoint, maps results to a clean output format including officer details and associated company info, and returns JSON output.

  case "search_officers": {
    const { q, jurisdiction_code, page } = args as unknown as SearchOfficersArgs;
    if (!q) throw new Error("Parameter 'q' is required");
  
    const data = (await apiFetch("/officers/search", {
      q,
      jurisdiction_code,
      page,
    })) as { results: { officers: Array<{ officer: Record<string, unknown> }> } };
  
    const officers = data.results?.officers ?? [];
    if (officers.length === 0) return textResult("No officers found matching that query.");
  
    const out = officers.map(({ officer: o }) => {
      const company = o["company"] as Record<string, unknown> | null;
      return {
        name: o["name"],
        position: o["position"],
        start_date: o["start_date"],
        end_date: o["end_date"],
        inactive: o["inactive"],
        company: company
          ? {
              name: company["name"],
              company_number: company["company_number"],
              jurisdiction_code: company["jurisdiction_code"],
              opencorporates_url: company["opencorporates_url"],
            }
          : null,
        opencorporates_url: o["opencorporates_url"],
      };
    });
    return textResult(JSON.stringify(out, null, 2));
  }

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

  Helper function that constructs URLs for API requests, appending the API key and query parameters as needed. Used by the search_officers handler via apiFetch.

  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:56-60 (helper)

  Helper function that wraps a string response into the MCP text result format used by all tool handlers including search_officers.

  function textResult(content: string) {
    return {
      content: [{ type: "text" as const, text: content }],
    };
  }