devutils-mcp-server

Instructions

Implementation Reference

• src/tools/jwt.ts:6-64 (handler)

  The handler implementation for the jwt_decode tool, which performs base64url decoding and JSON parsing of the JWT components.

  server.tool(
    "jwt_decode",
    "Decode a JWT (JSON Web Token) and display its header and payload without verifying the signature. Useful for debugging and inspecting tokens.",
    { token: z.string().describe("The JWT string to decode") },
    async ({ token }) => {
      try {
        const parts = token.split(".");
        if (parts.length !== 3) {
          return {
            content: [
              {
                type: "text" as const,
                text: "Error: Invalid JWT format. A JWT must have 3 parts separated by dots (header.payload.signature).",
              },
            ],
            isError: true,
          };
        }
  
        const decodeBase64Url = (str: string): string => {
          // Replace URL-safe characters and add padding
          const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
          const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
          return Buffer.from(padded, "base64").toString("utf-8");
        };
  
        const header = JSON.parse(decodeBase64Url(parts[0]));
        const payload = JSON.parse(decodeBase64Url(parts[1]));
  
        // Enrich payload with human-readable dates
        const enriched = { ...payload };
        if (enriched.iat) enriched.iat_readable = new Date(enriched.iat * 1000).toISOString();
        if (enriched.exp) enriched.exp_readable = new Date(enriched.exp * 1000).toISOString();
        if (enriched.nbf) enriched.nbf_readable = new Date(enriched.nbf * 1000).toISOString();
  
        const result = {
          header,
          payload: enriched,
          signature: parts[2],
        };
  
        return {
          content: [
            { type: "text" as const, text: JSON.stringify(result, null, 2) },
          ],
        };
      } catch (e) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error decoding JWT: ${e instanceof Error ? e.message : String(e)}`,
            },
          ],
          isError: true,
        };
      }
    }
  );