@payware/mcp-server 1.3.2 → 1.4.0

package/src/shared/poi/poi-create-api.js

@@ -3,6 +3,7 @@ import { createAuthHeaders } from '../auth-headers.js';
 import { apiErrorResult } from '../api-errors.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+import { CREATES } from '../tool-annotations.js';
 
 /**
  * Creating POIs (Points of Interaction) - the physical payment points a payer scans.
@@ -206,6 +207,7 @@ export function buildCreatePOITool({ partnerType, resolveAuth }) {
 
   return {
     name: 'payware_poi_create',
+    annotations: CREATES,
     description: `Create a single POI (Point of Interaction) - a physical payment point a payer scans.
 
 **Endpoint:** POST /poi -> 201 Created
@@ -241,7 +243,7 @@ ${isIsv ? `
         },
         callbackUrl: {
           type: 'string',
-          description: 'HTTPS URL for POI events. Must present a publicly-trusted TLS certificate and resolve to a public address.',
+          description: 'HTTPS URL for this POI\'s callbacks: poi.scanned (with the new transaction id), poi.expired (price not scanned) and the sale\'s TRANSACTION_FINALIZED (final status, with poiId). Signed by the ISV that set the price, otherwise the merchant. A POI without one sends no callbacks - there is no per-price callback URL. Must present a publicly-trusted TLS certificate and resolve to a public address.',
           format: 'uri'
         },
         useSandbox: {
@@ -296,6 +298,7 @@ export function buildCreatePOIBatchTool({ partnerType, resolveAuth }) {
 
   return {
     name: 'payware_poi_create_batch',
+    annotations: CREATES,
     description: `Create up to ${MAX_POI_BATCH_SIZE} POIs in a single **atomic** call - the tool for rolling out a terminal estate.
 
 **Endpoint:** POST /poi/batch -> 201 Created, returning \`{ created, pois: [...] }\`

package/src/shared/products/products-api.js

@@ -802,35 +802,46 @@ export async function updateAudio({
     throw new Error('audioId is required');
   }
 
-  const requestBody = {};
-
-  if (title !== undefined) requestBody.title = title;
-  if (newProductId !== undefined) requestBody.productId = newProductId;
+  // PATCH is metadata only. The server refuses a different productId there with
+  // ERR_AUDIO_REASSIGN_FORBIDDEN and moves an audio through POST .../{id}/transfer instead
+  // (AudioService.update), so a rename and a move are two calls. The rename goes first: if the move
+  // is then refused, the title the caller asked for is still applied.
+  const move = newProductId !== undefined && newProductId !== productId;
+  if (title === undefined && !move) {
+    throw new Error('Nothing to update: provide a title, or a newProductId different from productId');
+  }
 
-  const minimizedBody = createMinimizedJSON(requestBody);
-  const headers = await createAuthHeaders(partnerType, { ...authParams, requestBody: minimizedBody });
   const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+  const audioUrl = `${baseUrl}/products/${productId}/audios/${audioId}`;
+
+  const send = async (method, url, requestBody, operation) => {
+    const minimizedBody = createMinimizedJSON(requestBody);
+    const headers = await createAuthHeaders(partnerType, { ...authParams, requestBody: minimizedBody });
+    try {
+      const response = await axios[method](url, minimizedBody, { headers });
+      return {
+        success: true,
+        data: response.data,
+        requestInfo: {
+          url,
+          method: method.toUpperCase(),
+          requestBody: minimizedBody,
+          statusCode: response.status
+        }
+      };
+    } catch (error) {
+      throw describeApiError(error, operation);
+    }
+  };
 
-  try {
-    const response = await axios.patch(
-      `${baseUrl}/products/${productId}/audios/${audioId}`,
-      minimizedBody,
-      { headers }
-    );
-
-    return {
-      success: true,
-      data: response.data,
-      requestInfo: {
-        url: `${baseUrl}/products/${productId}/audios/${audioId}`,
-        method: 'PATCH',
-        requestBody: minimizedBody,
-        statusCode: response.status
-      }
-    };
-  } catch (error) {
-    throw describeApiError(error, 'update audio');
+  let result;
+  if (title !== undefined) {
+    result = await send('patch', audioUrl, { title }, 'update audio');
+  }
+  if (move) {
+    result = await send('post', `${audioUrl}/transfer`, { targetProductId: newProductId }, 'transfer audio');
   }
+  return result;
 }
 
 /**

package/src/shared/shops/shops-api.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createAuthHeaders } from '../auth-headers.js';
 import { apiErrorResult } from '../api-errors.js';
 import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+import { READS } from '../tool-annotations.js';
 
 /**
  * Shops - the merchant outlets a transaction, product or POI belongs to.
@@ -48,6 +49,7 @@ export function buildListShopsTool({ partnerType, resolveAuth }) {
 
   return {
     name: 'payware_shops_list',
+    annotations: READS,
     description: `List the merchant outlets (shops) the caller can act on.
 
 **Endpoint:** GET /shops

package/src/shared/tool-annotations.js

@@ -0,0 +1,53 @@
+/**
+ * MCP tool annotations, as the six combinations this server's tools actually fall into.
+ *
+ * Annotations are hints a client uses to decide how much to ask the user before running a tool: a
+ * read can run unattended, a destructive call should be confirmed, a non-idempotent one should not
+ * be retried blindly after a timeout. Every tool declares one of these as `annotations`, and
+ * tests/tool-contract.test.js fails on a tool that does not. tests/tool-routes.test.js checks the
+ * choice against the route the tool calls, so a GET cannot be declared destructive or a DELETE
+ * read-only.
+ *
+ * All four hints are always set. The protocol defaults are the cautious ones (not read-only,
+ * destructive, open world), so a tool that left them out would be presented as more dangerous than
+ * it is, and a directory that lists servers requires them to be explicit.
+ *
+ * "Open world" means the tool reaches the payware API, and through it real payers, merchants and
+ * money. The local tools - keys, tokens, code samples, formatting, callback simulation - do not.
+ */
+
+/** Computes something locally and calls nothing. */
+export const LOCAL = Object.freeze({
+  readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
+});
+
+/** Reads from the payware API and changes nothing. */
+export const READS = Object.freeze({
+  readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true
+});
+
+/**
+ * Adds something that a repeat call returns rather than adds again: a shareable link, which the
+ * server mints on first request and records on the transaction, or a downloaded file saved locally.
+ */
+export const ADDS = Object.freeze({
+  readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true
+});
+
+/** Creates something new each time it is called: a transaction, a product, a report run. */
+export const CREATES = Object.freeze({
+  readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true
+});
+
+/** Overwrites, cancels or deletes. Repeating it changes nothing further. */
+export const CHANGES = Object.freeze({
+  readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true
+});
+
+/**
+ * Moves a payment forward irreversibly: processing it as the payer, or finalizing it as the
+ * institution. A retry after a timeout must not be automatic - the first call may have landed.
+ */
+export const COMMITS = Object.freeze({
+  readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true
+});

