@atbas/m-mcp 0.1.0

package/dist/paths.js

@@ -0,0 +1,106 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { JazzCashConfigError } from './errors.js';
+/**
+ * Locate the package root, and the bundled knowledge corpus within it.
+ *
+ * The two are resolved separately and in that order. Requiring the root to
+ * contain `knowledge/` as well would make "where is this package installed" a
+ * question the corpus can answer wrongly: relocating the corpus, or serving it
+ * from somewhere that is not a directory at all, would break the same walk that
+ * also resolves `dist/`. `package.json`
+ * is the marker that actually defines a package root, so the walk asks for that
+ * and nothing else.
+ *
+ * The walk works unchanged from `src/` during development and from `dist/` after
+ * a build, which avoids a copy step and the class of bug where the built server
+ * silently serves a stale corpus.
+ */
+/** The file that marks the directory owning a package. */
+const PACKAGE_MARKER = 'package.json';
+/** Where the bundled corpus sits, relative to the package root. */
+const CORPUS_DIRECTORY = 'knowledge';
+/**
+ * Environment variable naming the corpus directory outright.
+ *
+ * The package-root walk starts from `import.meta.url`, which is only the truth
+ * while the module is executed as a file inside its own package. A bundler
+ * rewrites that value: hosting this server inside a Next.js route handler
+ * resolves the walk into `.next/`, whose `package.json` is real and whose
+ * `knowledge/` does not exist. The corpus loader then finds no documents, the
+ * search index is built over nothing, and the server answers merchant
+ * integration questions from an empty knowledge base — confidently, because
+ * nothing in that path fails. That is the worst failure mode this server has, so
+ * a deployment that knows where the corpus is says so instead of hoping.
+ *
+ * Deliberately not a tool argument, and deliberately not relative: resolving a
+ * relative path would anchor the corpus to the working directory of whichever
+ * process happened to start the server, which is exactly the unpredictable input
+ * this variable exists to remove.
+ */
+const CORPUS_DIRECTORY_VARIABLE = 'MCP_CORPUS_DIR';
+let cachedRoot;
+/**
+ * Walk upwards to the nearest directory that owns a `package.json`.
+ *
+ * Exported so the walk can be exercised from somewhere other than this module's
+ * own directory, which is the only way to prove that moving the corpus leaves
+ * root discovery intact.
+ */
+export function findPackageRoot(startDirectory) {
+    let current = resolve(startDirectory);
+    for (;;) {
+        if (existsSync(join(current, PACKAGE_MARKER))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new JazzCashConfigError(`Unable to locate the package root. Searched upwards from ${startDirectory} for a directory containing ${PACKAGE_MARKER}.`);
+        }
+        current = parent;
+    }
+}
+/** Absolute path to the package root. Cached after the first successful walk. */
+export function packageRoot() {
+    cachedRoot ??= findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+    return cachedRoot;
+}
+/**
+ * Absolute path to the directory holding the bundled corpus.
+ *
+ * Derived from the package root rather than being what identifies it, so this is
+ * the single place that has to change if the corpus stops shipping beside the
+ * code — and the single place `MCP_CORPUS_DIR` has to override.
+ *
+ * The override is validated on every call rather than memoised: the check is one
+ * `stat` in front of a file read that is about to happen anyway, and a cached
+ * answer would make the variable unreadable to anything that sets it after this
+ * module was first imported.
+ */
+export function corpusRoot() {
+    const configured = process.env[CORPUS_DIRECTORY_VARIABLE]?.trim() ?? '';
+    if (configured === '') {
+        return join(packageRoot(), CORPUS_DIRECTORY);
+    }
+    // Refused rather than resolved against `process.cwd()`. A silently resolved
+    // relative path would either find a corpus nobody meant to serve, or fall
+    // through to the empty-knowledge-base failure this variable exists to prevent.
+    if (!isAbsolute(configured)) {
+        throw new JazzCashConfigError(`${CORPUS_DIRECTORY_VARIABLE} must be an absolute path, but is "${configured}". A relative path would be resolved against the working directory of whichever process started the server, which is not something this server can predict.`);
+    }
+    // Checked here, at the one place the corpus is located, rather than left to
+    // the loader: an absent or mistyped directory yields no documents, and a
+    // server that serves no documents answers merchant questions from nothing
+    // instead of refusing to start.
+    const stats = statSync(configured, { throwIfNoEntry: false });
+    if (stats?.isDirectory() !== true) {
+        throw new JazzCashConfigError(`${CORPUS_DIRECTORY_VARIABLE} is set to "${configured}", which is not an existing directory. Point it at the ${CORPUS_DIRECTORY}/ directory that ships with this package, or unset it to resolve the corpus from the package root.`);
+    }
+    return configured;
+}
+/** Absolute path to `knowledge/`, optionally joined with further segments. */
+export function knowledgePath(...segments) {
+    return join(corpusRoot(), ...segments);
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AAEH,0DAA0D;AAC1D,MAAM,cAAc,GAAG,cAAc,CAAC;AAEtC,mEAAmE;AACnE,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,yBAAyB,GAAG,gBAAgB,CAAC;AAEnD,IAAI,UAA8B,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB;IACpD,IAAI,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEtC,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YAC9C,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,mBAAmB,CAC3B,4DAA4D,cAAc,+BAA+B,cAAc,GAAG,CAC3H,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW;IACzB,UAAU,KAAK,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAExE,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAC/C,CAAC;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,+EAA+E;IAC/E,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,mBAAmB,CAC3B,GAAG,yBAAyB,sCAAsC,UAAU,6JAA6J,CAC1O,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,gCAAgC;IAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,IAAI,KAAK,EAAE,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,mBAAmB,CAC3B,GAAG,yBAAyB,eAAe,UAAU,0DAA0D,gBAAgB,oGAAoG,CACpO,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,GAAG,QAA2B;IAC1D,OAAO,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;AACzC,CAAC"}

package/dist/prompts/integration-walkthrough.d.ts

@@ -0,0 +1,11 @@
+import type { Registrar } from '../registry.js';
+/**
+ * Guided integration walkthrough.
+ *
+ * Sequences the tools in the order a resident engineer works through them, so
+ * that a merchant's AI does not have to infer the order — which is where most
+ * self-directed integrations go wrong, typically by writing checkout code before
+ * establishing what the hash rules are.
+ */
+export declare const registerIntegrationWalkthrough: Registrar;
+//# sourceMappingURL=integration-walkthrough.d.ts.map

package/dist/prompts/integration-walkthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-walkthrough.d.ts","sourceRoot":"","sources":["../../src/prompts/integration-walkthrough.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAgD5C,CAAC"}

package/dist/prompts/integration-walkthrough.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * Guided integration walkthrough.
+ *
+ * Sequences the tools in the order a resident engineer works through them, so
+ * that a merchant's AI does not have to infer the order — which is where most
+ * self-directed integrations go wrong, typically by writing checkout code before
+ * establishing what the hash rules are.
+ */
+export const registerIntegrationWalkthrough = (server, deps) => {
+    server.registerPrompt('jazzcash_integration_walkthrough', {
+        title: 'JazzCash integration walkthrough',
+        description: 'Step-by-step guided integration: choose a flow, complete onboarding, generate code, test in sandbox, and go live.',
+        argsSchema: {
+            product: z.string().describe('What you want to accept: card, bnpl, mwallet, recurring, or refund.'),
+            platform: z.string().optional().describe('custom, woocommerce or shopify.'),
+            language: z.string().optional().describe('php, node or python.'),
+        },
+    }, ({ product, platform, language }) => {
+        const resolvedPlatform = platform ?? 'custom';
+        const resolvedLanguage = language ?? 'php';
+        const availableFlows = deps.catalogue
+            .list()
+            .map((flow) => `${flow.id} (${flow.product})`)
+            .join(', ');
+        const instructions = [
+            `I want to integrate JazzCash ${product} into a ${resolvedPlatform} application, writing ${resolvedLanguage}.`,
+            '',
+            'Work through this in order, using the jazzcash_* tools rather than general knowledge of payment gateways. Cite the document behind each answer.',
+            '',
+            '1. Call `jazzcash_list_integration_flows` and recommend one flow, saying why.',
+            '2. Call `jazzcash_get_integration_flow` for it. Summarise the mandatory parameters and any known documentation defects.',
+            `3. Call \`jazzcash_get_onboarding_checklist\` with that flow and platform "${resolvedPlatform}". Tell me what I must do in the JazzCash portal before any code runs.`,
+            `4. Call \`jazzcash_generate_integration_code\` for ${resolvedLanguage}. Explain where each generated file belongs and what still needs configuring.`,
+            '5. Call `jazzcash_generate_ipn_handler`. IPN and Status Inquiry are mandatory, not optional — do not skip them.',
+            '6. Call `jazzcash_build_transaction_parameters` to produce one signed sandbox payload, and show it to me.',
+            '7. Explain how to run the sandbox test: `jazzcash_send_gateway_request` for a REST flow, or `jazzcash_build_checkout_form` for a hosted page, which needs a human in a browser.',
+            '8. Remind me what evidence JazzCash requires before go-live.',
+            '',
+            'Rules for you:',
+            '- Never invent a parameter, endpoint or response code. If the corpus does not cover something, say so.',
+            '- Never compute the secure hash in browser JavaScript. The Integrity Salt is the HMAC key.',
+            '- Sandbox and production share identical endpoints, so remind me that going live is a credential change and to confirm which credentials are loaded before any live call.',
+            '',
+            `Flows available: ${availableFlows}.`,
+        ].join('\n');
+        return {
+            messages: [{ role: 'user', content: { type: 'text', text: instructions } }],
+        };
+    });
+};
+//# sourceMappingURL=integration-walkthrough.js.map

package/dist/prompts/integration-walkthrough.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-walkthrough.js","sourceRoot":"","sources":["../../src/prompts/integration-walkthrough.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAc,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;IACxE,MAAM,CAAC,cAAc,CACnB,kCAAkC,EAClC;QACE,KAAK,EAAE,kCAAkC;QACzC,WAAW,EACT,mHAAmH;QACrH,UAAU,EAAE;YACV,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qEAAqE,CAAC;YACnG,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;YAC3E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;SACjE;KACF,EACD,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE;QAClC,MAAM,gBAAgB,GAAG,QAAQ,IAAI,QAAQ,CAAC;QAC9C,MAAM,gBAAgB,GAAG,QAAQ,IAAI,KAAK,CAAC;QAC3C,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS;aAClC,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,OAAO,GAAG,CAAC;aAC7C,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,YAAY,GAAG;YACnB,gCAAgC,OAAO,WAAW,gBAAgB,yBAAyB,gBAAgB,GAAG;YAC9G,EAAE;YACF,iJAAiJ;YACjJ,EAAE;YACF,+EAA+E;YAC/E,yHAAyH;YACzH,8EAA8E,gBAAgB,wEAAwE;YACtK,sDAAsD,gBAAgB,+EAA+E;YACrJ,iHAAiH;YACjH,2GAA2G;YAC3G,iLAAiL;YACjL,8DAA8D;YAC9D,EAAE;YACF,gBAAgB;YAChB,wGAAwG;YACxG,4FAA4F;YAC5F,2KAA2K;YAC3K,EAAE;YACF,oBAAoB,cAAc,GAAG;SACtC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO;YACL,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC;SAC5E,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/prompts/register.d.ts

@@ -0,0 +1,4 @@
+import type { Registrar } from '../registry.js';
+/** Prompt registrars. */
+export declare const ALL_PROMPTS: readonly Registrar[];
+//# sourceMappingURL=register.d.ts.map

package/dist/prompts/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/prompts/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,yBAAyB;AACzB,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAqC,CAAC"}

package/dist/prompts/register.js

@@ -0,0 +1,4 @@
+import { registerIntegrationWalkthrough } from './integration-walkthrough.js';
+/** Prompt registrars. */
+export const ALL_PROMPTS = [registerIntegrationWalkthrough];
+//# sourceMappingURL=register.js.map

package/dist/prompts/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/prompts/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAE9E,yBAAyB;AACzB,MAAM,CAAC,MAAM,WAAW,GAAyB,CAAC,8BAA8B,CAAC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+import type { ServerDependencies } from './dependencies.js';
+import type { RegistrarFor } from './core/registry.js';
+export { applyRegistrars } from './core/registry.js';
+/**
+ * Registration signature for a registrar that may read any part of the surface,
+ * including the documentation corpus.
+ *
+ * The default for tools, resources and prompts. A registrar that reads no corpus
+ * should be typed {@link import('./core/registry.js').CoreRegistrar} instead —
+ * it remains assignable here, so declaring the narrower type costs nothing and
+ * buys a compiler-checked claim about what the handler touches.
+ */
+export type Registrar = RegistrarFor<ServerDependencies>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAOrD;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/registry.js

@@ -0,0 +1,2 @@
+export { applyRegistrars } from './core/registry.js';
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/resources/knowledge-resources.d.ts

@@ -0,0 +1,5 @@
+import type { Registrar } from '../registry.js';
+export declare const registerIndexResource: Registrar;
+export declare const registerDocumentResources: Registrar;
+export declare const registerFlowResources: Registrar;
+//# sourceMappingURL=knowledge-resources.d.ts.map

package/dist/resources/knowledge-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-resources.d.ts","sourceRoot":"","sources":["../../src/resources/knowledge-resources.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA0ChD,eAAO,MAAM,qBAAqB,EAAE,SA0CnC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,SA0BvC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,SA0BnC,CAAC"}

package/dist/resources/knowledge-resources.js

@@ -0,0 +1,121 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { resolveEndpoint } from '../catalogue/endpoints.js';
+import { JazzCashNotFoundError } from '../errors.js';
+import { CORPUS_VERSION } from '../version.js';
+/**
+ * Read-only resources.
+ *
+ * Clients that prefer to pull context rather than call a tool can read the
+ * corpus and the flow catalogue directly. URIs match the citations that tools
+ * emit, so a citation is always resolvable — and when one is not, the client is
+ * told that in the protocol's own vocabulary rather than as a server fault.
+ */
+/**
+ * JSON-RPC code the MCP specification reserves for an unknown resource URI.
+ *
+ * Spelled out because the pinned SDK's `ErrorCode` enum has no member for it.
+ * Without the translation below, the thrown {@link JazzCashNotFoundError}
+ * carries a *string* code, and the protocol layer — which emits an error code
+ * only when it is a safe integer — reports every mistyped URI as `-32603`
+ * (internal error). A client then cannot tell its own typo from a broken server.
+ */
+const RESOURCE_NOT_FOUND = -32002;
+/**
+ * Read a resource, translating "no such entry" into the protocol's own code.
+ *
+ * Resource callbacks have no `isError` channel, so unlike the tool handlers they
+ * cannot use `safeHandler`: the error has to leave through the protocol layer.
+ * Anything other than a missing entry is rethrown untouched, so a genuine server
+ * fault is still reported as one.
+ */
+function readOrNotFound(uri, read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (error instanceof JazzCashNotFoundError) {
+            throw new McpError(RESOURCE_NOT_FOUND, error.message, { uri: uri.href });
+        }
+        throw error;
+    }
+}
+export const registerIndexResource = (server, deps) => {
+    server.registerResource('jazzcash-index', 'jazzcash://index', {
+        title: 'JazzCash corpus index',
+        description: 'Every document and integration flow this server knows about.',
+        mimeType: 'application/json',
+    }, (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify({
+                    corpusVersion: CORPUS_VERSION,
+                    documents: deps.corpus.documents().map((document) => ({
+                        uri: `jazzcash://docs/${document.metadata.docId}`,
+                        docId: document.metadata.docId,
+                        title: document.metadata.title,
+                        sourcePdf: document.metadata.sourcePdf,
+                        version: document.metadata.version,
+                        sections: document.sections.map((section) => ({ id: section.sectionId, title: section.title })),
+                    })),
+                    flows: deps.catalogue.list().map((flow) => ({
+                        uri: `jazzcash://flows/${flow.id}`,
+                        id: flow.id,
+                        title: flow.title,
+                        product: flow.product,
+                        transport: flow.transport,
+                        movesMoney: flow.movesMoney,
+                        endpoint: resolveEndpoint(flow, 'sandbox'),
+                    })),
+                }, null, 2),
+            },
+        ],
+    }));
+};
+export const registerDocumentResources = (server, deps) => {
+    server.registerResource('jazzcash-doc', new ResourceTemplate('jazzcash://docs/{docId}', {
+        list: () => ({
+            resources: deps.corpus.documents().map((document) => ({
+                uri: `jazzcash://docs/${document.metadata.docId}`,
+                name: document.metadata.title,
+                description: `Curated from ${document.metadata.sourcePdf} (version ${document.metadata.version}).`,
+                mimeType: 'text/markdown',
+            })),
+        }),
+    }), {
+        title: 'JazzCash integration guide',
+        description: 'A curated JazzCash integration guide, transcribed from the official 2026 PDF.',
+        mimeType: 'text/markdown',
+    }, (uri, variables) => {
+        const docId = String(variables['docId']);
+        const document = readOrNotFound(uri, () => deps.corpus.document(docId));
+        return {
+            contents: [{ uri: uri.href, mimeType: 'text/markdown', text: document.markdown }],
+        };
+    });
+};
+export const registerFlowResources = (server, deps) => {
+    server.registerResource('jazzcash-flow', new ResourceTemplate('jazzcash://flows/{flowId}', {
+        list: () => ({
+            resources: deps.catalogue.list().map((flow) => ({
+                uri: `jazzcash://flows/${flow.id}`,
+                name: flow.title,
+                description: flow.useWhen,
+                mimeType: 'application/json',
+            })),
+        }),
+    }), {
+        title: 'JazzCash flow specification',
+        description: 'Machine-readable specification for one integration flow.',
+        mimeType: 'application/json',
+    }, (uri, variables) => {
+        const flowId = String(variables['flowId']);
+        const flow = readOrNotFound(uri, () => deps.catalogue.get(flowId));
+        return {
+            contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(flow, null, 2) }],
+        };
+    });
+};
+//# sourceMappingURL=knowledge-resources.js.map

