@payware/mcp-server 1.3.3 → 1.4.0

package/src/payment-institution/transactions/get-transaction-status.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction status via payware API (active transactions)
@@ -54,6 +55,7 @@ export async function getPITransactionStatus({
  */
 export const getPITransactionStatusTool = {
   name: "payware_operations_get_transaction_status",
+  annotations: READS,
   description: `Get the current status of an active payware transaction as a financial institution.
 
 **Use Cases:**
@@ -96,7 +98,7 @@ Four rules a payer-facing app must follow:
 4. **A missing field is usually a plan boundary, not an error.** \`imageUrl\` and \`termsUrl\` are
    Standard and above; \`termsText\` and the descriptions are universal.
 
-For a \`pr\`/\`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
+For a \`pr\`, \`pl\` or \`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
 plan gating); for the resulting \`pw\` transaction they are the snapshot frozen at creation, so what
 you get always reflects what the payer could have been shown at scan time.
 
@@ -105,14 +107,14 @@ strings at the smallest unit their own currency can be paid in - not always two
 **the value to echo back unchanged at finalize**; \`feeFixed\` and \`feeRate\` are informational, and
 recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
 
-**Note:** This endpoint only returns active transactions. Use \`payware_pi_get_transaction_history\` for completed/expired transactions.`,
+**Note:** This endpoint only returns active transactions. Use \`payware_operations_get_transaction_history\` for completed/expired transactions.`,
   inputSchema: {
     type: "object",
     properties: {
       transactionId: {
         type: "string",
-        description: "Transaction ID to check status. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+        description: "Transaction ID to check status. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
+        pattern: "^(pw|pr|pl|ps)[0-9A-Za-z]{8}$"
       },
       partnerId: {
         type: "string",
@@ -121,8 +123,7 @@ recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       useSandbox: {
         type: "boolean",
@@ -159,6 +160,8 @@ recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
       privateKey,
       useSandbox
     });
+    // The success text quotes the endpoint. The helper above keeps its own baseUrl, so it needs one here.
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
 
     if (result.success) {
       const tx = result.transaction;
@@ -209,8 +212,8 @@ ${JSON.stringify(result.transaction, null, 2)}
 **Next Steps:**
 1. ${!tx.payerAccount ? 'Transaction waiting for payer to process' : 'Transaction processed, waiting for finalization'}
 2. ${tx.timeToLive && parseInt(tx.timeToLive) < 60 ? '⚠️ Transaction expires soon!' : 'Monitor remaining TTL'}
-3. Use \`payware_pi_process_transaction\` if you need to process this transaction
-4. Use \`payware_pi_finalize_transaction\` to confirm/decline after processing
+3. Use \`payware_operations_process_transaction\` if you need to process this transaction
+4. Use \`payware_operations_finalize_transaction\` to confirm/decline after processing
 
 **⚠️ Transaction State:**
 - This is an **active** transaction
@@ -240,18 +243,18 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 
 **Common Issues:**
 1. **ERR_MISSING_TRANSACTION (404)**: Transaction not found, expired, or already completed
-2. **Invalid Transaction ID**: Check transaction ID format (10 chars: 'pw'/'pr'/'ps' + 8 chars)
+2. **Invalid Transaction ID**: Check transaction ID format (10 chars: 'pw'/'pr'/'pl'/'ps' + 8 chars)
 3. **Authentication Issues**: Verify JWT token and partner credentials
 
 **Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), 'pl' (placement) or 'ps' (soundbite)
 2. Check if transaction has expired or been completed
-3. Use \`payware_pi_get_transaction_history\` for completed/expired transactions
+3. Use \`payware_operations_get_transaction_history\` for completed/expired transactions
 4. Verify your partner credentials and API access
 5. Ensure transaction was created or you have access to it
 
 **Alternative Actions:**
-- If transaction is completed: Use \`payware_pi_get_transaction_history\`
+- If transaction is completed: Use \`payware_operations_get_transaction_history\`
 - If transaction ID is wrong: Verify the correct transaction ID
 - If access issues: Check your payment institution credentials`
         }]

package/src/payment-institution/transactions/process-pi-transaction.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a transaction as a payment institution via payware API
@@ -112,6 +113,7 @@ export async function processPITransaction({
  */
 export const processPITransactionTool = {
   name: "payware_operations_process_transaction",
+  annotations: COMMITS,
   description: `Process a transaction as a payment institution. Payment institutions can process transactions created by others and must provide account/friendlyName details.
 
 **Use Cases:**
@@ -148,8 +150,8 @@ export const processPITransactionTool = {
     properties: {
       transactionId: {
         type: "string",
-        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
+        pattern: "^(pw|pr|pl|ps)[0-9A-Za-z]{8}$"
       },
       account: {
         type: "string",
@@ -205,8 +207,7 @@ export const processPITransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       // Payment method for POI transactions
       paymentMethod: {
@@ -373,7 +374,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 1. **TRANSACTION_PROCESSED** callback will be sent to counterparty
 2. Wait for callback notification to your URL (if provided)
 3. Monitor transaction status for completion
-4. Use \`payware_pi_finalize_transaction\` to confirm/decline the transaction
+4. Use \`payware_operations_finalize_transaction\` to confirm/decline the transaction
 5. Handle final TRANSACTION_FINALIZED callbacks
 
 **⚠️ Important:**
@@ -412,7 +413,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 7. **ERR_SPECIFYING_CURRENCY_NOT_ALLOWED**: Cannot change currency on merchant transactions
 
 **Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), 'pl' (placement) or 'ps' (soundbite)
 2. Ensure account and friendlyName are provided
 3. Check currency matches original transaction currency
 4. Verify callback URL is provided (especially for payee role)

package/src/payment-institution/transactions/simulate-pi-callback.js

@@ -10,6 +10,8 @@
  * @param {Object} options - Additional options
  * @returns {Object} Mock callback payload
  */
+import { LOCAL } from '../../shared/tool-annotations.js';
+
 export function generateMockPICallback(transactionId, callbackType = 'TRANSACTION_PROCESSED', options = {}) {
   const {
     amount = '57.00',
@@ -146,6 +148,7 @@ export async function simulatePICallbackDelivery(callbackUrl, payload) {
  */
 export const simulatePICallbackTool = {
   name: "payware_operations_simulate_callback",
+  annotations: LOCAL,
   description: "Simulate payment institution callback scenarios for testing webhook handling. Payment institutions receive TRANSACTION_PROCESSED when merchant processes their transaction, and TRANSACTION_FINALIZED when transaction is completed.",
   inputSchema: {
     type: "object",

package/src/payment-institution/transactions/soundbite-transaction.js

@@ -4,6 +4,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { readFileSync } from 'fs';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction information using Soundbite file via payware API
@@ -73,6 +74,7 @@ export async function getSoundbiteTransaction({
  */
 export const soundbiteTransactionTool = {
   name: "payware_operations_soundbite_transaction",
+  annotations: CREATES,
   description: `Get transaction information using a Soundbite SDK output file. This allows payment institutions to process transactions using audio-based identifiers.
 
 **Soundbite Integration:**
@@ -105,8 +107,7 @@ export const soundbiteTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       useSandbox: {
         type: "boolean",
@@ -199,8 +200,8 @@ ${JSON.stringify(result.transaction, null, 2)}
 1. Transaction successfully identified from soundbite file
 2. Use transaction ID: \`${tx.transactionId || 'N/A'}\` for further operations
 3. ${!tx.payerAccount ? 'Process this transaction if you are the payer' : 'Transaction ready for finalization'}
-4. Use \`payware_pi_process_transaction\` to process payment
-5. Use \`payware_pi_finalize_transaction\` to confirm/decline
+4. Use \`payware_operations_process_transaction\` to process payment
+5. Use \`payware_operations_finalize_transaction\` to confirm/decline
 
 **♿ Accessibility Note:**
 - Soundbite provides audio-based alternative to QR/barcode scanning

package/src/proxy-server.js

@@ -33,6 +33,31 @@ class PaywareMCPProxy {
     const allowedOrigins = (process.env.PAYWARE_MCP_PROXY_ORIGINS
       || `http://localhost:${this.port},http://127.0.0.1:${this.port}`)
       .split(',').map((o) => o.trim()).filter(Boolean);
+
+    // DNS rebinding and cross-site requests. The CORS allowlist below decides which pages may READ a
+    // response; it never refuses a request. A page whose hostname has been rebound to 127.0.0.1 is
+    // same-origin with this server, so CORS does not apply to it at all, and a cross-site form POST
+    // needs no preflight - either way the route runs and signs as the partner. Two checks refuse them:
+    // Host must be a name this server answers to (a rebound page sends its own hostname there), and an
+    // Origin, which browsers send on every POST, must be allowlisted. Clients that are not browsers -
+    // curl, the bridge - send no Origin and pass. PAYWARE_MCP_PROXY_HOSTS (comma-separated host:port)
+    // widens the Host list deliberately.
+    const bindHost = process.env.PAYWARE_MCP_PROXY_HOST || '127.0.0.1';
+    const allowedHosts = new Set((process.env.PAYWARE_MCP_PROXY_HOSTS
+      || `localhost:${this.port},127.0.0.1:${this.port},${bindHost}:${this.port}`)
+      .split(',').map((h) => h.trim().toLowerCase()).filter(Boolean));
+    this.app.use((req, res, next) => {
+      const host = (req.headers.host || '').toLowerCase();
+      if (!allowedHosts.has(host)) {
+        return res.status(403).json({ error: 'Forbidden', message: `Host ${host || '(none)'} is not allowed` });
+      }
+      const origin = req.headers.origin;
+      if (origin !== undefined && !allowedOrigins.includes(origin)) {
+        return res.status(403).json({ error: 'Forbidden', message: `Origin ${origin} is not allowed` });
+      }
+      next();
+    });
+
     this.app.use(cors({
       origin: allowedOrigins,
       credentials: true

package/src/shared/placements/api.js

@@ -0,0 +1,51 @@
+import axios from 'axios';
+import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
+import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+import { createAuthHeaders } from '../auth-headers.js';
+import { apiErrorResult } from '../api-errors.js';
+
+/**
+ * One call to the campaigns, placements and airings API, as a merchant or as an ISV acting for one.
+ *
+ * Built on the shared `createAuthHeaders`, so the on-behalf JWT (`aud` = the merchant, `sub` = its
+ * OAuth2 token) and the content hash come from the same code every newer tool uses. The body is
+ * serialized once and that exact string is both hashed and sent; `transformRequest` stops axios from
+ * serializing it a second time.
+ *
+ * Never throws for an HTTP error: it returns `apiErrorResult`, whose `details` keeps the response
+ * body, which is where a refused replace-all lists its rows.
+ *
+ * @param {Object} params
+ * @param {string} params.method    HTTP verb
+ * @param {string} params.path      path under the API root, ids already encoded
+ * @param {Object} [params.query]   query parameters; undefined values are left out
+ * @param {*} [params.body]         request body, serialized deterministically
+ * @param {boolean} [params.binary] read the response as bytes (images)
+ * @param {Object} params.auth      from the role: partnerType, credentials and useSandbox
+ */
+export async function placementsRequest({ method, path, query, body, binary = false, auth }) {
+  const minimizedBody = body === undefined ? undefined : createMinimizedJSON(body);
+  const headers = await createAuthHeaders(auth.partnerType, { ...auth, requestBody: minimizedBody });
+  const baseUrl = auth.useSandbox ? getSandboxUrl() : getProductionUrl();
+  const params = query && Object.fromEntries(Object.entries(query).filter(([, v]) => v !== undefined && v !== null));
+
+  try {
+    const response = await axios({
+      method,
+      url: `${baseUrl}${path}`,
+      headers,
+      ...(params && Object.keys(params).length > 0 && { params }),
+      ...(minimizedBody !== undefined && { data: minimizedBody, transformRequest: [(data) => data] }),
+      ...(binary && { responseType: 'arraybuffer' })
+    });
+    return {
+      success: true,
+      status: response.status,
+      data: response.data,
+      contentType: response.headers['content-type'],
+      requestId: response.headers['x-request-id']
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}