package/src/tools/advanced-code-generator.js

@@ -19,6 +19,7 @@
 import { CommonTemplates } from '../utils/code-examples/common/helpers.js';
 import { AuthGenerators } from '../utils/code-examples/common/auth-examples.js';
 import { createDeterministicJSON } from '../core/utils/json-serializer.js';
+import { LOCAL } from '../shared/tool-annotations.js';
 
 /**
  * Advanced payware Code Generator
@@ -324,22 +325,21 @@ class AdvancedCodeGenerator {
    */
   generateAuthenticationExample(language, partnerType, options) {
     const AuthGen = AuthGenerators[language];
-    if (AuthGen) {
-      const generator = new AuthGen();
-      const envTemplate = generator.getEnvironmentTemplate(partnerType, options);
-      const depsTemplate = generator.getDependenciesTemplate(options);
-      const authTemplate = generator.getAuthTemplate(partnerType, options);
-
-      return this.wrapCompleteExample(
-        `${envTemplate}\n\n${depsTemplate}\n\n${authTemplate}`,
-        'Authentication Setup',
-        language,
-        partnerType,
-        options
-      );
-    } else {
-      return this.generateBasicAuthExample(language, partnerType, options);
+    if (!AuthGen) {
+      throw new Error(`No authentication generator for language: ${language}`);
     }
+    const generator = new AuthGen();
+    const envTemplate = generator.getEnvironmentTemplate(partnerType, options);
+    const depsTemplate = generator.getDependenciesTemplate(options);
+    const authTemplate = generator.getAuthTemplate(partnerType, options);
+
+    return this.wrapCompleteExample(
+      `${envTemplate}\n\n${depsTemplate}\n\n${authTemplate}`,
+      'Authentication Setup',
+      language,
+      partnerType,
+      options
+    );
   }
 
   /**
@@ -1455,256 +1455,6 @@ echo "✅ Request completed"`;
     return this.wrapCodeExample(code, opDef.description, 'bash', partnerType, options);
   }
 
-
-  generateBasicAuthExample(language, partnerType, options) {
-    const { includeComments = true } = options;
-
-    const authExamples = {
-      python: `${includeComments ? '# Basic Authentication Setup - Python' : ''}
-import jwt
-import json
-import hashlib
-import base64
-from datetime import datetime, timezone
-
-def create_jwt_token(request_body=None):
-    ${includeComments ? '"""Create JWT token for payware API authentication"""' : ''}
-    partner_id = "YOUR_PARTNER_ID"
-    private_key = """-----BEGIN RSA PRIVATE KEY-----
-YOUR_PRIVATE_KEY_HERE
------END RSA PRIVATE KEY-----"""
-
-    # Create content SHA-256 for request body
-    content_sha256 = ""
-    if request_body:
-        content_sha256 = base64.b64encode(hashlib.sha256(request_body.encode()).digest()).decode()
-
-    # JWT payload
-    payload = {
-        "iss": partner_id,
-        "aud": "payware.eu",
-        "iat": int(datetime.now(timezone.utc).timestamp()),
-        "exp": int(datetime.now(timezone.utc).timestamp()) + 300,
-        "contentSha256": content_sha256
-    }
-
-    # Create JWT token
-    token = jwt.encode(payload, private_key, algorithm="RS256")
-    return token
-
-${includeComments ? '# Example usage' : ''}
-token = create_jwt_token()
-print(f"JWT Token: {token}")`,
-
-      nodejs: `${includeComments ? '// Basic Authentication Setup - Node.js' : ''}
-const jwt = require('jsonwebtoken');
-const crypto = require('crypto');
-
-function createJWTToken(requestBody = null) {
-    /**
-     * Create JWT token for payware API authentication
-     */
-    const partnerId = "YOUR_PARTNER_ID";
-    const privateKey = \`-----BEGIN RSA PRIVATE KEY-----
-YOUR_PRIVATE_KEY_HERE
------END RSA PRIVATE KEY-----\`;
-
-    ${includeComments ? '// Create content SHA-256' : ''} for request body
-    let contentSha256 = "";
-    if (requestBody) {
-        contentSha256 = crypto.createHash('sha256').update(requestBody).digest('base64');
-    }
-
-    // JWT payload
-    const payload = {
-        iss: partnerId,
-        aud: "payware.eu",
-        iat: Math.floor(Date.now() / 1000),
-        exp: Math.floor(Date.now() / 1000) + 300,
-        contentSha256: contentSha256
-    };
-
-    // Create JWT token
-    const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });
-    return token;
-}
-
-${includeComments ? '// Example usage' : ''}
-const token = createJWTToken();
-console.log(\`JWT Token: \${token}\`);`,
-
-      java: `${includeComments ? '// Basic Authentication Setup - Java' : ''}
-import io.jsonwebtoken.Jwts;
-import io.jsonwebtoken.SignatureAlgorithm;
-import java.security.PrivateKey;
-import java.security.spec.PKCS8EncodedKeySpec;
-import java.security.KeyFactory;
-import java.util.Date;
-import java.util.Map;
-import java.util.HashMap;
-import java.security.MessageDigest;
-import java.util.Base64;
-
-public class PaywareAuth {
-
-    private static String createJWTToken(String requestBody) {
-        try {
-            String partnerId = "YOUR_PARTNER_ID";
-            String privateKeyPEM = "-----BEGIN RSA PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_HERE\\n-----END RSA PRIVATE KEY-----";
-
-            ${includeComments ? '// Create content SHA-256' : ''}
-            String contentSha256 = "";
-            if (requestBody != null) {
-                MessageDigest md = MessageDigest.getInstance("SHA-256");
-                byte[] digest = md.digest(requestBody.getBytes());
-                contentSha256 = Base64.getEncoder().encodeToString(digest);
-            }
-
-            // JWT payload
-            Map<String, Object> claims = new HashMap<>();
-            claims.put("iss", partnerId);
-            claims.put("aud", "payware.eu");
-            claims.put("iat", new Date().getTime() / 1000);
-            claims.put("exp", (new Date().getTime() / 1000) + 300);
-            claims.put("contentSha256", contentSha256);
-
-            // Note: You'll need to implement private key loading
-            // PrivateKey privateKey = loadPrivateKey(privateKeyPEM);
-
-            return "your-jwt-token"; // Placeholder - implement JWT creation
-
-        } catch (Exception e) {
-            throw new RuntimeException("Failed to create JWT token", e);
-        }
-    }
-
-    public static void main(String[] args) {
-        String token = createJWTToken(null);
-        System.out.println("JWT Token: " + token);
-    }
-}`,
-
-      csharp: `${includeComments ? '// Basic Authentication Setup - C#' : ''}
-using System;
-using System.Text;
-using System.Security.Cryptography;
-using Microsoft.IdentityModel.Tokens;
-using System.IdentityModel.Tokens.Jwt;
-using System.Security.Claims;
-
-public class PaywareAuth
-{
-    private static string CreateJWTToken(string requestBody = null)
-    {
-        var partnerId = "YOUR_PARTNER_ID";
-        var privateKeyPEM = @"-----BEGIN RSA PRIVATE KEY-----
-YOUR_PRIVATE_KEY_HERE
------END RSA PRIVATE KEY-----";
-
-        ${includeComments ? '// Create content SHA-256' : ''}
-        var contentSha256 = "";
-        if (!string.IsNullOrEmpty(requestBody))
-        {
-            using (var sha256 = SHA256.Create())
-            {
-                var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(requestBody));
-                contentSha256 = Convert.ToBase64String(hash);
-            }
-        }
-
-        // JWT payload
-        var claims = new[]
-        {
-            new Claim("iss", partnerId),
-            new Claim("aud", "payware.eu"),
-            new Claim("iat", DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer),
-            new Claim("exp", DateTimeOffset.UtcNow.AddMinutes(5).ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer),
-            new Claim("contentSha256", contentSha256)
-        };
-
-        // Note: You'll need to implement RSA key loading
-        // var rsa = RSA.Create();
-        // rsa.ImportFromPem(privateKeyPEM);
-        // var key = new RsaSecurityKey(rsa);
-
-        return "your-jwt-token"; // Placeholder - implement JWT creation
-    }
-
-    public static void Main(string[] args)
-    {
-        var token = CreateJWTToken();
-        Console.WriteLine($"JWT Token: {token}");
-    }
-}`,
-
-      php: `${includeComments ? '<?php // Basic Authentication Setup - PHP' : '<?php'}
-require_once 'vendor/autoload.php';
-use Firebase\\JWT\\JWT;
-use Firebase\\JWT\\Key;
-
-function createJWTToken($requestBody = null) {
-    $partnerId = "YOUR_PARTNER_ID";
-    $privateKey = "-----BEGIN RSA PRIVATE KEY-----
-YOUR_PRIVATE_KEY_HERE
------END RSA PRIVATE KEY-----";
-
-    ${includeComments ? '// Create content SHA-256' : ''}
-    $contentSha256 = "";
-    if ($requestBody !== null) {
-        $contentSha256 = base64_encode(hash('sha256', $requestBody, true));
-    }
-
-    // JWT payload
-    $payload = [
-        'iss' => $partnerId,
-        'aud' => 'payware.eu',
-        'iat' => time(),
-        'exp' => time() + 300,
-        'contentSha256' => $contentSha256
-    ];
-
-    // Create JWT token
-    $token = JWT::encode($payload, $privateKey, 'RS256');
-    return $token;
-}
-
-${includeComments ? '// Example usage' : ''}
-$token = createJWTToken();
-echo "JWT Token: " . $token . "\\n";
-?>`,
-
-      curl: `${includeComments ? '#!/bin/bash\n# Basic Authentication Setup - cURL' : '#!/bin/bash'}
-
-# Configuration
-PARTNER_ID="YOUR_PARTNER_ID"
-PRIVATE_KEY_FILE="path/to/private-key.pem"
-
-# Function to create JWT token (simplified)
-create_jwt_token() {
-    local request_body="\$1"
-    local content_sha256=""
-
-    if [ -n "\$request_body" ]; then
-        content_sha256=\$(echo -n "\$request_body" | openssl dgst -sha256 -binary | base64)
-    fi
-
-    echo "your-jwt-token" # Placeholder - implement JWT creation with openssl
-}
-
-${includeComments ? '# Example usage' : ''}
-JWT_TOKEN=\$(create_jwt_token)
-echo "JWT Token: \$JWT_TOKEN"`
-    };
-
-    return this.wrapCodeExample(
-      authExamples[language] || authExamples.python,
-      'Authentication Setup',
-      language,
-      partnerType,
-      options
-    );
-  }
-
   // Helper methods for Java code generation
   toPascalCase(str) {
     return str.split(/[-_]/).map(word =>
@@ -1986,6 +1736,7 @@ export const advancedCodeGenerator = new AdvancedCodeGenerator();
  */
 export const generateCodeExampleTool = {
   name: 'payware_generate_code_example',
+  annotations: LOCAL,
   description: 'Generate production-ready payware API integration code examples with authentication, error handling, and environment configuration for any operation across 16 supported operations and 6 programming languages.',
 
   inputSchema: {
@@ -2126,6 +1877,7 @@ Use different parameters to explore all available options!
  */
 export const generateDocumentationTool = {
   name: 'payware_generate_documentation',
+  annotations: LOCAL,
   description: 'Generate comprehensive documentation for payware API integration with quick start instructions, authentication flows, operation examples, error handling patterns, and language-specific integration guides.',
 
   inputSchema: {

package/src/utils/code-examples/common/auth-examples.js

@@ -68,7 +68,7 @@ from cryptography.hazmat.primitives import serialization`;
     ${options.includeComments ? '# Create JWT payload\n    ' : ''}payload = {
         'iss': partner_id,
         'aud': 'https://payware.eu',
-        'iat': int(datetime.utcnow().timestamp())
+        'iat': int(datetime.now().timestamp())
     }
 
     ${options.includeComments ? '# Create and return token\n    ' : ''}token = jwt.encode(payload, private_key, algorithm='RS256', headers=header)

package/src/utils/code-examples/isv/products.js

@@ -295,7 +295,7 @@ def create_isv_jwt_token(merchant_partner_id, oauth2_token, request_body=None, u
         'iss': isv_partner_id,           # ISV Partner ID
         'aud': merchant_partner_id,      # Target Merchant ID
         'sub': oauth2_token,             # OAuth2 access token
-        'iat': int(datetime.utcnow().timestamp())
+        'iat': int(datetime.now().timestamp())
     }
 
     # Create and return token

package/src/utils/code-examples/isv/transactions.js

@@ -217,7 +217,7 @@ def create_isv_jwt_token(merchant_partner_id, oauth2_token, request_body=None, u
         'iss': config['isv_partner_id'],      # ISV Partner ID
         'aud': merchant_partner_id,           # Target Merchant ID
         'sub': oauth2_token,                  # OAuth2 access token
-        'iat': int(datetime.utcnow().timestamp())
+        'iat': int(datetime.now().timestamp())
     }
 
     # Create token

package/src/utils/code-examples/merchant/transactions.js

@@ -171,7 +171,7 @@ def create_jwt_token(request_body=None, use_sandbox=True):
     payload = {
         'iss': config['partner_id'],
         'aud': 'https://payware.eu',
-        'iat': int(datetime.utcnow().timestamp())
+        'iat': int(datetime.now().timestamp())
     }
 
     # Create token

package/src/utils/format-request.js

@@ -3,6 +3,7 @@
  */
 
 import { createMinimizedJSON } from '../core/utils/json-serializer.js';
+import { LOCAL } from '../shared/tool-annotations.js';
 
 /**
  * Format transaction request data
@@ -165,6 +166,7 @@ export function formatCurlCommand(method, endpoint, headers, body = null) {
  */
 export const formatRequestTool = {
   name: "payware_utils_format_request",
+  annotations: LOCAL,
   description: "Format and validate payware API requests with proper structure and headers",
   inputSchema: {
     type: "object",

package/src/utils/json-formatter.js

@@ -5,12 +5,14 @@
 
 import { createDeterministicJSON, validateJSONConsistency } from '../core/utils/json-serializer.js';
 import { generateContentSha256 } from '../core/auth/jwt-token.js';
+import { LOCAL } from '../shared/tool-annotations.js';
 
 /**
  * Format JSON with deterministic serialization tool
  */
 export const formatJSONDeterministicTool = {
   name: "payware_utils_format_json_deterministic",
+  annotations: LOCAL,
   description: "Format JSON payload with deterministic key sorting for consistent SHA-256 calculation and payware API compliance",
   inputSchema: {
     type: "object",

package/src/utils/server-info.js

@@ -5,12 +5,14 @@
 import { readFileSync } from 'fs';
 import { getPartnerTypeSafe, getSandboxUrl, getProductionUrl } from '../config/env.js';
 import { getPartnerDisplayInfo, getPartnerConfig } from '../config/partner-types.js';
+import { LOCAL } from '../shared/tool-annotations.js';
 
 /**
  * Get server information tool implementation
  */
 export const getServerInfoTool = {
   name: "payware_utils_server_info",
+  annotations: LOCAL,
   description: "Get MCP server version, status, and environment information",
   inputSchema: {
     type: "object",