@lerianstudio/matcher-mcp 5.0.0-beta.62 → 5.0.0-beta.63

package/README.md

@@ -44,13 +44,16 @@ as the matcher app, which also pins the embedded OpenAPI spec to the matched
 matcher version. The bearer token the relay forwards is never baked into the
 image.
 
-It speaks **Streamable HTTP** and binds `MCP_PORT` (default `4019`), exposing two
-endpoints:
+It speaks **Streamable HTTP** and binds `MCP_PORT` (default `4019`). The server
+also hosts the optional console copilot and voice routes:
 
 | Method | Path       | Purpose                                          |
 |--------|------------|--------------------------------------------------|
 | `GET`  | `/healthz` | Plain liveness probe.                            |
 | `POST` | `/mcp`     | The Streamable HTTP MCP endpoint clients connect to. |
+| `POST` | `/agent/turns` | Stream an authenticated copilot turn when a provider is configured. |
+| `GET` | `/agent/transcribe` | Report voice-transcription availability for the authenticated caller. |
+| `POST` | `/agent/transcribe` | Transcribe an authenticated voice recording when configured. |
 
 Point any Streamable-HTTP MCP client at `POST /mcp` and send the matcher bearer
 token as the `Authorization` header.
@@ -73,6 +76,9 @@ Three options for `<mcp-url>`:
 - **Local matcher dev (repo clone).** `make up` brings the relay up as a compose
   service on `:4019` alongside the rest of the stack (`restart: unless-stopped`,
   so it stays up — no separate process to babysit). Use `http://localhost:4019/mcp`.
+  If Matcher runs on the host, stop both Compose `app` and `mcp` first and start
+  the host relay with `MATCHER_API_URL=http://localhost:4018`; the Compose relay
+  targets the Docker-only name `app:4018`. See [`../docs/development.md`](../docs/development.md).
 - **Run it standalone with `npx`.** `@lerianstudio/matcher-mcp` is a **public**
   package (Apache-2.0) — no registry auth needed. Start the relay (binds `:4019`)
   pointed at your Matcher API:
@@ -264,13 +270,14 @@ full embedded OpenAPI spec.
 | `fee_schedule_*` | Manage fee schedules — create, list, get, update, delete, and simulate. |
 | `fee_rule_*`     | Manage fee rules attached to schedules — create, list, get, update, delete. |
 | `match_rule_*`   | Manage a context's match rules — create, list, get, update, delete, reorder. |
-| `context_*`      | Manage reconciliation contexts — create, list, get, update, delete. |
-| `source_*`       | Manage a context's data sources — create, list, get, update, delete. |
+| `context_*`      | Manage reconciliation contexts — create, list, get, update, archive, restore, setup progress, and next-step guidance. |
+| `source_*`       | Manage a context's data sources — create, list, get, update, archive, and restore. |
+| `field_map_*`    | Manage field maps — create, list by context, get by source, update, and delete. |
 | `match_run_*`    | Drive reconciliation runs — start a run, list runs, get a run, inspect match groups. |
 | `exception_*`    | Work reconciliation exceptions — list/get, history and comments (list/add/delete), per-exception action verbs (dispatch, open-dispute, force-match, adjust-entry), and cross-exception bulk actions (assign/resolve/dispatch). |
 | `dispute_*`      | Manage the dispute lifecycle — list, get, close, submit evidence. |
-| `ingestion_*`    | Inspect a context's import lifecycle — list jobs, get a job, list a job's per-row errors and transactions, search transactions, ignore a transaction. |
-| `dashboard_*`    | Read a context's reporting dashboard — combined aggregates plus focused slices (cash-impact, match-rate, metrics, SLA, source-breakdown, volume). |
+| `ingestion_*`    | Inspect a context's import lifecycle — list jobs, get a job, list a job's per-row errors and transactions, search transactions, ignore a transaction, and upload files through `ingestion_upload` or `ingestion_upload_begin`. |
+| `dashboard_*`    | Read combined aggregates and focused slices (cash-impact, match-rate, metrics, SLA, source-breakdown, volume). The console uses the aggregate for volume, match rate and SLA, plus separate metrics, source-breakdown and cash-impact queries. Only standalone volume, match-rate and SLA reads have no console consumer. |
 | `report_*`       | Pull a context's reports — paginated matched/unmatched/variance reads, the summary read, four counts (exceptions/matched/unmatched/transactions), and five base64 exports (exceptions/matched/summary/unmatched/variance). |
 | `workspace_usage` | Read the caller's own commercial state and free-tier consumption — plan, billing status, both trial axes (days remaining, matched lines against the cap), the expiry verdict, and the derived percentage consumed. Takes no arguments; the workspace comes from the relayed credential. |
 
@@ -288,11 +295,16 @@ HTTP client and a single token relay, so both surfaces map matcher errors
 
 ### Intentionally not curated
 
-Multipart **file upload** (`uploadFile`) and **document extraction**
-(`extractDocument`) carry a `multipart/form-data` binary body that a JSON tool
-cannot express, and the inbound **webhook receiver** (`processCallback`) is an
-inbound endpoint, not an operator action. These are deliberately left off the
-curated surface and remain reachable only via `matcher_invoke`.
+`uploadFile` has curated replacements. Use `ingestion_upload` for a small
+base64-in-JSON payload or `ingestion_upload_begin` for a real local file; the
+relay rebuilds or brokers the multipart request. `matcher_invoke` cannot build
+that binary body and points callers to the curated tools.
+
+`extractDocument` accepts a raw document body and has no MCP path today; call
+the Matcher HTTP API directly for that operation. Inbound callback and webhook
+receivers (`processCallback`, aggregator webhooks, and hub events) stay
+generic-only because they are machine- or hub-initiated deliveries rather than
+operator actions.
 
 ## Project layout
 
@@ -309,7 +321,7 @@ mcp/
 └── src/
     ├── server.ts       # entry point: builds the per-request server, wires tools + telemetry
     ├── config.ts       # frozen, fail-loud bootstrap config
-    ├── transport/      # Streamable HTTP transport (GET /healthz + POST /mcp)
+    ├── transport/      # HTTP routing for /healthz, /mcp, /agent/turns and /agent/transcribe
     ├── auth/           # request-scoped fail-closed bearer-token relay
     ├── matcher/        # Matcher HTTP client
     ├── observability/  # OpenTelemetry init + token-free tool instrumentation
@@ -330,6 +342,9 @@ pnpm test        # run vitest
 pnpm dev         # run with --watch
 ```
 
+For the Compose and host-process topologies, including the `:4018`/`:4019`
+proxy variables used by the UI, see [`../docs/development.md`](../docs/development.md).
+
 ## Toolchain
 
 Mirrors the `ui/` sub-project: **pnpm** (`pnpm@11.5.2`), Node `>=22`, ESLint flat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerianstudio/matcher-mcp",
-  "version": "5.0.0-beta.62",
+  "version": "5.0.0-beta.63",
   "type": "module",
   "description": "Model Context Protocol server for the Matcher reconciliation engine",
   "license": "Apache-2.0",
@@ -66,6 +66,6 @@
     "eslint": "^10.4.1",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.60.1",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.11"
   }
 }