Parcel Tracking MCP Server

Instructions

Implementation Reference

• src/index.ts:180-225 (handler)

  The main execution logic for the 'tracking-delivery' tool: validates carrier ID, prompts for carrier if missing, registers the tracking number, fetches status from 17TRACK API, and returns formatted JSON response or error.

  async ({ number, carrier }) => {
    if (carrier && !validateCarrierId(carrier)) {
      return {
        content: [
          {
            type: "text",
            text: `The carrier ID "${carrier}" is not valid. Please use the 'search-carrier' tool to find the correct carrier ID.`,
          } as const,
        ],
      };
    }
  
    if (!carrier) {
      return {
        content: [
          {
            type: "text",
            text:
              "Please specify the carrier ID along with the tracking number for more accurate results. You can use the 'search-carrier' tool to look up the carrier ID first.",
          } as const,
        ],
      };
    }
  
    try {
      await register({ number, carrier });
      const data = await getDelivery({ number, carrier });
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(data, null, 2),
          } as const,
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: "Error tracking delivery: " + (error instanceof Error ? error.message : String(error)),
          } as const,
        ],
      };
    }
  }

• src/index.ts:172-179 (schema)

  Input schema for 'tracking-delivery' tool using Zod: requires tracking 'number' string, optional 'carrier' number ID.

    number: z.string().describe("The tracking number of the parcel"),
    carrier: z
      .number()
      .optional()
      .describe(
        "Carrier ID (number). If omitted, 17TRACK will auto-detect, but accuracy may be lower."
      ),
  },

• src/index.ts:168-226 (registration)

  MCP tool registration call: server.tool(name, description, inputSchema, handlerFunction). Note: full block includes schema and handler.

  server.tool(
    "tracking-delivery",
    "Track a parcel delivery via 17TRACK",
    {
      number: z.string().describe("The tracking number of the parcel"),
      carrier: z
        .number()
        .optional()
        .describe(
          "Carrier ID (number). If omitted, 17TRACK will auto-detect, but accuracy may be lower."
        ),
    },
    async ({ number, carrier }) => {
      if (carrier && !validateCarrierId(carrier)) {
        return {
          content: [
            {
              type: "text",
              text: `The carrier ID "${carrier}" is not valid. Please use the 'search-carrier' tool to find the correct carrier ID.`,
            } as const,
          ],
        };
      }
  
      if (!carrier) {
        return {
          content: [
            {
              type: "text",
              text:
                "Please specify the carrier ID along with the tracking number for more accurate results. You can use the 'search-carrier' tool to look up the carrier ID first.",
            } as const,
          ],
        };
      }
  
      try {
        await register({ number, carrier });
        const data = await getDelivery({ number, carrier });
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(data, null, 2),
            } as const,
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: "Error tracking delivery: " + (error instanceof Error ? error.message : String(error)),
            } as const,
          ],
        };
      }
    }
  );

• src/index.ts:84-103 (helper)

  Helper function to register a tracking number with the 17TRACK API prior to querying status.

  async function register({ number, carrier }: Props) {
    const body = [
      {
        number,
        carrier: carrier ?? 0,
      },
    ];
  
    const res = await fetch(`${TRACKER_API_BASE_URL}/register`, {
      method: "POST",
      headers: {
        "17token": apiToken,
        "Content-Type": "application/json",
        "User-Agent": USER_AGENT,
      },
      body: JSON.stringify(body),
    });
  
    return res.json();
  }

• src/index.ts:105-123 (helper)

  Helper function to retrieve parcel tracking information from the 17TRACK API.

  async function getDelivery({ number, carrier }: Props) {
    const body = [
      {
        number,
        carrier: carrier ?? 0,
      },
    ];
  
    const res = await fetch(`${TRACKER_API_BASE_URL}/gettrackinfo`, {
      method: "POST",
      headers: {
        "17token": apiToken,
        "Content-Type": "application/json",
        "User-Agent": USER_AGENT,
      },
      body: JSON.stringify(body),
    });
  
    return res.json();