shabaaspay-mcp-server 1.0.3 → 1.0.5

package/dist/agent-toolkit/ai-sdk.d.ts

@@ -0,0 +1,5 @@
+import { ShabaasAgentToolkit, type ShabaasAgentToolkitOptions } from './index.js';
+export declare class ShabaasAgentToolkitAiSdk extends ShabaasAgentToolkit {
+    constructor(options: ShabaasAgentToolkitOptions);
+    getAiSdkTools(): Promise<Record<string, any>>;
+}

package/dist/agent-toolkit/ai-sdk.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShabaasAgentToolkitAiSdk = void 0;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const index_js_1 = require("./index.js");
+class ShabaasAgentToolkitAiSdk extends index_js_1.ShabaasAgentToolkit {
+    constructor(options) {
+        super(options);
+    }
+    async getAiSdkTools() {
+        let toolFactory;
+        try {
+            const aiModuleName = 'ai';
+            const aiModule = await import(aiModuleName);
+            toolFactory = aiModule.tool;
+        }
+        catch {
+            throw new Error('AI SDK adapter requires the "ai" package. Install it with: npm install ai');
+        }
+        const entries = this.getTools().map((toolDef) => {
+            const parameters = (0, zod_to_json_schema_1.zodToJsonSchema)(toolDef.inputSchema);
+            return [
+                toolDef.name,
+                toolFactory({
+                    description: toolDef.description,
+                    parameters,
+                    execute: async (args) => toolDef.execute(args ?? {}),
+                }),
+            ];
+        });
+        return Object.fromEntries(entries);
+    }
+}
+exports.ShabaasAgentToolkitAiSdk = ShabaasAgentToolkitAiSdk;

package/dist/agent-toolkit/index.d.ts

@@ -0,0 +1,16 @@
+export type ShabaasAgentToolkitOptions = {
+    apiKey: string;
+    environment?: 'sandbox' | 'production';
+};
+export type ShabaasFunctionTool = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    execute: (args?: Record<string, unknown>) => Promise<unknown>;
+};
+export declare class ShabaasAgentToolkit {
+    private readonly apiKey;
+    private readonly tools;
+    constructor(options: ShabaasAgentToolkitOptions);
+    getTools(): ShabaasFunctionTool[];
+}

package/dist/agent-toolkit/index.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShabaasAgentToolkit = void 0;
+const client_js_1 = require("../api/client.js");
+const backend_urls_js_1 = require("../constants/backend-urls.js");
+const index_js_1 = require("../tools/index.js");
+function toToolkitConfig(options) {
+    const environment = options.environment ?? 'sandbox';
+    return {
+        environment,
+        shabaasAuthUuid: options.apiKey,
+        sandboxUrl: backend_urls_js_1.CANONICAL_SANDBOX_BASE_URL,
+        productionUrl: backend_urls_js_1.CANONICAL_PRODUCTION_BASE_URL,
+        httpPort: 3001,
+        httpHost: '0.0.0.0',
+        mcpHttpApiKey: '',
+        mcpStdioApiKey: '',
+        allowedOrigins: ['*'],
+        rateLimitPerMinute: 60,
+        rateLimitPerHour: 1000,
+        authTokenMaxAgeMinutes: 50,
+        policyCacheTtlMs: 300_000,
+    };
+}
+class ShabaasAgentToolkit {
+    apiKey;
+    tools;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('ShabaasAgentToolkit requires apiKey');
+        }
+        this.apiKey = options.apiKey;
+        const config = toToolkitConfig(options);
+        const apiClient = new client_js_1.ShabaasApiClient(config);
+        this.tools = (0, index_js_1.createAllTools)(apiClient, config);
+    }
+    getTools() {
+        return Object.values(this.tools).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            execute: async (args) => tool.execute(args ?? {}, { requestUuid: this.apiKey }),
+        }));
+    }
+}
+exports.ShabaasAgentToolkit = ShabaasAgentToolkit;

package/dist/agent-toolkit/langchain.d.ts

