@payware/mcp-server 1.3.3 → 1.5.0

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
@@ -1735,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: {
@@ -1875,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/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",