@payware/mcp-server 1.3.3 → 1.5.0

package/.env.example

@@ -26,6 +26,10 @@ PAYWARE_SANDBOX_URL=https://sandbox.payware.eu/api
 # Production base URL (Optional - defaults to https://api.payware.eu/api)
 PAYWARE_PRODUCTION_URL=https://api.payware.eu/api
 
+# Toolsets to load (Optional - unset loads every tool), comma-separated:
+# auth, transactions, products, placements, deep_links, data, logs, poi, shops, onboarding, utils
+# PAYWARE_MCP_TOOLSETS=products,placements
+
 # =============================================================================
 # ISV-SPECIFIC CONFIGURATION (Only when PAYWARE_PARTNER_TYPE=isv)
 # =============================================================================

package/README.md

@@ -40,6 +40,14 @@ Releases are published to npm as `@payware/mcp-server` and to the official [MCP
 - **Get QR Code**: Generate QR code for POI payments
 - **List POIs**: List all POIs for a merchant
 
+### 📣 Campaign, Placement and Airing Tools
+For merchants, and for ISVs acting for them. Changes need the merchant's PRM plan; reading works on every plan.
+- **Placements**: Distribute a product through posters, TV spots, packaging, links or tags, each with its own `pl` ID, so every payment it starts is attributed to it. Includes the QR code, barcode and short link of each placement
+- **Campaigns**: Group placements, across products, and read their combined results
+- **Airing Rules**: Schedule when a placement is on air, with recurrences, time windows and time zones, and replace a whole schedule in one call
+- **Airing Calendar**: Every airing across all products in a time range
+- **Results**: Offers shown, payments started and confirmed, and confirmed amounts per placement or campaign
+
 ### 📋 Logs Tools (Premium)
 - **Query Logs**: Search and filter application logs by level, logger, message content, and date range
 - **Log Status**: Check log availability and storage information
@@ -92,6 +100,16 @@ PAYWARE_SANDBOX_URL=https://sandbox.payware.eu/api
 
 ⚠️ **Security Note**: Never commit the `.env` file to version control. It contains sensitive credentials.
 
+#### Choosing toolsets
+
+Every tool definition goes into the assistant's context on every turn, and a merchant has over 70 of them. To offer only the groups you use, set `PAYWARE_MCP_TOOLSETS` to a comma-separated list:
+
+```env
+PAYWARE_MCP_TOOLSETS=products,placements
+```
+
+Toolsets: `auth`, `transactions`, `products`, `placements`, `deep_links`, `data`, `logs`, `poi`, `shops`, `onboarding`, `utils`. Unset, or `all`, loads every tool. An unknown name is ignored with a warning in the server log. A tool outside the chosen toolsets is neither listed nor callable; this narrows what the assistant is offered and does not change what your partner account may do. An ISV that obtains OAuth2 tokens through this server includes `auth`.
+
 ### 3. Start the MCP Server
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payware/mcp-server",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "mcpName": "io.github.payware/mcp-server",
   "description": "Official MCP server for payware payment API integration",
   "main": "src/index.js",
@@ -15,19 +15,17 @@
     "proxy:dev": "node --watch src/proxy-server.js",
     "bridge": "node src/mcp-proxy.js",
     "inspector": "npx @modelcontextprotocol/inspector node src/mcp-proxy.js",
-    "test": "node --test tests/api-errors.test.js tests/json-serializer.test.js tests/request-contract.test.js tests/tool-contract.test.js",
-    "test:watch": "node --test --watch tests/api-errors.test.js tests/json-serializer.test.js tests/request-contract.test.js tests/tool-contract.test.js",
+    "test": "node --test tests/api-errors.test.js tests/json-serializer.test.js tests/proxy-server.test.js tests/request-contract.test.js tests/stdio-server.test.js tests/tool-contract.test.js tests/tool-routes.test.js tests/toolsets.test.js",
+    "test:watch": "node --test --watch tests/api-errors.test.js tests/json-serializer.test.js tests/proxy-server.test.js tests/request-contract.test.js tests/stdio-server.test.js tests/tool-contract.test.js tests/tool-routes.test.js tests/toolsets.test.js",
     "check": "node --check src/index.js && npm test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.5.0",
-    "axios": "^1.6.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "axios": "^1.20.0",
     "cors": "^2.8.5",
     "dotenv": "^17.2.2",
-    "express": "^5.1.0",
-    "http-proxy-middleware": "^3.0.5",
-    "jsonwebtoken": "^9.0.0",
-    "node-forge": "^1.3.1"
+    "express": "^5.2.1",
+    "jsonwebtoken": "^9.0.3"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/auth/rsa-keys.js

@@ -1,4 +1,5 @@
-import forge from 'node-forge';
+import { generateKeyPairSync } from 'crypto';
+import { LOCAL } from '../shared/tool-annotations.js';
 
 /**
  * Generate RSA key pair for payware API authentication
@@ -6,11 +7,15 @@ import forge from 'node-forge';
  * @returns {Object} Object containing publicKey and privateKey in PEM format
  */
 export function generateRSAKeyPair(keySize = 2048) {
-  const keyPair = forge.pki.rsa.generateKeyPair({ bits: keySize });
-  
-  const privateKeyPem = forge.pki.privateKeyToPem(keyPair.privateKey);
-  const publicKeyPem = forge.pki.publicKeyToPem(keyPair.publicKey);
-  
+  // node:crypto rather than node-forge, which was a dependency for this call alone. The encodings are
+  // the ones forge produced - PKCS#1 private ("BEGIN RSA PRIVATE KEY"), SPKI public - so the output
+  // reads the same; only forge's CRLF line endings become LF.
+  const { privateKey: privateKeyPem, publicKey: publicKeyPem } = generateKeyPairSync('rsa', {
+    modulusLength: keySize,
+    privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    publicKeyEncoding: { type: 'spki', format: 'pem' }
+  });
+
   return {
     privateKey: privateKeyPem,
     publicKey: publicKeyPem,
@@ -24,6 +29,7 @@ export function generateRSAKeyPair(keySize = 2048) {
  */
 export const generateRSAKeysTool = {
   name: "payware_authentication_generate_rsa_keys",
+  annotations: LOCAL,
   description: "Generate RSA key pair for payware API authentication",
   inputSchema: {
     type: "object",

package/src/auth/sandbox-setup.js

@@ -3,6 +3,7 @@
  */
 
 import { getPartnerIdSafe, getPrivateKeySafe } from '../config/env.js';
+import { LOCAL } from '../shared/tool-annotations.js';
 
 const SANDBOX_CONFIG = {
   baseUrl: 'https://sandbox.payware.eu/api',
@@ -90,6 +91,7 @@ export function generateSandboxConfig(partnerId, privateKey = null) {
  */
 export const setupSandboxAuthTool = {
   name: "payware_authentication_setup_sandbox_auth",
+  annotations: LOCAL,
   description: "Setup sandbox authentication configuration for payware API",
   inputSchema: {
     type: "object",

package/src/config/toolsets.js

@@ -0,0 +1,104 @@
+/**
+ * Toolsets: named groups of tools, so a client can load only what it needs.
+ *
+ * Every tool definition is sent in tools/list and from there into every prompt the client builds, so
+ * a merchant with 72 tools pays for all of them on every turn whether it uses them or not. Setting
+ * PAYWARE_MCP_TOOLSETS=products,placements loads those two groups and nothing else. Unset, every tool
+ * loads, as it always has.
+ *
+ * This narrows what the assistant is offered; it is not access control. What a call may do is still
+ * decided by payware for the configured partner.
+ *
+ * Toolsets are assigned by tool name, not by prefix alone: the placement and airing tools sit under
+ * payware_products_* because the API nests them under products, yet they are a separate concern.
+ * tests/tool-contract.test.js fails on a tool that belongs to no toolset, so a new tool family has to
+ * be placed here.
+ */
+
+/** Toolset name -> what it holds. The order is the order they are listed in messages. */
+export const TOOLSETS = {
+  auth: 'Keys, JWTs and, for ISVs, OAuth2 tokens',
+  transactions: 'Create, process, finalize, cancel and look up transactions, and simulate callbacks',
+  products: 'Products, price schedules, audio and product images',
+  placements: 'Campaigns, placements, airing rules and the airing calendar',
+  deep_links: 'Shareable links for transactions and products',
+  data: 'Reports and exports',
+  logs: 'API logs (Premium)',
+  poi: 'Points of interaction (ISV)',
+  shops: 'Shop codes',
+  onboarding: 'ISV merchant invitations and the reference data their forms need',
+  utils: 'Code samples, documentation, request formatting and server information'
+};
+
+const BY_PREFIX = [
+  ['payware_authentication_', 'auth'],
+  ['payware_authorization_', 'auth'],
+  ['payware_operations_', 'transactions'],
+  ['payware_products_', 'products'],
+  ['payware_deep_links_', 'deep_links'],
+  ['payware_data_', 'data'],
+  ['payware_logs_', 'logs'],
+  ['payware_poi_', 'poi'],
+  ['payware_shops_', 'shops'],
+  ['payware_isv_', 'onboarding'],
+  ['payware_reference_', 'onboarding'],
+  ['payware_utils_', 'utils'],
+  ['payware_generate_', 'utils']
+];
+
+/**
+ * The toolset a tool belongs to, or null for a name no rule covers.
+ * @param {string} name tool name
+ * @returns {string|null}
+ */
+export function toolsetOf(name) {
+  if (name.startsWith('payware_campaigns_') || /^payware_products_.*(placement|airing)/.test(name)) {
+    return 'placements';
+  }
+  const match = BY_PREFIX.find(([prefix]) => name.startsWith(prefix));
+  return match ? match[1] : null;
+}
+
+/**
+ * Narrow a role's tools to the toolsets named in `setting` (PAYWARE_MCP_TOOLSETS).
+ *
+ * Unset, blank or containing `all`: every tool. Names are case-insensitive and may use a hyphen for
+ * the underscore. An unknown name is ignored with a warning, and when no known name is left every
+ * tool loads, because a typo that silently served no tools would look like a broken server. A known
+ * toolset with no tools for this role is a warning too, not an error.
+ *
+ * @param {Array} tools the role's tools
+ * @param {string|undefined} setting the PAYWARE_MCP_TOOLSETS value
+ * @returns {{tools: Array, selected: string[]|null, warnings: string[]}} selected is null when all load
+ */
+export function filterToolsets(tools, setting) {
+  const names = String(setting ?? '')
+    .split(',')
+    .map(s => s.trim().toLowerCase().replace(/-/g, '_'))
+    .filter(Boolean);
+
+  if (names.length === 0 || names.includes('all')) {
+    return { tools, selected: null, warnings: [] };
+  }
+
+  const known = Object.keys(TOOLSETS);
+  const warnings = [];
+  const unknown = names.filter(n => !known.includes(n));
+  if (unknown.length > 0) {
+    warnings.push(`PAYWARE_MCP_TOOLSETS: unknown toolset ${unknown.join(', ')} ignored. Known: ${known.join(', ')}, or all.`);
+  }
+
+  const selected = known.filter(n => names.includes(n));
+  if (selected.length === 0) {
+    warnings.push('PAYWARE_MCP_TOOLSETS names no known toolset, so every tool is loaded.');
+    return { tools, selected: null, warnings };
+  }
+
+  const kept = tools.filter(t => selected.includes(toolsetOf(t.name)));
+  for (const set of selected) {
+    if (!kept.some(t => toolsetOf(t.name) === set)) {
+      warnings.push(`PAYWARE_MCP_TOOLSETS: toolset ${set} has no tools for this partner type.`);
+    }
+  }
+  return { tools: kept, selected, warnings };
+}

package/src/core/auth/jwt-factory.js

@@ -119,7 +119,10 @@ async function createJWTTokenWithCustomPayload(payload, privateKey, requestBody)
   // Add contentSha256 to header if request body exists (SHA-256 is preferred over MD5)
   if (requestBody) {
     const { createMinimizedJSON } = await import('../utils/json-serializer.js');
-    const bodyString = createMinimizedJSON(requestBody);
+    // A string IS the body, byte for byte - the caller serialized it once and sends exactly that.
+    // Serializing it again hashed a JSON string literal of the body, so every ISV write that passed
+    // its body as a string was ERR_INVALID_CONTENT_HASH. createJWTToken has always made this split.
+    const bodyString = typeof requestBody === 'string' ? requestBody : createMinimizedJSON(requestBody);
     header.contentSha256 = crypto.default.createHash('sha256').update(bodyString, 'utf8').digest('base64');
   }
 

package/src/core/auth/jwt-token.js

@@ -3,6 +3,7 @@ import crypto from 'crypto';
 import { normalizePrivateKey, getKeyInfo } from '../utils/key-utils.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { createDeterministicJSON } from '../utils/json-serializer.js';
+import { LOCAL } from '../../shared/tool-annotations.js';
 
 /**
  * Generate SHA-256 hash for JWT contentSha256 header (PREFERRED)
@@ -132,6 +133,7 @@ const IAT_MAX_FUTURE_SKEW_SECONDS = 60;
 
 export const validateJWTTokenTool = {
   name: "payware_authentication_validate_jwt",
+  annotations: LOCAL,
   description: "Validate and debug a payware JWT: decode header and payload, check the claims against the API's rules (algorithm, audience including the ISV on-behalf form, 5-minute freshness), and verify the contentSha256 hash against the request body when one is given",
   inputSchema: {
     type: "object",
@@ -374,6 +376,7 @@ ${issues.some(i => i.includes('hash mismatch')) ? '- Use deterministic JSON seri
  */
 export const testJWTTokenTool = {
   name: "payware_authentication_test_jwt",
+  annotations: LOCAL,
   description: "Test JWT token creation process with detailed step-by-step breakdown, showing deterministic JSON serialization, SHA-256 hash calculation, and final JWT structure",
   inputSchema: {
     type: "object",
@@ -604,6 +607,7 @@ ${deterministicJson}
  */
 export const createJWTTokenTool = {
   name: "payware_authentication_create_jwt_token",
+  annotations: LOCAL,
   description: "Create JWT token for payware API authentication according to official documentation",
   inputSchema: {
     type: "object",

package/src/index.js

@@ -18,6 +18,7 @@ import {
 // Import partner type and configuration
 import { getPartnerTypeSafe, getPartnerType } from './config/env.js';
 import { getPartnerConfig, getPartnerDisplayInfo } from './config/partner-types.js';
+import { filterToolsets } from './config/toolsets.js';
 
 // Import tool registries
 import { getSharedTools } from './shared/index.js';
@@ -71,11 +72,13 @@ class PaywareMCPServer {
         allTools = getMerchantTools();
     }
 
-    // Only log in development mode to avoid interfering with MCP transport
-    // Debugging disabled to prevent MCP JSON-RPC protocol corruption
-    // These logs interfere with the MCP client communication
-    // console.log messages on stdout break the JSON-RPC protocol
-    return allTools;
+    // PAYWARE_MCP_TOOLSETS narrows the list; a filtered-out tool is not listed and cannot be called.
+    // Warnings go to stderr, which MCP clients keep in their server log, never to stdout.
+    const { tools, warnings } = filterToolsets(allTools, process.env.PAYWARE_MCP_TOOLSETS);
+    for (const warning of warnings) {
+      process.stderr.write(`Warning: ${warning}\n`);
+    }
+    return tools;
   }
 
   setupToolHandlers() {
@@ -90,7 +93,8 @@ class PaywareMCPServer {
         tools: this.tools.map(tool => ({
           name: tool.name,
           description: `[${this.partnerInfo.name}] ${tool.description}`,
-          inputSchema: tool.inputSchema
+          inputSchema: tool.inputSchema,
+          annotations: tool.annotations
         }))
       };
     });

package/src/isv/data/index.js

@@ -19,10 +19,12 @@ import {
   LOCALES
 } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 // Create ISV data tool factory
-const createISVDataTool = (toolName, apiFunction, description, additionalParams = {}) => ({
+const createISVDataTool = (toolName, apiFunction, description, additionalParams = {}, annotations) => ({
   name: `payware_data_${toolName}`,
+  annotations,
   description: `${description} (ISV acting on behalf of merchant)`,
   inputSchema: {
     type: "object",
@@ -43,8 +45,7 @@ const createISVDataTool = (toolName, apiFunction, description, additionalParams
       },
       privateKey: {
         type: "string",
-        description: "ISV RSA private key for authentication. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "ISV RSA private key for authentication. Uses environment-specific private key as default."
       },
       ...additionalParams
     },
@@ -104,6 +105,7 @@ ${JSON.stringify(result.data, null, 2)}
  */
 export const generateReportTool = {
   name: "payware_data_generate_report",
+  annotations: CREATES,
   description: "Generate an asynchronous data report for ISV data analysis and reporting on behalf of merchants. Production only - not supported in sandbox.",
   inputSchema: {
     type: "object",
@@ -156,8 +158,7 @@ export const generateReportTool = {
       },
       privateKey: {
         type: "string",
-        description: "ISV RSA private key for authentication. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "ISV RSA private key for authentication. Uses environment-specific private key as default."
       }
     },
     required: ["reportUnitId", "merchantPartnerId", "oauth2Token"]
@@ -232,7 +233,7 @@ This feature requires proper OAuth2 authorization from the merchant and is only
 };
 
 // Create all other ISV data tools
-export const listReportsTool = createISVDataTool('list_reports', listReports, 'List All Available Reports', {});
+export const listReportsTool = createISVDataTool('list_reports', listReports, 'List All Available Reports', {}, READS);
 
 export const getReportRequestsTool = createISVDataTool('get_report_requests', getReportRequests, 'Get Report Request History', {
   reportId: {
@@ -240,21 +241,21 @@ export const getReportRequestsTool = createISVDataTool('get_report_requests', ge
     description: "The report unit ID (path) to get execution history for (e.g., '/processedTransactions')",
     enum: Object.values(REPORT_TYPES)
   }
-});
+}, READS);
 
 export const getExportListTool = createISVDataTool('get_export_list', getExportList, 'Get Export List for Request', {
   requestId: {
     type: "string",
     description: "The request ID (UUID) to get exports for"
   }
-});
+}, READS);
 
 export const getReportStatusTool = createISVDataTool('get_report_status', getReportStatus, 'Get Report Status', {
   requestId: {
     type: "string",
     description: "The request ID returned from the report generation request (UUID format)"
   }
-});
+}, READS);
 
 export const exportReportTool = createISVDataTool('export_report', exportReport, 'Export Report', {
   requestId: {
@@ -267,35 +268,35 @@ export const exportReportTool = createISVDataTool('export_report', exportReport,
     enum: Object.values(EXPORT_FORMATS),
     default: EXPORT_FORMATS.PDF
   }
-});
+}, CREATES);
 
 export const getExportStatusTool = createISVDataTool('get_export_status', getExportStatus, 'Get Export Status', {
   exportId: {
     type: "string",
     description: "The export ID returned from the export request (UUID format)"
   }
-});
+}, READS);
 
 export const downloadExportTool = createISVDataTool('download_export', downloadExport, 'Download Export', {
   exportId: {
     type: "string",
     description: "The export ID from the export request (UUID format)"
   }
-});
+}, READS);
 
 export const cancelReportTool = createISVDataTool('cancel_report', cancelReport, 'Cancel Report', {
   requestId: {
     type: "string",
     description: "The request ID of the report to cancel (UUID format)"
   }
-});
+}, CHANGES);
 
 export const cancelExportTool = createISVDataTool('cancel_export', cancelExport, 'Cancel Export', {
   exportId: {
     type: "string",
     description: "The export ID of the export to cancel (UUID format)"
   }
-});
+}, CHANGES);
 
 /**
  * All ISV data tools

package/src/isv/deep-links/delete-product-link.js

@@ -1,11 +1,13 @@
 import { deleteProductDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Delete deep link for a product (ISV on behalf of merchant)
  */
 export const deleteProductLinkTool = {
   name: "payware_deep_links_delete_product_link",
+  annotations: CHANGES,
   description: `Delete an active deep link for a product on behalf of a merchant. Once deleted, the deep link URL will no longer redirect to the payware mobile app.
 
 **ISV Authentication:**
@@ -45,8 +47,7 @@ export const deleteProductLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["productId", "merchantPartnerId", "oauth2Token"]

package/src/isv/deep-links/delete-transaction-link.js

@@ -1,11 +1,13 @@
 import { deleteTransactionDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Delete deep link for a transaction (ISV on behalf of merchant)
  */
 export const deleteTransactionLinkTool = {
   name: "payware_deep_links_delete_transaction_link",
+  annotations: CHANGES,
   description: `Delete an active deep link for a transaction on behalf of a merchant. Once deleted, the deep link URL will no longer redirect to the payware mobile app.
 
 **ISV Authentication:**
@@ -45,8 +47,7 @@ export const deleteTransactionLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["transactionId", "merchantPartnerId", "oauth2Token"]

package/src/isv/deep-links/get-product-link.js

@@ -1,12 +1,14 @@
 import { getProductDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { ADDS } from '../../shared/tool-annotations.js';
 
 /**
  * Get deep link for a product (ISV on behalf of merchant)
  */
 export const getProductLinkTool = {
   name: "payware_deep_links_get_product_link",
-  description: `Get an active deep link for a product on behalf of a merchant. Returns a clickable URL that redirects to the payware mobile app.
+  annotations: ADDS,
+  description: `Get an active deep link for a product on behalf of a merchant. Returns a clickable URL that redirects to the payware mobile app. For a link whose payments are attributed to one placement of the product (a poster, an ad, a mailing), use payware_products_get_placement_link instead.
 
 **ISV Authentication:**
 - Requires ISV JWT token with merchant partner ID in 'aud' claim
@@ -14,7 +16,7 @@ export const getProductLinkTool = {
 
 **Deep Link Format:**
 - Web URL: https://go.payware.eu/{productId}
-- Mobile Redirect: payware://{productId}
+- Mobile Redirect: payware:/{productId} (one slash: the identifier is case-sensitive, so it must not sit in the URI host, which redirect services lowercase)
 
 **Use Cases:**
 - Mobile-only e-commerce product references
@@ -23,6 +25,7 @@ export const getProductLinkTool = {
 
 **Important Notes:**
 - Deep links are only supported in production environment
+- Apps that open payware links must accept \`payware:\` followed by one, two or three slashes (QR codes and NFC tags carry \`payware://{id}\`): read the identifier after the scheme and any slashes, up to \`/\`, \`?\` or \`#\`, and keep its case
 - Link expiration is synchronized with the referenced product
 - Traditional deep links that route to app content when app is installed`,
 
@@ -49,8 +52,7 @@ export const getProductLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["productId", "merchantPartnerId", "oauth2Token"]
@@ -107,7 +109,7 @@ export const getProductLinkTool = {
 - Product ID: ${productId}
 - Merchant: ${merchantPartnerId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${productId}
+- Mobile Redirect: payware:/${productId}
 
 **ISV Authentication:**
 - ISV Partner ID: ${isvPartnerId}
@@ -131,7 +133,7 @@ ${JSON.stringify(result.data, null, 2)}
 
 **Usage:**
 1. Share the web URL: \`${linkUrl}\`
-2. On mobile devices, it will redirect to: \`payware://${productId}\`
+2. On mobile devices, it will redirect to: \`payware:/${productId}\`
 3. Link expires when the product expires
 4. Recreate if product is updated`
         }]

package/src/isv/deep-links/get-transaction-link.js

@@ -1,11 +1,13 @@
 import { getTransactionDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { ADDS } from '../../shared/tool-annotations.js';
 
 /**
  * Get deep link for a transaction (ISV on behalf of merchant)
  */
 export const getTransactionLinkTool = {
   name: "payware_deep_links_get_transaction_link",
+  annotations: ADDS,
   description: `Get an active deep link for a transaction on behalf of a merchant. Returns a clickable URL that redirects to the payware mobile app.
 
 **ISV Authentication:**
@@ -14,7 +16,7 @@ export const getTransactionLinkTool = {
 
 **Deep Link Format:**
 - Web URL: https://go.payware.eu/{transactionId}
-- Mobile Redirect: payware://{transactionId}
+- Mobile Redirect: payware:/{transactionId} (one slash: the identifier is case-sensitive, so it must not sit in the URI host, which redirect services lowercase)
 
 **Use Cases:**
 - P2P payments via messaging services
@@ -23,6 +25,7 @@ export const getTransactionLinkTool = {
 
 **Important Notes:**
 - Deep links are only supported in production environment
+- Apps that open payware links must accept \`payware:\` followed by one, two or three slashes (QR codes and NFC tags carry \`payware://{id}\`): read the identifier after the scheme and any slashes, up to \`/\`, \`?\` or \`#\`, and keep its case
 - Link expiration is synchronized with the referenced transaction
 - Traditional deep links that route to app content when app is installed`,
 
@@ -49,8 +52,7 @@ export const getTransactionLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["transactionId", "merchantPartnerId", "oauth2Token"]
@@ -107,7 +109,7 @@ export const getTransactionLinkTool = {
 - Transaction ID: ${transactionId}
 - Merchant: ${merchantPartnerId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${transactionId}
+- Mobile Redirect: payware:/${transactionId}
 
 **ISV Authentication:**
 - ISV Partner ID: ${isvPartnerId}
@@ -131,7 +133,7 @@ ${JSON.stringify(result.data, null, 2)}
 
 **Usage:**
 1. Share the web URL: \`${linkUrl}\`
-2. On mobile devices, it will redirect to: \`payware://${transactionId}\`
+2. On mobile devices, it will redirect to: \`payware:/${transactionId}\`
 3. Link expires when the transaction expires
 4. Recreate if transaction is extended`
         }]
@@ -155,7 +157,7 @@ ${JSON.stringify(result.data, null, 2)}
 5. **Invalid transaction ID**: Ensure transaction ID format is correct
 
 **Troubleshooting:**
-1. Verify transaction exists using \`payware_transactions_get_transaction_status\`
+1. Verify transaction exists using \`payware_operations_get_transaction_status\`
 2. Check OAuth2 token is valid and not expired
 3. Ensure ISV has permission to access merchant data
 4. Check if running in production environment

package/src/isv/index.js

@@ -31,6 +31,9 @@ import { isvPOITools } from './poi/index.js';
 // Shop tools
 import { isvShopTools } from './shops/index.js';
 
+// Campaigns, placements and airings - one definition shared by merchants and ISVs
+import { placementTools } from '../shared/placements/tools.js';
+
 // Merchant onboarding: invitations, and the reference data their forms need
 import { isvInvitationTools } from './invitations/index.js';
 import { isvReferenceTools } from './reference/index.js';
@@ -73,6 +76,9 @@ export const isvTools = [
   // Shop lookup - needed before any call that takes a shopCode
   ...isvShopTools,
 
+  // Campaigns, placements and airings, on behalf of the merchant
+  ...placementTools('isv'),
+
   // Merchant onboarding. These come BEFORE a merchant exists, so they authenticate as the ISV
   // itself rather than on behalf of anyone - they are how the merchantPartnerId + oauth2Token pair
   // that every other tool here requires comes into existence in the first place.