find_entities

Instructions

Implementation Reference

• src/tools/find.ts:180-210 (handler)

  Main handler for the find_entities tool. Dispatches to findMPs, findBills, findPetitions, or findInterests based on entity_type argument.

  export async function handleFindTool(
    name: string,
    args: Record<string, unknown>
  ): Promise<string> {
    try {
      if (name !== "find_entities") {
        throw new Error(`Unknown tool: ${name}`);
      }
  
      const entityType = args.entity_type as string;
      const limit = (args.limit as number) ?? 20;
  
      if (entityType === "mp") {
        return await findMPs(args, limit);
      } else if (entityType === "bill") {
        return await findBills(args, limit);
      } else if (entityType === "petition") {
        return await findPetitions(args, limit);
      } else if (entityType === "interest") {
        return await findInterests(args, limit);
      } else {
        throw new Error(
          `Unknown entity_type: ${entityType}. Use 'mp', 'bill', 'petition', or 'interest'.`
        );
      }
    } catch (error) {
      const message =
        error instanceof Error ? error.message : "An unknown error occurred.";
      throw new Error(message);
    }
  }

• src/tools/find.ts:10-75 (schema)

  Tool definition including inputSchema with entity_type enum (mp, bill, petition, interest) and various filter parameters like name, mp_id, party, constituency, keyword, etc.

  export const findTools = [
    {
      name: "find_entities",
      description:
        "Find MPs, bills, petitions, or declared financial interests. " +
        "entity_type='mp': search members by name/party/constituency/house/status. " +
        "entity_type='bill': search legislation by title keyword/stage/house. " +
        "entity_type='petition': find petitions by keyword. " +
        "entity_type='interest': fetch an MP's declared financial interests. Pass name='John McDonnell' OR mp_id=178 (member ID from a prior MP lookup). Optionally add keyword to filter by topic (e.g. keyword='property'). To find ALL MPs with a given interest topic, omit name/mp_id and pass only keyword='defence'.",
      inputSchema: {
        type: "object",
        properties: {
          entity_type: {
            type: "string",
            enum: ["mp", "bill", "petition", "interest"],
            description: "What to search for.",
          },
          name: {
            type: "string",
            description: "MP or Lord name. For entity_type='mp': filter by name. For entity_type='interest': fetch this specific MP's declared interests.",
          },
          mp_id: {
            type: "number",
            description: "MP member ID (integer). For entity_type='interest': fetch declared interests for the MP with this ID. Use this when you already have the member ID from a prior find_entities mp lookup.",
          },
          party: {
            type: "string",
            description: "Filter MPs by party.",
          },
          constituency: {
            type: "string",
            description: "Filter MPs by constituency.",
          },
          house: {
            type: "string",
            enum: ["Commons", "Lords"],
            description: "Filter by house.",
          },
          status: {
            type: "string",
            enum: ["active", "inactive"],
            description: "Filter MPs by active or inactive status.",
          },
          stage: {
            type: "string",
            description: "Bill stage filter.",
          },
          keyword: {
            type: "string",
            description:
              "Bill title search, petition text search, or financial interest topic filter.",
          },
          petition_state: {
            type: "string",
            enum: ["open", "closed", "all"],
            description: "Petition state filter. Default 'all'.",
          },
          limit: {
            type: "number",
            description: "Maximum results. Default 20.",
          },
        },
        required: ["entity_type"],
      },
    },
  ];

• src/index.ts:12-12 (registration)

  Import of findTools and handleFindTool from src/tools/find.ts

  import { findTools, handleFindTool } from "./tools/find.js";

• src/index.ts:38-38 (registration)

  Route for find_entities in the CallToolRequestSchema handler — calls handleFindTool when name is 'find_entities'

  else if (name === "find_entities") result = await handleFindTool(name, safeArgs);

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

  Registration of findTools in the allTools array passed to ListToolsRequestSchema handler

  const allTools = [
    ...rankTools,
    ...eventsTools,
    ...patternsTools,
    ...findTools,
    ...queryTools,
  ];