tracking-delivery

Track parcel delivery status using a tracking number, with automatic or manual carrier detection via 17TRACK.

Instructions

Track a parcel delivery via 17TRACK

Input Schema

TableJSON Schema

Name	Required	Description	Default
`number`	Yes	The tracking number of the parcel
`carrier`	No	Carrier ID (number). If omitted, 17TRACK will auto-detect, but accuracy may be lower.

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();

Parcel Tracking MCP Server