Online Kommentar MCP Server

Instructions

Implementation Reference

• src/index.ts:100-146 (handler)

  The handler function for the 'get_commentary_by_id' tool. It fetches commentary data from the API using the provided ID, handles 404 and other errors, parses the JSON response, formats key details like title, authors, editors, and content into a readable text block, and returns it as tool content.

    async ({ id }: { id: string }) => {
      try {
          const response = await fetch(`${API_BASE_URL}/commentaries/${id}`, {
              headers: { "Accept": "application/json" }
          });
  
          if (!response.ok) {
              if (response.status === 404) {
                  return {
                      content: [{ type: "text", text: `Commentary with ID '${id}' not found.` }],
                      isError: true,
                  };
              }
              throw new Error(`API request failed with status ${response.status}`);
          }
  
          const data = (await response.json()) as { data: Commentary };
          const commentary = data.data;
          
          // Let's format the output nicely for the user
          const authors = commentary.authors.map(a => a.name).join(', ');
          const editors = commentary.editors ? commentary.editors.map(e => e.name).join(', ') : 'None listed';
          const resultText = `
  Title: ${commentary.title}
  ID: ${commentary.id}
  Language: ${commentary.language}
  Publication Date: ${commentary.date}
  Legislative Act: ${commentary.legislative_act.title}
  Legal Domain: ${commentary.legal_domain?.name || 'Not specified'}
  Authors: ${authors}
  Editors: ${editors}
  URL: ${commentary.html_link}
  Content:
  ${commentary.content || 'Full content not available in summary.'}
          `.trim();
  
          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 retrieving commentary: ${errorMessage}` }],
              isError: true,
          };
      }
    }

• src/index.ts:91-99 (registration)

  Registers the 'get_commentary_by_id' tool with the MCP server, specifying the tool name, title, description, and input schema before passing the inline handler function.

  server.registerTool(
    "get_commentary_by_id",
    {
      title: "Get Commentary by ID",
      description: "Retrieves a specific commentary by its ID.",
      inputSchema: {
        id: z.string().describe("The ID of the commentary to retrieve."),
      },
    },

• src/index.ts:96-98 (schema)

  Zod input schema for the tool, defining a required 'id' parameter as a string with description.

  inputSchema: {
    id: z.string().describe("The ID of the commentary to retrieve."),
  },

• src/index.ts:7-30 (helper)

  TypeScript interface defining the structure of a Commentary object, used for type assertion in the handler's response parsing.

  interface Commentary {
    id: string;
    title: string;
    language: string;
    date: string;
    legislative_act: {
      id: string;
      title: string;
    };
    legal_domain?: {
      id: string;
      name: string;
    };
    authors: {
      id: string;
      name: string;
    }[];
    editors?: {
      id: string;
      name: string;
    }[];
    html_link: string;
    content?: string;
  }

• src/index.ts:5-5 (helper)

  Constant defining the base URL for the Online Kommentar API, used in fetch calls for both tools.

  const API_BASE_URL = "https://onlinekommentar.ch/api";