@lerianstudio/matcher-mcp 1.0.0-beta.7 → 1.0.0-beta.8

package/dist/spec/openapi.yaml

@@ -5167,7 +5167,13 @@ components:
           description: Aggregate run statistics as an open key-value map; consumers must tolerate unknown keys and treat a missing key as unknown rather than zero. Known keys include matches, candidates_left, candidates_right, unmatched_left, unmatched_right, unmatched_external, auto_matched_left, auto_matched_right, pending_review_left, pending_review_right, proposed_left, proposed_right, exceptions_raised (newly created), exceptions_updated (re-touched), plus per-rule families rule_matched:<ruleID> and rule_meta:<ruleID>:<TYPE>
           type: object
         status:
-          description: "Current status of the run: PROCESSING (in flight), COMPLETED (finished), or FAILED (errored)"
+          description: "Current status of the run: QUEUED (async submit, awaiting worker pickup), PROCESSING (in flight), FINALIZING (a transient finishing-up state — a poll MAY briefly observe it between PROCESSING and COMPLETED, and it is also observable while a run is recovered after a crash; treat it as in-flight, not terminal), COMPLETED (finished), or FAILED (errored)"
+          enum:
+            - QUEUED
+            - PROCESSING
+            - FINALIZING
+            - COMPLETED
+            - FAILED
           examples:
             - COMPLETED
           type: string
@@ -5968,6 +5974,11 @@ components:
     RunMatchRequest:
       additionalProperties: false
       properties:
+        async:
+          description: "Submit asynchronously: when true the run is queued (status QUEUED) and executed by the worker; when false/omitted the run executes in-request and the response carries the completed run (terminal status). Both paths return HTTP 202; distinguish by the response status. Poll GET /v1/matching/runs/{runId} for async progress."
+          examples:
+            - false
+          type: boolean
         mode:
           description: Execution mode
           enum:
@@ -5989,9 +6000,13 @@ components:
           format: uuid
           type: string
         status:
-          description: "Status of the run at acceptance: PROCESSING (in flight), COMPLETED (finished synchronously), or FAILED (errored)"
+          description: "Status of the run at acceptance: QUEUED (async submit, awaiting worker pickup), COMPLETED (finished synchronously), or FAILED (errored synchronously). A synchronous run is already terminal; an async run is QUEUED. Poll GET /v1/matching/runs/{runId} for async progress (PROCESSING/FINALIZING/COMPLETED)"
+          enum:
+            - QUEUED
+            - COMPLETED
+            - FAILED
           examples:
-            - PROCESSING
+            - COMPLETED
           type: string
       required:
         - runId
@@ -13530,7 +13545,10 @@ paths:
         - Matching
   /v1/matching/contexts/{contextId}/run:
     post:
-      description: Triggers a matching run for a reconciliation context. Supports DRY_RUN mode for testing rules without committing results, or COMMIT mode for persisting matches.
+      description: |-
+        Triggers a matching run for a reconciliation context. Supports DRY_RUN mode for testing rules without committing results, or COMMIT mode for persisting matches.
+
+        Submission is synchronous by default: the run executes inside the request and the 202 response carries the run id and its terminal status (COMPLETED or FAILED). Set `async: true` to submit asynchronously: the run is created in QUEUED state, the request returns 202 immediately with `{runId, status: QUEUED}` WITHOUT executing in-request, and the matching worker executes it. Distinguish the two by the response `status`: a synchronous run is already terminal (COMPLETED/FAILED), an async run is QUEUED. For the async path, poll `GET /v1/matching/runs/{runId}` until status transitions QUEUED -> PROCESSING -> COMPLETED (or FAILED). A poll MAY briefly observe FINALIZING (a transient finishing-up state) between PROCESSING and COMPLETED; treat it as in-flight, not terminal.
       operationId: runMatch
       parameters:
         - description: Reconciliation context ID

package/dist/tools/matching/get.js

@@ -3,6 +3,8 @@
 // Reads one match run's detail by id: status, timing, aggregate stats, and the
 // per-rule matched-group counts (ruleStats). The matcher payload is returned
 // verbatim — this is how an operator polls a run started by `match_run_start`.
+// In-flight states (keep polling): QUEUED, PROCESSING, FINALIZING. Terminal
+// states (stop): COMPLETED, FAILED.
 //
 // Path/query split (per the spec): `runId` is the PATH param, but `contextId` is
 // a REQUIRED QUERY param (not part of the path), so matcher can scope the run to