package/dist/resources/knowledge-resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-resources.js","sourceRoot":"","sources":["../../src/resources/knowledge-resources.ts"],"names":[],"mappings":"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"}

package/dist/resources/register.d.ts

@@ -0,0 +1,4 @@
+import type { Registrar } from '../registry.js';
+/** Resource registrars. */
+export declare const ALL_RESOURCES: readonly Registrar[];
+//# sourceMappingURL=register.d.ts.map

package/dist/resources/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/resources/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,2BAA2B;AAC3B,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAI7C,CAAC"}

package/dist/resources/register.js

@@ -0,0 +1,8 @@
+import { registerDocumentResources, registerFlowResources, registerIndexResource } from './knowledge-resources.js';
+/** Resource registrars. */
+export const ALL_RESOURCES = [
+    registerIndexResource,
+    registerDocumentResources,
+    registerFlowResources,
+];
+//# sourceMappingURL=register.js.map

package/dist/resources/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/resources/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEnH,2BAA2B;AAC3B,MAAM,CAAC,MAAM,aAAa,GAAyB;IACjD,qBAAqB;IACrB,yBAAyB;IACzB,qBAAqB;CACtB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,40 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDependencies } from './dependencies.js';
+import { type Registrar } from './registry.js';
+import { type ToolDescriptor } from './tools/register.js';
+/**
+ * Composition root.
+ *
+ * Builds dependencies from the process environment, then hands them to the
+ * registration lists. It deliberately knows nothing about individual tools.
+ *
+ * The corpus-free half lives in `./core/server.js`, and this module adds the
+ * knowledge half on top. The split is not cosmetic: the three loaders imported
+ * below run at module scope for anything that reaches this file, so a host that
+ * serves only the credential tools imports the core module instead and never
+ * pays for — or gains access to — a corpus it does not serve.
+ */
+export declare function createServerDependencies(source?: NodeJS.ProcessEnv): ServerDependencies;
+/**
+ * Which parts of the surface to register.
+ *
+ * Every field defaults to the whole of it, so the stdio entry point calls
+ * `createServer(deps)` and gets exactly what it always got. The options exist
+ * for the hosted HTTP tier, which may only ever expose tools that need no
+ * merchant credential. The complementary set — the tools a merchant's local
+ * connector serves — has its own entry point in `./core/server.js`, because it
+ * must be reachable without a corpus at all.
+ *
+ * The tool list is passed as descriptors rather than as bare registrars because
+ * the caller doing the filtering has to reason about the tool's name, provider
+ * and credential dependence — none of which a `Registrar` reveals. See
+ * `src/tools/register.ts` for why that flag is written down rather than
+ * inferred from a tool's group.
+ */
+export interface ServerSurface {
+    readonly tools?: readonly ToolDescriptor[] | undefined;
+    readonly resources?: readonly Registrar[] | undefined;
+    readonly prompts?: readonly Registrar[] | undefined;
+}
+export declare function createServer(deps: ServerDependencies, surface?: ServerSurface): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK5D,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG5E;;;;;;;;;;;GAWG;AASH,wBAAgB,wBAAwB,CAAC,MAAM,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAYpG;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAAC;CACrD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,GAAE,aAAkB,GAAG,SAAS,CAsB7F"}

