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