@@ -32,10 +34,13 @@ export function registerMatchRunGetTool(server) {
     server.registerTool('match_run_get', {
         description: 'Fetch a single match run by id, including status, timing, aggregate ' +
             'statistics, and per-rule matched-group counts. Use this to poll a run ' +
-            'started by match_run_start. Requires runId and contextId (contextId is ' +
-            'sent as a query param). Both are routing params scoped to your token; no ' +
-            'tenant field is accepted. Returns the run detail, or a structured RFC ' +
-            '9457 error (e.g. 404).',
+            'started by match_run_start. status is one of: QUEUED, PROCESSING, ' +
+            'FINALIZING (all IN-FLIGHT — still running, keep polling; FINALIZING is a ' +
+            'transient near-done state, not an error) or COMPLETED, FAILED (TERMINAL ' +
+            '— stop polling). Requires runId and contextId (contextId is sent as a ' +
+            'query param). Both are routing params scoped to your token; no tenant ' +
+            'field is accepted. Returns the run detail, or a structured RFC 9457 ' +
+            'error (e.g. 404).',
         inputSchema: getMatchRunInputShape,
     }, async (args, extra) => {
         return dispatchMatching({

package/dist/tools/matching/get.js.map

@@ -1 +1 @@
-{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/tools/matching/get.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,uDAAuD;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEvD,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,mCAAmC,CAAC;IAChD,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,uDAAuD,CAC1D;CACJ,CAAA;AAOD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB;IACvD,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EACT,sEAAsE;YACtE,wEAAwE;YACxE,yEAAyE;YACzE,2EAA2E;YAC3E,wEAAwE;YACxE,wBAAwB;QAC1B,WAAW,EAAE,qBAAqB;KACnC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YACzB,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;SACrC,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/tools/matching/get.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,oCAAoC;AACpC,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,uDAAuD;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEvD,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,mCAAmC,CAAC;IAChD,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,uDAAuD,CAC1D;CACJ,CAAA;AAOD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB;IACvD,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EACT,sEAAsE;YACtE,wEAAwE;YACxE,oEAAoE;YACpE,2EAA2E;YAC3E,0EAA0E;YAC1E,wEAAwE;YACxE,wEAAwE;YACxE,sEAAsE;YACtE,mBAAmB;QACrB,WAAW,EAAE,qBAAqB;KACnC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YACzB,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;SACrC,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/matching/start.js

@@ -1,8 +1,12 @@
 // `match_run_start` — curated POST /v1/matching/contexts/{contextId}/run.
 //
-// Triggers a matching run for a reconciliation context. This is an async action:
-// matcher responds 202 with { runId, status } and processes in the background —
-// the operator polls `match_run_get` with the returned runId to follow progress.
+// Triggers a matching run for a reconciliation context. Both submit paths return
+// HTTP 202 with { runId, status }; the `status` distinguishes them:
+//   - sync (async omitted/false): the run executes in-request and the 202 carries
+//     the TERMINAL run — status COMPLETED or FAILED. No polling needed.
+//   - async (async:true): the run is created QUEUED and executed by a background
+//     worker; the 202 carries status QUEUED. The operator polls `match_run_get`
+//     with the returned runId to follow progress.
 // This tool does NOT auto-poll; it returns the 202 acceptance body verbatim.
 //
 // `contextId` is a routing path param (matcher validates it belongs to the
@@ -27,28 +31,50 @@ export const startMatchRunInputShape = {
         .enum(RUN_MODES)
         .describe('Execution mode. DRY_RUN tests the rules without committing any matches; ' +
         'COMMIT executes the rules and persists the resulting matches.'),
+    async: z
+        .boolean()
+        .optional()
+        .describe('Submit path (optional, default false). Both return 202 with ' +
+        '{ runId, status }; the status distinguishes them. Omit (or false) to ' +
+        'run in-request: the 202 carries the TERMINAL run (status COMPLETED or ' +
+        'FAILED). Set true to enqueue: the run is created QUEUED and a background ' +
+        'worker executes it — the 202 status is QUEUED and you poll match_run_get ' +
+        'with the runId until it reaches COMPLETED/FAILED.'),
 };
 /**
- * Register `match_run_start`. Substitutes contextId into the path and sends only
- * `{ mode }` as the body (per RunMatchRequest, which forbids extra properties).
- * Dispatches through the shared fail-closed relay; a matcher error surfaces via
- * the shared toToolError.
+ * Register `match_run_start`. Substitutes contextId into the path and sends
+ * `{ mode }` as the body, adding `async` ONLY when the caller set it (per
+ * RunMatchRequest, which accepts `async` but forbids unknown properties — so the
+ * key is omitted when undefined to keep the body minimal). Dispatches through the
+ * shared fail-closed relay; a matcher error surfaces via the shared toToolError.
  */
 export function registerMatchRunStartTool(server) {
     server.registerTool('match_run_start', {
-        description: 'Trigger a matching run for a reconciliation context. Async: returns 202 ' +
-            'with { runId, status } and processes in the background — poll ' +
-            'match_run_get with the runId to follow progress (this tool does not ' +
+        description: 'Trigger a matching run for a reconciliation context. Both submit paths ' +
+            'return 202 with { runId, status }; the status distinguishes them. Omit ' +
+            'async (or set false) to run in-request: the 202 carries the TERMINAL run ' +
+            '(status COMPLETED or FAILED). Set async:true to enqueue: the run is ' +
+            'created QUEUED and a background worker executes it (202 status QUEUED) — ' +
+            'poll match_run_get with the runId to follow progress (this tool does not ' +
             'auto-poll). mode is required: DRY_RUN tests rules without committing, ' +
             'COMMIT persists the matches. contextId is a routing param scoped to your ' +
             'token (no tenant field is accepted). Returns the acceptance body, or a ' +
-            'structured RFC 9457 error.',
+            'structured RFC 9457 error (e.g. 422 when the rule set is not ' +
+            'stream-bounded and cannot run at unbounded scale).',
         inputSchema: startMatchRunInputShape,
     }, async (args, extra) => {
+        // Omit `async` unless the caller set it — match the { mode } body style and
+        // keep the body minimal for RunMatchRequest's no-unknown-props contract.
+        const body = {
+            mode: args.mode,
+        };
+        if (args.async !== undefined) {
+            body.async = args.async;
+        }
         return dispatchMatching({
             method: 'POST',
             path: contextRunPath(args.contextId),
-            body: { mode: args.mode },
+            body,
         }, extra);
     });
 }

package/dist/tools/matching/start.js.map

@@ -1 +1 @@
-{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/tools/matching/start.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,iFAAiF;AACjF,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAA;AAEvD,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,8CAA8C,CACjD;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,QAAQ,CACP,0EAA0E;QACxE,+DAA+D,CAClE;CACJ,CAAA;AAOD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,0EAA0E;YAC1E,gEAAgE;YAChE,sEAAsE;YACtE,wEAAwE;YACxE,2EAA2E;YAC3E,yEAAyE;YACzE,4BAA4B;QAC9B,WAAW,EAAE,uBAAuB;KACrC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC;YACpC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;SAC1B,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/tools/matching/start.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,iFAAiF;AACjF,oEAAoE;AACpE,kFAAkF;AAClF,wEAAwE;AACxE,iFAAiF;AACjF,gFAAgF;AAChF,kDAAkD;AAClD,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAA;AAEvD,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,8CAA8C,CACjD;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,QAAQ,CACP,0EAA0E;QACxE,+DAA+D,CAClE;IACH,KAAK,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,8DAA8D;QAC5D,uEAAuE;QACvE,wEAAwE;QACxE,2EAA2E;QAC3E,2EAA2E;QAC3E,mDAAmD,CACtD;CACJ,CAAA;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,yEAAyE;YACzE,yEAAyE;YACzE,2EAA2E;YAC3E,sEAAsE;YACtE,2EAA2E;YAC3E,2EAA2E;YAC3E,wEAAwE;YACxE,2EAA2E;YAC3E,yEAAyE;YACzE,+DAA+D;YAC/D,oDAAoD;QACtD,WAAW,EAAE,uBAAuB;KACrC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,4EAA4E;QAC5E,yEAAyE;QACzE,MAAM,IAAI,GAA0D;YAClE,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAA;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACzB,CAAC;QACD,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC;YACpC,IAAI;SACL,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerianstudio/matcher-mcp",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "type": "module",
   "description": "Model Context Protocol server for the Matcher reconciliation engine",
   "license": "Apache-2.0",