Lookup Trademark

Instructions

Implementation Reference

• src/tools/trademarks.ts:123-145 (handler)

  The actual handler function for the lookup_trademark tool. It takes a serial number, calls the Verilex API at /api/v1/trademarks/:serial, and returns the full trademark details as JSON.

    async ({ serial }) => {
      const res = await apiGet<{ dataset: string; data: Record<string, unknown> }>(
        `/api/v1/trademarks/${encodeURIComponent(serial)}`,
      );
  
      if (!res.ok) {
        const msg =
          res.status === 404
            ? `Serial number ${serial} not found in the trademark dataset.`
            : `API error (${res.status}): ${JSON.stringify(res.data)}`;
        return {
          content: [{ type: "text" as const, text: msg }],
          isError: res.status !== 404,
        };
      }
  
      return {
        content: [
          { type: "text" as const, text: JSON.stringify(res.data.data, null, 2) },
        ],
      };
    },
  );

• src/tools/trademarks.ts:116-121 (schema)

  Input schema for lookup_trademark: requires a 'serial' string parameter validated with a regex for 7-8 digits (USPTO serial number format).

  inputSchema: {
    serial: z
      .string()
      .regex(/^\d{7,8}$/, "Serial number must be 7-8 digits")
      .describe("USPTO serial number (e.g. 97123456)"),
  },

• src/tools/trademarks.ts:108-145 (registration)

  Registration of the lookup_trademark tool via server.registerTool() with title, description, input schema, and handler.

  server.registerTool(
    "lookup_trademark",
    {
      title: "Lookup Trademark",
      description:
        "Look up a single US trademark by its USPTO serial number. Returns full details " +
        "including mark text, owner, international class, filing date, registration date, " +
        "status, attorney, and description of goods/services. Source: USPTO TSDR.",
      inputSchema: {
        serial: z
          .string()
          .regex(/^\d{7,8}$/, "Serial number must be 7-8 digits")
          .describe("USPTO serial number (e.g. 97123456)"),
      },
    },
    async ({ serial }) => {
      const res = await apiGet<{ dataset: string; data: Record<string, unknown> }>(
        `/api/v1/trademarks/${encodeURIComponent(serial)}`,
      );
  
      if (!res.ok) {
        const msg =
          res.status === 404
            ? `Serial number ${serial} not found in the trademark dataset.`
            : `API error (${res.status}): ${JSON.stringify(res.data)}`;
        return {
          content: [{ type: "text" as const, text: msg }],
          isError: res.status !== 404,
        };
      }
  
      return {
        content: [
          { type: "text" as const, text: JSON.stringify(res.data.data, null, 2) },
        ],
      };
    },
  );

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

  Registration call: registerTrademarkTools(server) is invoked during server setup. This is where the trademark tools (including lookup_trademark) are registered on the MCP server.

  registerTrademarkTools(server);

• src/client.ts:44-76 (helper)

  The apiGet() helper function used by the handler to make HTTP GET requests to the Verilex backend API. It handles URL building, payment tokens, and parsing staleness headers.

  export async function apiGet<T = unknown>(
    path: string,
    params?: Record<string, string | number | undefined>,
  ): Promise<ApiResponse<T>> {
    const url = buildUrl(path, params);
  
    const headers: Record<string, string> = {
      Accept: "application/json",
      "User-Agent": "verilex-mcp-server/0.1.0",
    };
  
    // Forward x402 payment token if present in env (for paid endpoints)
    const paymentToken = process.env.VERILEX_PAYMENT_TOKEN;
    if (paymentToken) {
      headers["X-Payment-Token"] = paymentToken;
    }
  
    const res = await fetch(url, { headers });
    const data = (await res.json()) as T;
  
    const stale = res.headers.get("X-Data-Stale");
    const lastUpdated = res.headers.get("X-Data-Last-Updated");
    const ageSeconds = res.headers.get("X-Data-Age-Seconds");
  
    return {
      ok: res.ok,
      status: res.status,
      data,
      stale: stale === "true",
      lastUpdated: lastUpdated ?? undefined,
      ageSeconds: ageSeconds ? Number(ageSeconds) : undefined,
    };
  }