searchMeetingList

Instructions

Implementation Reference

• src/index.ts:215-238 (handler)

  Handler function that calls the Kokkai API 'meeting_list' endpoint with the provided parameters, handles errors, and returns the result as formatted JSON text.

  async (params) => {
    const result = await this._callKokkaiApi(
      "meeting_list",
      params
    );
    if (result.error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching meeting list: ${result.message} ${result.details || ""}`,
          },
        ],
      };
    }
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/index.ts:6-134 (schema)

  Common schema parameters shared across all Kokkai API search tools, defining input validation for search criteria like dates, speakers, keywords, etc.

  const kokkaiCommonSearchParams = {
    startRecord: z
      .number()
      .int()
      .min(1)
      .optional()
      .describe(
        "Start position for retrieving search results (1-based). Default is 1."
      ),
    nameOfHouse: z
      .enum(["衆議院", "参議院", "両院", "両院協議会"])
      .optional()
      .describe(
        "Name of the House (e.g., '衆議院' for House of Representatives, '参議院' for House of Councillors). '両院' and '両院協議会' yield the same results."
      ),
    nameOfMeeting: z
      .string()
      .optional()
      .describe(
        "Name of the meeting (e.g., plenary session, committee). Partial match. Multiple terms separated by space for OR search."
      ),
    any: z
      .string()
      .optional()
      .describe(
        "Keywords to search in speech content. Partial match. Multiple terms separated by space for AND search."
      ),
    speaker: z
      .string()
      .optional()
      .describe(
        "Speaker's name. Partial match. Multiple names separated by space for OR search."
      ),
    from: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format")
      .optional()
      .describe(
        "Start date for meeting search (YYYY-MM-DD). Default '0000-01-01'."
      ),
    until: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format")
      .optional()
      .describe(
        "End date for meeting search (YYYY-MM-DD). Default '9999-12-31'."
      ),
    supplementAndAppendix: z
      .boolean()
      .optional()
      .describe(
        "Limit search to supplements and appendices. Default false."
      ),
    contentsAndIndex: z
      .boolean()
      .optional()
      .describe("Limit search to table of contents and index. Default false."),
    searchRange: z
      .enum(["冒頭", "本文", "冒頭・本文"])
      .optional()
      .describe(
        "Specifies where to search for keywords from 'any' parameter: '冒頭' (opening), '本文' (body), or '冒頭・本文' (both). Default '冒頭・本文'."
      ),
    closing: z
      .boolean()
      .optional()
      .describe("Limit search to meetings held during recess. Default false."),
    speechNumber: z
      .number()
      .int()
      .nonnegative()
      .optional()
      .describe("Exact match for speech number (e.g., 10)."),
    speakerPosition: z
      .string()
      .optional()
      .describe("Speaker's position/title. Partial match."),
    speakerGroup: z
      .string()
      .optional()
      .describe("Speaker's affiliated political group. Partial match."),
    speakerRole: z
      .enum(["証人", "参考人", "公述人"])
      .optional()
      .describe(
        "Speaker's role: '証人' (witness), '参考人' (expert witness/referential speaker), '公述人' (public speaker)."
      ),
    speechID: z
      .string()
      .optional()
      .describe(
        "Unique ID for a speech (format: issueID_paddedSpeechNumber, e.g., '100105254X00119470520_000'). Exact match."
      ),
    issueID: z
      .string()
      .optional()
      .describe(
        "Unique ID for a meeting record (21 alphanumeric characters, e.g., '100105254X00119470520'). Exact match."
      ),
    sessionFrom: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Starting Diet session number (up to 3 digits)."),
    sessionTo: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Ending Diet session number (up to 3 digits)."),
    issueFrom: z
      .number()
      .int()
      .nonnegative()
      .optional()
      .describe(
        "Starting issue number (up to 3 digits, 0 for TOC/index/appendix/supplement)."
      ),
    issueTo: z
      .number()
      .int()
      .nonnegative()
      .optional()
      .describe(
        "Ending issue number (up to 3 digits, 0 for TOC/index/appendix/supplement)."
      ),
    // recordPacking is handled internally, always 'json'
  };

• src/index.ts:203-214 (schema)

  Specific input schema for searchMeetingList tool, extending common params with maximumRecords limit.

  {
    ...kokkaiCommonSearchParams,
    maximumRecords: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe(
        "Maximum number of records to retrieve (1-100) for meeting list. Default is 30."
      ),
  },

• src/index.ts:201-239 (registration)

  Registration of the searchMeetingList tool on the MCP server, including name, description, input schema, and handler function.

    "searchMeetingList",
    "Searches for meeting summaries from the Kokkai API (会議単位簡易出力). Returns basic info like meeting name, date, ID, URL. Does not include speech text. Max 100 records.",
    {
      ...kokkaiCommonSearchParams,
      maximumRecords: z
        .number()
        .int()
        .min(1)
        .max(100)
        .optional()
        .describe(
          "Maximum number of records to retrieve (1-100) for meeting list. Default is 30."
        ),
    },
    async (params) => {
      const result = await this._callKokkaiApi(
        "meeting_list",
        params
      );
      if (result.error) {
        return {
          content: [
            {
              type: "text",
              text: `Error fetching meeting list: ${result.message} ${result.details || ""}`,
            },
          ],
        };
      }
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    }
  );

• src/index.ts:146-197 (helper)

  Helper method used by all tools to make HTTP requests to the Kokkai API, construct query parameters, handle responses and errors.

  private async _callKokkaiApi(
    endpoint: string,
    params: Record<string, any>
  ): Promise<any> {
    const queryParams = new URLSearchParams();
    for (const key in params) {
      if (params[key] !== undefined && params[key] !== null) {
        queryParams.append(key, String(params[key]));
      }
    }
    queryParams.append("recordPacking", "json"); // Always request JSON
  
    const url = `${KOKKAI_API_BASE_URL}/${endpoint}?${queryParams.toString()}`;
    console.log(`Calling Kokkai API: ${url}`);
  
    try {
      const response = await fetch(url, {
        headers: {
          "User-Agent": "MCP Agent Kokkai Client/1.0",
        },
      });
  
      const responseData = (await response.json()) as any;
  
      if (!response.ok) {
        const errorMessage =
          responseData.message || "Unknown API error";
        const errorDetails = responseData.details
          ? responseData.details.join("; ")
          : "";
        console.error(
          `Kokkai API Error: ${errorMessage} ${errorDetails}`,
          responseData
        );
        return {
          error: true,
          status: response.status,
          message: errorMessage,
          details: errorDetails,
          rawResponse: responseData,
        };
      }
      return responseData;
    } catch (error: any) {
      console.error("Network or parsing error calling Kokkai API:", error);
      return {
        error: true,
        message:
          error.message || "Failed to fetch or parse API response.",
      };
    }
  }