package/dist/server.js

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { defaultFlowSource } from './catalogue/default-catalogue.js';
+import { createCoreDependencies, SERVER_INSTRUCTIONS } from './core/server.js';
+import { loadSymptomKnowledgeBase } from './diagnostics/diagnose.js';
+import { loadKnowledgeCorpus } from './knowledge/corpus.js';
+import { buildSearchIndex } from './knowledge/search.js';
+import { ALL_PROMPTS } from './prompts/register.js';
+import { applyRegistrars } from './registry.js';
+import { ALL_RESOURCES } from './resources/register.js';
+import { TOOL_DESCRIPTORS } from './tools/register.js';
+import { SERVER_NAME, SERVER_VERSION } from './version.js';
+/**
+ * Composition root.
+ *
+ * Builds dependencies from the process environment, then hands them to the
+ * registration lists. It deliberately knows nothing about individual tools.
+ *
+ * The corpus-free half lives in `./core/server.js`, and this module adds the
+ * knowledge half on top. The split is not cosmetic: the three loaders imported
+ * below run at module scope for anything that reaches this file, so a host that
+ * serves only the credential tools imports the core module instead and never
+ * pays for — or gains access to — a corpus it does not serve.
+ */
+// `createCredentialServer`, `createCoreDependencies` and `SERVER_INSTRUCTIONS`
+// are deliberately not re-exported. This module loads the corpus at module
+// scope, so offering the corpus-free entry points through it would invite
+// exactly the import the split exists to prevent — a host serving only the
+// credential tools would pull the whole knowledge half in behind them. They live
+// in `./core/server.js`, which is where the connector reaches them.
+export function createServerDependencies(source = process.env) {
+    const core = createCoreDependencies(source, { catalogue: defaultFlowSource() });
+    const corpus = loadKnowledgeCorpus();
+    const search = buildSearchIndex(corpus);
+    const symptoms = loadSymptomKnowledgeBase();
+    core.logger.info('Knowledge corpus loaded', {
+        documents: corpus.documents().length,
+        corpusVersion: corpus.corpusVersion,
+    });
+    return { ...core, corpus, search, symptoms };
+}
+export function createServer(deps, surface = {}) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    const tools = surface.tools ?? TOOL_DESCRIPTORS;
+    const resources = surface.resources ?? ALL_RESOURCES;
+    const prompts = surface.prompts ?? ALL_PROMPTS;
+    applyRegistrars(server, deps, tools.map((descriptor) => descriptor.registrar));
+    applyRegistrars(server, deps, resources);
+    applyRegistrars(server, deps, prompts);
+    deps.logger.debug('Server surface registered', {
+        tools: tools.length,
+        resources: resources.length,
+        prompts: prompts.length,
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAuB,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,iFAAiF;AACjF,oEAAoE;AAEpE,MAAM,UAAU,wBAAwB,CAAC,SAA4B,OAAO,CAAC,GAAG;IAC9E,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,wBAAwB,EAAE,CAAC;IAE5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE;QAC1C,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM;QACpC,aAAa,EAAE,MAAM,CAAC,aAAa;KACpC,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC;AAwBD,MAAM,UAAU,YAAY,CAAC,IAAwB,EAAE,UAAyB,EAAE;IAChF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAEpH,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAAC;IAChD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,aAAa,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,WAAW,CAAC;IAE/C,eAAe,CACb,MAAM,EACN,IAAI,EACJ,KAAK,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAChD,CAAC;IACF,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACzC,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAEvC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE;QAC7C,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,SAAS,EAAE,SAAS,CAAC,MAAM;QAC3B,OAAO,EAAE,OAAO,CAAC,MAAM;KACxB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/telemetry/logger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structured logger.
+ *
+ * WRITES TO STDERR ONLY. On the MCP stdio transport `stdout` carries JSON-RPC
+ * framing; a single byte written there by application code desynchronises the
+ * client for the remainder of the session. This is enforced by an ESLint rule
+ * banning `console` and `process.stdout` in `src/`, and by a unit test.
+ */
+export declare const LOG_LEVELS: readonly ["error", "warn", "info", "debug"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export type LogContext = Readonly<Record<string, unknown>>;
+export interface Logger {
+    error(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    debug(message: string, context?: LogContext): void;
+    /** Derive a logger that attaches `bindings` to every record it emits. */
+    child(bindings: LogContext): Logger;
+}
+export interface LoggerOptions {
+    readonly level: LogLevel;
+    /** Defaults to `process.stderr`. Overridable so tests can assert on output. */
+    readonly stream?: NodeJS.WritableStream;
+    /** Injectable clock, so log assertions are deterministic. */
+    readonly now?: () => Date;
+}
+export declare function isLogLevel(value: unknown): value is LogLevel;
+export declare function createLogger(options: LoggerOptions): Logger;
+/** A logger that discards everything. Useful in tests and pure code paths. */
+export declare function createNullLogger(): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/telemetry/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/telemetry/logger.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,6CAA8C,CAAC;AAEtE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AASnD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3D,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACnD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACnD,yEAAyE;IACzE,KAAK,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IACxC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAmC3D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,MAAM,CAYzC"}

package/dist/telemetry/logger.js

@@ -0,0 +1,67 @@
+import { redactForLog } from './redaction.js';
+/**
+ * Structured logger.
+ *
+ * WRITES TO STDERR ONLY. On the MCP stdio transport `stdout` carries JSON-RPC
+ * framing; a single byte written there by application code desynchronises the
+ * client for the remainder of the session. This is enforced by an ESLint rule
+ * banning `console` and `process.stdout` in `src/`, and by a unit test.
+ */
+export const LOG_LEVELS = ['error', 'warn', 'info', 'debug'];
+const LEVEL_SEVERITY = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+};
+export function isLogLevel(value) {
+    return typeof value === 'string' && LOG_LEVELS.includes(value);
+}
+export function createLogger(options) {
+    const stream = options.stream ?? process.stderr;
+    const now = options.now ?? (() => new Date());
+    const threshold = LEVEL_SEVERITY[options.level];
+    const emit = (level, bindings, message, context) => {
+        if (LEVEL_SEVERITY[level] > threshold) {
+            return;
+        }
+        const record = {
+            timestamp: now().toISOString(),
+            level,
+            message,
+            ...redactForLog({ ...bindings, ...context }),
+        };
+        stream.write(`${JSON.stringify(record)}\n`);
+    };
+    const build = (bindings) => ({
+        error: (message, context) => {
+            emit('error', bindings, message, context);
+        },
+        warn: (message, context) => {
+            emit('warn', bindings, message, context);
+        },
+        info: (message, context) => {
+            emit('info', bindings, message, context);
+        },
+        debug: (message, context) => {
+            emit('debug', bindings, message, context);
+        },
+        child: (extra) => build({ ...bindings, ...extra }),
+    });
+    return build({});
+}
+/** A logger that discards everything. Useful in tests and pure code paths. */
+export function createNullLogger() {
+    const noop = () => {
+        /* intentionally empty */
+    };
+    const logger = {
+        error: noop,
+        warn: noop,
+        info: noop,
+        debug: noop,
+        child: () => logger,
+    };
+    return logger;
+}
+//# sourceMappingURL=logger.js.map

package/dist/telemetry/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/telemetry/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAItE,MAAM,cAAc,GAAuC;IACzD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAqBF,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAS,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhD,MAAM,IAAI,GAAG,CAAC,KAAe,EAAE,QAAoB,EAAE,OAAe,EAAE,OAAoB,EAAQ,EAAE;QAClG,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,SAAS,EAAE,CAAC;YACtC,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG;YACb,SAAS,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE;YAC9B,KAAK;YACL,OAAO;YACP,GAAI,YAAY,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,CAA6B;SAC1E,CAAC;QACF,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,CAAC,QAAoB,EAAU,EAAE,CAAC,CAAC;QAC/C,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAQ,EAAE;YAChC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAQ,EAAE;YAC/B,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAQ,EAAE;YAC/B,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAQ,EAAE;YAChC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,KAAK,EAAE,CAAC,KAAK,EAAU,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;KAC3D,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,yBAAyB;IAC3B,CAAC,CAAC;IACF,MAAM,MAAM,GAAW;QACrB,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,GAAW,EAAE,CAAC,MAAM;KAC5B,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}