caisse-enregistreuse-mcp-server

Instructions

Implementation Reference

• src/tools/data.ts:130-130 (registration)

  Registers the 'data_list_delivery_zones' tool using the registerSimple helper function, specifying the backend PHP endpoint '/workers/getDeliveryZones.php' and translation keys for title and description.

  registerSimple(server, 'data_list_delivery_zones', '/workers/getDeliveryZones.php', t('tools.data_list_delivery_zones.description'), t('tools.data_list_delivery_zones.title'));

• src/tools/data.ts:90-114 (handler)

  Handler logic executed for the tool: authenticates via resolveAuth, fetches data from the specified PHP endpoint using the 'get' HTTP utility with shop credentials and format parameter, logs the result, processes with structData, and returns structured content or error message.

  async ({ format }: CommonArgs, ctx: Ctx) => {
      try {
          const { shopId, apiKey } = resolveAuth(undefined, ctx);
          const data = await get(path, { idboutique: shopId, key: apiKey, format });
  
          process.stderr.write(
              `[caisse][tool:${toolName}] ok type=${Array.isArray(data) ? 'array' : typeof data}`
              + (Array.isArray(data) ? ` len=${data.length}` : '')
              + '\n'
          );
          //Array.isArray(data) ? data.slice(0, 50) : data
          const funcResult = structData( data);
          process.stderr.write(`[caisse][RES]  ${JSON.stringify(data)} \n`);
          process.stderr.write(`[caisse][RES] funcResult ${JSON.stringify(funcResult)} \n`);
          return funcResult;
          //return { content, structuredContent: isText ? undefined : data };
      } catch (e) {
          process.stderr.write(`[caisse][tool:${toolName}][error]\n`);
          process.stderr.write(`[caisse][tool:${toolName}][error] ${(e as Error).message}\n`);
          // renvoyer un message "propre" plutôt que laisser l’exception devenir un 424
          return {
              content: [{ type: 'text', text: `Erreur pendant la préparation de la réponse: ${(e as Error).message}` }],
              is_error: true,
          };
      }

• src/tools/data.ts:11-13 (schema)

  Shared Zod input schema for simple data list tools, allowing optional 'format' parameter (json/csv/html, defaults to json). Used in the tool's inputSchema.

  const CommonShape = {
      format: z.enum(['json', 'csv', 'html']).default('json'),
  } satisfies Record<string, ZodTypeAny>;

• src/tools/data.ts:52-73 (helper)

  Helper function to format tool response: creates a text preview (truncated if large) and wraps data in structuredContent for MCP compliance.

  function structData(data: any) {
      // on ne touche PAS à structuredContent (c’est ce que ChatGPT utilise)
      const light = Array.isArray(data)
          ? data.slice(0, 5000)//.map(({ id, nom, email, tel, ...r }) => ({ id, nom, email, tel }))
          : data;
  
      const maxLength = 40000;
      const preview =
          typeof light === 'string'
              ? (light.length > maxLength ? light.slice(0, maxLength) + '…(truncated)' : light)
              : safeStringify(light, 2, maxLength);   // <-- aperçu court et “safe”
      const wrapped =
          Array.isArray(data)
              ? { data: data }
              : data && typeof data === 'object'
                  ? data
                  : { data: data };
      return {
          content: [{ type: 'text', text: preview }],
          structuredContent: wrapped,
      };
  }

• src/tools/data.ts:75-117 (helper)

  Helper function that registers simple data-listing tools: defines schema, title/description, and generic handler that calls a PHP endpoint.

  function registerSimple(
      server: McpServer | any,
      toolName: string,
      path: string,
      title: string,
      entityLabel: string
  ) {
      server.registerTool(
          toolName,
          {
              title,
              description: `Liste des ${entityLabel}`,
              inputSchema: CommonShape, // ZodRawShape,
              annotations: { readOnlyHint: true }
          },
          async ({ format }: CommonArgs, ctx: Ctx) => {
              try {
                  const { shopId, apiKey } = resolveAuth(undefined, ctx);
                  const data = await get(path, { idboutique: shopId, key: apiKey, format });
  
                  process.stderr.write(
                      `[caisse][tool:${toolName}] ok type=${Array.isArray(data) ? 'array' : typeof data}`
                      + (Array.isArray(data) ? ` len=${data.length}` : '')
                      + '\n'
                  );
                  //Array.isArray(data) ? data.slice(0, 50) : data
                  const funcResult = structData( data);
                  process.stderr.write(`[caisse][RES]  ${JSON.stringify(data)} \n`);
                  process.stderr.write(`[caisse][RES] funcResult ${JSON.stringify(funcResult)} \n`);
                  return funcResult;
                  //return { content, structuredContent: isText ? undefined : data };
              } catch (e) {
                  process.stderr.write(`[caisse][tool:${toolName}][error]\n`);
                  process.stderr.write(`[caisse][tool:${toolName}][error] ${(e as Error).message}\n`);
                  // renvoyer un message "propre" plutôt que laisser l’exception devenir un 424
                  return {
                      content: [{ type: 'text', text: `Erreur pendant la préparation de la réponse: ${(e as Error).message}` }],
                      is_error: true,
                  };
              }
          }
      );
  }