Online Kommentar MCP Server

Instructions

Implementation Reference

• src/index.ts:52-87 (handler)

  The asynchronous handler function that executes the 'search_commentaries' tool. It builds query parameters, fetches data from the Online Kommentar API, processes the response, formats the commentaries into text, and handles errors appropriately.

  async (args: { search: string; language?: "en" | "de" | "fr" | "it"; legislative_act?: string; sort?: "title" | "-title" | "date" | "-date"; page?: number; }) => {
    const { search, language, legislative_act, sort, page } = args;
    const queryParams = new URLSearchParams({
        ...(search && { search }),
        ...(language && { language }),
        ...(legislative_act && { legislative_act }),
        ...(sort && { sort }),
        ...(page && { page: page.toString() }),
    });
  
    try {
        const response = await fetch(`${API_BASE_URL}/commentaries?${queryParams.toString()}`, {
            headers: { "Accept": "application/json" }
        });
  
        if (!response.ok) {
            throw new Error(`API request failed with status ${response.status}`);
        }
  
        const data = (await response.json()) as { data: Commentary[] };
        const commentaries = data.data;
        const resultText = commentaries.length > 0
            ? commentaries.map(c => `ID: ${c.id}\nTitle: ${c.title}\nDate: ${c.date}\nURL: ${c.html_link}`).join("\n\n")
            : "No commentaries found for the given criteria.";
  
        return {
            content: [{ type: "text", text: resultText }],
        };
    } catch (error) {
        const errorMessage = error instanceof Error ? error.message : "An unknown error occurred";
        return {
            content: [{ type: "text", text: `Error searching commentaries: ${errorMessage}` }],
            isError: true,
        };
    }
  }

• src/index.ts:44-50 (schema)

  Zod-based input schema defining parameters for the 'search_commentaries' tool: search query, optional filters for language, legislative act, sort order, and pagination.

  inputSchema: {
    search: z.string().describe("The full-text search query."),
    language: z.enum(["en", "de", "fr", "it"]).optional().describe("Content language."),
    legislative_act: z.string().optional().describe("Filter by legislative act ID."),
    sort: z.enum(["title", "-title", "date", "-date"]).optional().describe("Sort order."),
    page: z.number().optional().describe("Page number for pagination."),
  },

• src/index.ts:39-88 (registration)

  Registration of the 'search_commentaries' tool on the MCP server, including name, metadata, input schema, and handler reference.

  server.registerTool(
    "search_commentaries",
    {
      title: "Search Commentaries",
      description: "Searches for legal commentaries based on a query and filters.",
      inputSchema: {
        search: z.string().describe("The full-text search query."),
        language: z.enum(["en", "de", "fr", "it"]).optional().describe("Content language."),
        legislative_act: z.string().optional().describe("Filter by legislative act ID."),
        sort: z.enum(["title", "-title", "date", "-date"]).optional().describe("Sort order."),
        page: z.number().optional().describe("Page number for pagination."),
      },
    },
    async (args: { search: string; language?: "en" | "de" | "fr" | "it"; legislative_act?: string; sort?: "title" | "-title" | "date" | "-date"; page?: number; }) => {
      const { search, language, legislative_act, sort, page } = args;
      const queryParams = new URLSearchParams({
          ...(search && { search }),
          ...(language && { language }),
          ...(legislative_act && { legislative_act }),
          ...(sort && { sort }),
          ...(page && { page: page.toString() }),
      });
  
      try {
          const response = await fetch(`${API_BASE_URL}/commentaries?${queryParams.toString()}`, {
              headers: { "Accept": "application/json" }
          });
  
          if (!response.ok) {
              throw new Error(`API request failed with status ${response.status}`);
          }
  
          const data = (await response.json()) as { data: Commentary[] };
          const commentaries = data.data;
          const resultText = commentaries.length > 0
              ? commentaries.map(c => `ID: ${c.id}\nTitle: ${c.title}\nDate: ${c.date}\nURL: ${c.html_link}`).join("\n\n")
              : "No commentaries found for the given criteria.";
  
          return {
              content: [{ type: "text", text: resultText }],
          };
      } catch (error) {
          const errorMessage = error instanceof Error ? error.message : "An unknown error occurred";
          return {
              content: [{ type: "text", text: `Error searching commentaries: ${errorMessage}` }],
              isError: true,
          };
      }
    }
  );