@@ -0,0 +1,5 @@
+import { ShabaasAgentToolkit, type ShabaasAgentToolkitOptions } from './index.js';
+export declare class ShabaasAgentToolkitLangChain extends ShabaasAgentToolkit {
+    constructor(options: ShabaasAgentToolkitOptions);
+    getLangChainTools(): Promise<any[]>;
+}

package/dist/agent-toolkit/langchain.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShabaasAgentToolkitLangChain = void 0;
+const zod_1 = require("zod");
+const index_js_1 = require("./index.js");
+class ShabaasAgentToolkitLangChain extends index_js_1.ShabaasAgentToolkit {
+    constructor(options) {
+        super(options);
+    }
+    async getLangChainTools() {
+        let DynamicStructuredTool;
+        try {
+            const langchainToolsModule = '@langchain/core/tools';
+            ({ DynamicStructuredTool } = await import(langchainToolsModule));
+        }
+        catch {
+            throw new Error('LangChain adapter requires @langchain/core. Install it with: npm install @langchain/core');
+        }
+        return this.getTools().map((tool) => new DynamicStructuredTool({
+            name: tool.name,
+            description: tool.description,
+            schema: tool.inputSchema ?? zod_1.z.object({}),
+            func: async (args) => {
+                const result = await tool.execute(args);
+                return JSON.stringify(result);
+            },
+        }));
+    }
+}
+exports.ShabaasAgentToolkitLangChain = ShabaasAgentToolkitLangChain;

package/dist/agent-toolkit/modelcontextprotocol.d.ts

@@ -0,0 +1,2 @@
+export { StdioMcpServer } from '../server/stdio-server.js';
+export { HttpMcpServer } from '../server/http-server.js';

package/dist/agent-toolkit/modelcontextprotocol.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpMcpServer = exports.StdioMcpServer = void 0;
+var stdio_server_js_1 = require("../server/stdio-server.js");
+Object.defineProperty(exports, "StdioMcpServer", { enumerable: true, get: function () { return stdio_server_js_1.StdioMcpServer; } });
+var http_server_js_1 = require("../server/http-server.js");
+Object.defineProperty(exports, "HttpMcpServer", { enumerable: true, get: function () { return http_server_js_1.HttpMcpServer; } });

package/dist/api/client.d.ts

@@ -4,6 +4,16 @@ import { ApiResponse } from '../types/index.js';
 export type RequestAuthOptions = {
     requestUuid?: string;
 };
