W3Ship MCP Server

Instructions

Implementation Reference

• src/index.ts:379-406 (handler)

  The tool 'ship_address' forwards an identity lookup request to the centralized W3Ship API for verification and address retrieval.

  case "ship_address": {
      // Forward the identity lookup to the centralized W3Ship API.
      // Signature verification and DB lookup happen server-side.
      const { publicKey, signature, timestamp } = args as any;
  
      if (!publicKey || !signature || !timestamp) {
          return { content: [{ type: 'text', text: 'Error: publicKey, signature, and timestamp are all required.' }], isError: true };
      }
  
      const identityRes = await fetch(`${W3SHIP_API}/api/identity`, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ publicKey, signature, timestamp }),
      });
  
      const identityData = await identityRes.json();
  
      if (!identityRes.ok) {
          return {
              content: [{ type: 'text', text: `Error: ${identityData.error || 'Identity lookup failed'}${identityData.details ? ' — ' + identityData.details : ''}` }],
              isError: true,
          };
      }
  
      return {
          content: [{ type: 'text', text: JSON.stringify(identityData, null, 2) }],
      };
  }

• src/index.ts:51-63 (registration)

  Tool registration for 'ship_address' in the listTools handler.

  {
      name: "ship_address",
      description: "Securely retrieve a physical address using a public key and a timed cryptographic signature.",
      inputSchema: {
          type: "object",
          properties: {
              publicKey: { type: "string", description: "The hex-encoded public key to lookup." },
              signature: { type: "string", description: "The hex-encoded signature of the timestamp." },
              timestamp: { type: "number", description: "The current Unix timestamp in milliseconds." },
          },
          required: ["publicKey", "signature", "timestamp"],
      },
  },