+/**
+ * Discoverable auth behavior metadata used by docs/discovery surfaces.
+ * Additive-only metadata: does not alter runtime request handling.
+ */
+export declare const AUTH_BEHAVIOR: {
+    readonly token_cache_ttl_ms: number;
+    readonly accepts_authorization_formats: readonly ["sbp_live_xxx", "Bearer sbp_live_xxx"];
+    readonly upstream_token_exchange: true;
+    readonly cache_scope: "per_api_key";
+};
 export declare class ShabaasApiClient {
     private client;
     private config;
@@ -27,10 +37,10 @@ export declare class ShabaasApiClient {
         maximum_amount: string;
         frequency: string;
         number_of_transactions_permitted: number;
-        pay_id: string;
+        pay_id?: string;
         phone_number?: string;
-        bsb?: number;
-        account_number?: number;
+        bsb?: string | number;
+        account_number?: string | number;
         agreement_type?: string;
         start_date?: string;
         end_date?: string;
@@ -41,6 +51,7 @@ export declare class ShabaasApiClient {
         payment_agreement_id: string;
         amount: string | number;
         description?: string;
+        notes?: string;
     }, options?: RequestAuthOptions): Promise<ApiResponse>;
     getPaymentInitiation(id: string, options?: RequestAuthOptions): Promise<ApiResponse>;
     initiateDirectDebit(data: {

package/dist/api/client.js

@@ -3,12 +3,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ShabaasApiClient = void 0;
+exports.ShabaasApiClient = exports.AUTH_BEHAVIOR = void 0;
 const axios_1 = __importDefault(require("axios"));
 const index_js_1 = require("../config/index.js");
 /** Cache bearer token per API key so we don't refetch every request. */
 const tokenCache = new Map();
 const CACHE_TTL_MS = 50 * 60 * 1000; // 50 min
+/**
+ * Discoverable auth behavior metadata used by docs/discovery surfaces.
+ * Additive-only metadata: does not alter runtime request handling.
+ */
+exports.AUTH_BEHAVIOR = {
+    token_cache_ttl_ms: CACHE_TTL_MS,
+    accepts_authorization_formats: ['sbp_live_xxx', 'Bearer sbp_live_xxx'],
+    upstream_token_exchange: true,
+    cache_scope: 'per_api_key',
+};
 class ShabaasApiClient {
     client;
     config;
@@ -123,8 +133,9 @@ class ShabaasApiClient {
                 maximum_amount: data.maximum_amount,
                 frequency: data.frequency,
                 number_of_transactions_permitted: data.number_of_transactions_permitted,
-                pay_id: data.pay_id,
             };
+            if (data.pay_id != null)
+                pa.pay_id = data.pay_id;
             if (data.phone_number != null)
                 pa.phone_number = data.phone_number;
             if (data.bsb != null)
@@ -167,7 +178,7 @@ class ShabaasApiClient {
                 payment_initiation: {
                     payment_agreement_id: data.payment_agreement_id,
                     amount,
-                    description: data.description,
+                    notes: data.notes ?? data.description,
                 },
             }, {
                 headers: {

package/dist/mcp-handler/discovery.js

@@ -18,44 +18,348 @@ const index_js_1 = require("./tools/index.js");
  */
 async function listTools(env) {
     const prod = env.SHABAAS_ENVIRONMENT === 'production';
+    const sharedExecution = {
+        method: 'POST',
+        endpoint: '/tools/execute',
+        auth: {
+            required: true,
+            header: 'Authorization',
+            accepted_formats: ['sbp_live_xxx', 'Bearer sbp_live_xxx'],
+        },
+        response_contract: 'StandardResponse<T> with success, data, metadata, insights, summary',
+        output_schema: {
+            type: 'object',
+            required: ['success', 'timestamp', 'data', 'metadata', 'insights', 'summary'],
+            additionalProperties: true,
+            properties: {
+                success: { type: 'boolean' },
+                timestamp: { type: 'string', format: 'date-time' },
+                data: { type: 'object' },
+                metadata: { type: 'object' },
+                insights: { type: 'object' },
+                summary: { type: 'string' },
+                raw: {},
+            },
+            notes: 'Set include_raw=true to include optional raw upstream response payload.',
+        },
+        error_schema: {
+            type: 'object',
+            required: ['error', 'message'],
+            additionalProperties: true,
+            properties: {
+                error: { type: 'string' },
+                message: { type: 'string' },
+                code: { type: 'string' },
+                request_id: { type: 'string' },
+                retryable: { type: 'boolean' },
+            },
+        },
+        error_model: {
+            transport_errors: [
+                { status: 400, code: 'INVALID_REQUEST', retryable: false },
+                { status: 401, code: 'AUTH_MISSING_OR_INVALID', retryable: true },
+                { status: 403, code: 'TOOL_NOT_PERMITTED', retryable: false },
+                { status: 404, code: 'RESOURCE_NOT_FOUND', retryable: false },
+                { status: 429, code: 'RATE_LIMITED', retryable: true },
+                { status: 500, code: 'INTERNAL_ERROR', retryable: true },
+            ],
+            domain_error_shape: 'Domain-level failures may also be represented in StandardResponse as success=false with summary/raw.error_code.',
+        },
+    };
     const toolsList = [
         {
             name: 'get_payment_agreement',
-            description: 'Retrieve payment agreement details with AI insights',
-            method: 'POST',
-            endpoint: '/tools/execute',
+            description: 'Retrieve payment agreement details, state transitions, and AI-facing summary guidance.',
+            ...sharedExecution,
+            openapi_operation: { method: 'get', path: '/api/public/payment_agreement' },
+            output_openapi_schema_ref: '#/components/schemas/SuccessPaymentAgreementResponse',
+            required_arguments: ['payment_agreement_id'],
+            optional_arguments: ['enrich', 'include_raw'],
+            argument_hints: {
+                payment_agreement_id: 'String ID returned by create_payment_agreement, e.g. 2882PA20251227045450257',
+                enrich: 'Boolean, defaults true. Include business guidance for agent decisions.',
+                include_raw: 'Boolean, defaults false. Include raw upstream API payload for debugging only.',
+            },
+            argument_schema: {
+                payment_agreement_id: { type: 'string', pattern: '^[0-9]+PA[0-9]+$' },
+                enrich: { type: 'boolean', default: true },
+                include_raw: { type: 'boolean', default: false },
+            },
             example: { tool: 'get_payment_agreement', arguments: { payment_agreement_id: '2882PA20251227045450257' } },
+            decision_guidance: {
+                when_to_use: 'Use when you have a payment agreement ID and need latest status/details.',
+                preconditions: ['Valid payment_agreement_id'],
+                retryable_errors: ['AUTH_MISSING_OR_INVALID'],
+                non_retryable_errors: ['RESOURCE_NOT_FOUND', 'INVALID_REQUEST'],
+                next_best_tool_on_failure: 'create_payment_agreement',
+            },
+            retry_policy: {
+                safe_to_retry: true,
+                retry_on_status: [401, 429, 500],
+                backoff: 'exponential_jitter',
+            },
+            idempotency_notes: 'Read-only operation; safe to repeat with same input.',
+            error_contract: [
+                { status: 400, code: 'INVALID_REQUEST', when: 'Malformed JSON or missing required field' },
+                { status: 401, code: 'AUTH_MISSING_OR_INVALID', when: 'Session/API key missing or invalid' },
+                { status: 403, code: 'TOOL_NOT_PERMITTED', when: 'Client policy blocks tool' },
+                { status: 404, code: 'RESOURCE_NOT_FOUND', when: 'Agreement ID not found' },
+            ],
+            error_model: {
+                domain_errors: [
+                    { code: 'RESOURCE_NOT_FOUND', retryable: false, suggested_next_tool: 'create_payment_agreement' },
+                    { code: 'INVALID_REQUEST', retryable: false, suggested_next_tool: null },
+                ],
+            },
         },
         {
             name: 'create_payment_agreement',
-            description: 'Create a new payment agreement',
-            method: 'POST',
-            endpoint: '/tools/execute',
+            description: 'Create a new PayTo payment agreement for payer authorization and recurring collection.',
+            ...sharedExecution,
+            openapi_operation: { method: 'post', path: '/api/public/payment_agreement' },
+            output_openapi_schema_ref: '#/components/schemas/SuccessPaymentAgreementResponse',
+            required_arguments: ['name', 'type', 'maximum_amount', 'frequency', 'number_of_transactions_permitted'],
+            optional_arguments: ['pay_id', 'phone_number', 'bsb', 'account_number', 'agreement_type', 'start_date', 'end_date', 'enrich', 'include_raw'],
+            argument_hints: {
+                type: 'Allowed identifier types: email, phone, org, abn, or bsb.',
+                pay_id: 'Required unless type=bsb.',
+                bsb: 'Required with account_number when type=bsb.',
+                account_number: 'Required with bsb when type=bsb.',
+                frequency: 'Preferred stored codes: ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR. Aliases DAILY and ADHOC are accepted by upstream.',
+                maximum_amount: 'String amount in AUD, e.g. 35.00',
+                number_of_transactions_permitted: 'Positive integer, e.g. 1',
+            },
+            argument_schema: {
+                name: { type: 'string', minLength: 1 },
+                type: { type: 'string', enum: ['email', 'phone', 'org', 'abn', 'bsb'] },
+                maximum_amount: { type: 'string', pattern: '^\\d+(\\.\\d{1,2})?$' },
+                frequency: { type: 'string', enum: ['ADHO', 'DAIL', 'FRTN', 'INDA', 'MIAN', 'MNTH', 'QURT', 'WEEK', 'YEAR', 'DAILY', 'ADHOC'] },
+                number_of_transactions_permitted: { type: 'integer', minimum: 1 },
+                pay_id: { type: 'string' },
+                bsb: { type: ['string', 'number'] },
+                account_number: { type: ['string', 'number'] },
+                conditional_requirements: [
+                    { if: { type: 'bsb' }, then_required: ['bsb', 'account_number'] },
+                    { if_not: { type: 'bsb' }, then_required: ['pay_id'] },
+                ],
+            },
+            example: {
+                tool: 'create_payment_agreement',
+                arguments: {
+                    name: 'Gym Membership',
+                    type: 'email',
+                    maximum_amount: '35.00',
+                    frequency: 'MNTH',
+                    number_of_transactions_permitted: 1,
+                    pay_id: 'payer@example.com',
+                },
+            },
+            decision_guidance: {
+                when_to_use: 'Use to create a new payer authorization mandate before initiating payments.',
+                preconditions: ['name, type, maximum_amount, frequency, number_of_transactions_permitted'],
+                retryable_errors: ['AUTH_MISSING_OR_INVALID'],
+                non_retryable_errors: ['VALIDATION_OR_BUSINESS_RULE', 'DEVELOPER_CREDITS_EXHAUSTED'],
+                next_best_tool_on_failure: 'get_payment_agreement',
+            },
+            retry_policy: {
+                safe_to_retry: false,
+                retry_on_status: [401, 429, 500],
+                backoff: 'exponential_jitter',
+            },
+            idempotency_notes: 'Creates a new agreement and is not idempotent without caller-side deduplication.',
+            error_contract: [
+                { status: 400, code: 'INVALID_REQUEST', when: 'Missing or invalid input shape' },
+                { status: 401, code: 'AUTH_MISSING_OR_INVALID', when: 'Session/API key missing or invalid' },
+                { status: 402, code: 'DEVELOPER_CREDITS_EXHAUSTED', when: 'Developer credits are exhausted' },
+                { status: 422, code: 'VALIDATION_OR_BUSINESS_RULE', when: 'Upstream validation or business rule failure' },
+            ],
+            error_model: {
+                domain_errors: [
+                    { code: 'VALIDATION_OR_BUSINESS_RULE', retryable: false, suggested_next_tool: 'get_payment_agreement' },
+                    { code: 'DEVELOPER_CREDITS_EXHAUSTED', retryable: false, suggested_next_tool: null },
+                ],
+            },
         },
         {
             name: 'initiate_payment',
-            description: 'Initiate a payment against an agreement',
-            method: 'POST',
-            endpoint: '/tools/execute',
+            description: 'Initiate a debit payment against an approved payment agreement.',
+            ...sharedExecution,
+            openapi_operation: { method: 'post', path: '/api/public/payment_initiation' },
+            output_openapi_schema_ref: '#/components/schemas/SuccessPaymentInitiationResponse',
+            required_arguments: ['payment_agreement_id', 'amount'],
+            optional_arguments: ['notes', 'description', 'enrich', 'include_raw'],
+            argument_hints: {
+                amount: 'Number or numeric string greater than zero, e.g. 10.00',
+                notes: 'Optional note persisted by backend for this payment initiation.',
+                description: 'Legacy alias; if notes is omitted, description is forwarded as notes.',
+            },
+            argument_schema: {
+                payment_agreement_id: { type: 'string', pattern: '^[0-9]+PA[0-9]+$' },
+                amount: { oneOf: [{ type: 'number', exclusiveMinimum: 0 }, { type: 'string', pattern: '^\\d+(\\.\\d{1,2})?$' }] },
+                notes: { type: 'string' },
+                description: { type: 'string' },
+                enrich: { type: 'boolean', default: true },
+                include_raw: { type: 'boolean', default: false },
+            },
+            example: {
+                tool: 'initiate_payment',
+                arguments: { payment_agreement_id: '2882PA20251227045450257', amount: '10.00', notes: 'Invoice 4201' },
+            },
+            decision_guidance: {
+                when_to_use: 'Use to debit an already approved payment agreement.',
+                preconditions: ['Active payment_agreement_id', 'amount > 0'],
+                retryable_errors: ['AUTH_MISSING_OR_INVALID'],
+                non_retryable_errors: ['BUSINESS_RULE_FAILURE', 'AGREEMENT_NOT_FOUND', 'INVALID_AMOUNT_OR_REQUEST'],
+                next_best_tool_on_failure: 'get_payment_agreement',
+            },
+            retry_policy: {
+                safe_to_retry: false,
+                retry_on_status: [401, 429, 500],
+                backoff: 'exponential_jitter',
+            },
+            idempotency_notes: 'Creates a payment initiation and is non-idempotent without external dedupe keys.',
+            error_contract: [
+                { status: 400, code: 'INVALID_AMOUNT_OR_REQUEST', when: 'Amount <= 0 or invalid request body' },
+                { status: 401, code: 'AUTH_MISSING_OR_INVALID', when: 'Session/API key missing or invalid' },
+                { status: 404, code: 'AGREEMENT_NOT_FOUND', when: 'Agreement does not exist for merchant' },
+                { status: 422, code: 'BUSINESS_RULE_FAILURE', when: 'Cooldown, inactive agreement, limits, or scheme rejection' },
+            ],
+            error_model: {
+                domain_errors: [
+                    { code: 'BUSINESS_RULE_FAILURE', retryable: false, suggested_next_tool: 'get_payment_agreement' },
+                    { code: 'AGREEMENT_NOT_FOUND', retryable: false, suggested_next_tool: 'create_payment_agreement' },
+                    { code: 'INVALID_AMOUNT_OR_REQUEST', retryable: false, suggested_next_tool: null },
+                ],
+            },
         },
         {
             name: 'get_payment_initiation',
-            description: 'Retrieve payment initiation by ID',
-            method: 'POST',
-            endpoint: '/tools/execute',
+            description: 'Retrieve a payment initiation status by payment initiation ID.',
+            ...sharedExecution,
+            openapi_operation: { method: 'get', path: '/api/public/payment_initiation' },
+            output_openapi_schema_ref: '#/components/schemas/SuccessPaymentInitiationResponse',
+            required_arguments: ['payment_initiation_id'],
+            optional_arguments: ['enrich', 'include_raw'],
+            argument_hints: {
+                payment_initiation_id: 'String ID returned by initiate_payment, e.g. 2724PI20250101010101001',
+            },
+            argument_schema: {
+                payment_initiation_id: { type: 'string', pattern: '^[0-9]+PI[0-9]+$' },
+                enrich: { type: 'boolean', default: true },
+                include_raw: { type: 'boolean', default: false },
+            },
+            example: { tool: 'get_payment_initiation', arguments: { payment_initiation_id: '2724PI20250101010101001' } },
+            decision_guidance: {
+                when_to_use: 'Use when you need the latest status of an initiated payment.',
+                preconditions: ['Valid payment_initiation_id'],
+                retryable_errors: ['AUTH_MISSING_OR_INVALID'],
+                non_retryable_errors: ['RESOURCE_NOT_FOUND', 'INVALID_REQUEST'],
+                next_best_tool_on_failure: 'initiate_payment',
+            },
+            retry_policy: {
+                safe_to_retry: true,
+                retry_on_status: [401, 429, 500],
+                backoff: 'exponential_jitter',
+            },
+            idempotency_notes: 'Read-only operation; safe to repeat with same input.',
+            error_contract: [
+                { status: 400, code: 'INVALID_REQUEST', when: 'Missing required field' },
+                { status: 401, code: 'AUTH_MISSING_OR_INVALID', when: 'Session/API key missing or invalid' },
+                { status: 404, code: 'RESOURCE_NOT_FOUND', when: 'Initiation ID not found' },
+            ],
+            error_model: {
+                domain_errors: [
+                    { code: 'RESOURCE_NOT_FOUND', retryable: false, suggested_next_tool: 'initiate_payment' },
+                    { code: 'INVALID_REQUEST', retryable: false, suggested_next_tool: null },
+                ],
+            },
         },
     ];
     if (!prod) {
         toolsList.push({
             name: 'get_auth_token',
-            description: 'Get ShaBaas API authorization token',
-            method: 'POST',
-            endpoint: '/tools/execute',
-            example: { tool: 'get_auth_token', arguments: { api_key: 'your-api-key-here' } },
+            description: 'Exchange an API key for a backend bearer token (debug/non-production helper).',
+            ...sharedExecution,
+            openapi_operation: { method: 'post', path: '/api/public/authorization' },
+            output_openapi_schema_ref: '#/components/schemas/SuccessAuthorizationResponse',
+            required_arguments: [],
+            optional_arguments: ['include_token_in_response'],
+            argument_hints: {
+                include_token_in_response: 'Boolean, defaults false. Keep false for normal agent usage.',
+            },
+            argument_schema: {
+                include_token_in_response: { type: 'boolean', default: false },
+            },
+            auth_note: 'Uses MCP session auth (OAuth/Authorization header) by default. Stdio clients may provide authorization in tool args when needed.',
+            example: { tool: 'get_auth_token', arguments: { include_token_in_response: false } },
+            decision_guidance: {
+                when_to_use: 'Use only for non-production debugging of auth flow.',
+                preconditions: ['Non-production environment'],
+                retryable_errors: ['AUTH_MISSING_OR_INVALID'],
+                non_retryable_errors: ['TOOL_NOT_PERMITTED_IN_PRODUCTION'],
+                next_best_tool_on_failure: 'create_payment_agreement',
+            },
+            retry_policy: {
+                safe_to_retry: true,
+                retry_on_status: [401, 429, 500],
+                backoff: 'exponential_jitter',
+            },
+            idempotency_notes: 'Returns current auth state; safe to repeat in non-production.',
+            error_contract: [
+                { status: 401, code: 'AUTH_MISSING_OR_INVALID', when: 'Session/API key missing or invalid' },
+                { status: 403, code: 'TOOL_NOT_PERMITTED_IN_PRODUCTION', when: 'Tool disabled in production' },
+            ],
+            error_model: {
+                domain_errors: [
+                    { code: 'TOOL_NOT_PERMITTED_IN_PRODUCTION', retryable: false, suggested_next_tool: 'create_payment_agreement' },
+                ],
+            },
         });
     }
     const res = (0, utils_js_1.jsonResponse)({
         tools: toolsList,
+        metadata: {
+            discovery_schema_version: '2026-04-15',
+            compatibility: {
+                policy: 'backward-compatible additive fields only for discovery metadata',
+                deprecation_window_days: 90,
+            },
+            official_openapi: {
+                mcp: 'https://raw.githubusercontent.com/shabaaspay/shabaas-ai/main/openapi/openapi.yaml',
+                repository: 'https://github.com/shabaaspay/shabaas-ai',
+            },
+            auth_behavior: {
+                entry_header: 'Authorization',
+                accepted_formats: ['sbp_live_xxx', 'Bearer sbp_live_xxx'],
+                token_cache_ttl_ms: 3000000,
+                cache_scope: 'per_api_key',
+                upstream_token_exchange: true,
+            },
+            error_taxonomy: {
+                canonical_error_codes: [
+                    'AUTH_MISSING_OR_INVALID',
+                    'TOOL_NOT_PERMITTED',
+                    'TOOL_NOT_PERMITTED_IN_PRODUCTION',
+                    'INVALID_REQUEST',
+                    'INVALID_AMOUNT_OR_REQUEST',
+                    'RESOURCE_NOT_FOUND',
+                    'AGREEMENT_NOT_FOUND',
+                    'DEVELOPER_CREDITS_EXHAUSTED',
+                    'VALIDATION_OR_BUSINESS_RULE',
+                    'BUSINESS_RULE_FAILURE',
+                ],
+                transport_errors: [
+                    { status: 400, reason: 'Invalid JSON or missing tool name' },
+                    { status: 401, reason: 'Missing/invalid API key in Authorization header' },
+                    { status: 403, reason: 'Tool blocked by client policy' },
+                    { status: 404, reason: 'Unknown tool name' },
+                    { status: 429, reason: 'Rate limit exceeded' },
+                    { status: 500, reason: 'Unhandled server error' },
+                ],
+                domain_error_codes_reference: 'https://raw.githubusercontent.com/shabaaspay/shabaas-ai/main/openapi/openapi.yaml',
+                note: 'Domain-level failures are returned in StandardResponse summary/raw fields and may include upstream error_code values from ShaBaas APIs.',
+            },
+        },
         direct_api_access: {
             description: 'You can also call ShaBaas API directly through this proxy',
             base_url: '/api',