@cognexuslabs/artzain-mcp-gateway 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+### Added
+
+- An MCP gateway that lists upstream tools as `<upstream>__<tool>` and forwards `tools/call` only when the Decision API returns allow. A deny, a review, and an outage return `isError` and do not call the upstream.

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 CogNEXUS Labs, LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# ArtzAIn MCP gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@cognexuslabs/artzain-mcp-gateway` is an MCP server. It proxies the MCP servers listed in `gateway.json`. CogNEXUS Labs publishes it beside the TypeScript SDK and the OpenClaw, n8n, and Grok Bot packages.
+
+A client sees one tool list. Each tool name is `<upstream>__<tool>`. `tools/call` asks the ArtzAIn Decision API before it forwards anything. The action and the target come from the W15 taxonomy shipped in this package (`src/taxonomy.json`). An entry in the upstream's `tools` map replaces the action for that tool name. The payload `tool` field is the action the rule matches.
+
+Only an `allow` is forwarded. A `deny`, a `review`, an unrecognised outcome, a missing API key, and a Decision API outage all return `isError` and the upstream is not called. A review includes the decision id:
+
+```text
+QUEUED FOR REVIEW: this call needs human approval before it runs.
+(decision <id>)
+```
+
+A deny includes the reason. An outage says the decision is unavailable and that the gateway is failing closed. There is no offline path.
+
+Connectors which Grok Bot authenticates with its own OAuth may not be routable through the gateway. The first release targets self-hosted and API-key MCP servers.
+
+## Configure
+
+```json
+{
+  "upstreams": [
+    {
+      "name": "notes",
+      "agent_id": "notes-bot",
+      "command": ["node", "server.js"],
+      "env": { "API_TOKEN": "set-this-outside-the-repo" },
+      "tools": { "save_doc": "write_file" }
+    }
+  ]
+}
+```
+
+Each upstream has a `name`, an `agent_id`, and exactly one of `command` (a string array) or `url` (http or https). `headers` and `env` are sent to that upstream and are not written to the gateway log. `tools` maps a raw tool name to an action.
+
+The gateway reads `--config`, then `ARTZAIN_GATEWAY_CONFIG`, then `./gateway.json`. The Decision API key is `COGNEXUS_API_KEY`. `COGNEXUS_API_BASE_URL` defaults to `https://app.cognexuslabs.ai`. A child-process upstream does not inherit the gateway's environment, so its token belongs in that upstream's `env`.
+
+```bash
+node dist/cli.js --config gateway.json
+```
+
+Point an MCP client at that process over stdio. Logs stay on stderr, and stderr does not include upstream credentials or the API key.
+
+## Develop
+
+From this directory: `npm ci`, `npm test`, `npm run build`. The package version is `0.1.0`. It publishes from the public mirror on an `mcp-gateway-v<version>` tag.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "./server.js";
+const code = await run(process.argv.slice(2));
+process.exit(code);

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * gateway.json lists the upstream MCP servers this process proxies.
+ * A header or env value is a credential. Nothing in this module prints it.
+ */
+export interface UpstreamConfig {
+    name: string;
+    agentId: string;
+    command?: string[];
+    url?: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+    tools: Record<string, string>;
+}
+export interface GatewayConfig {
+    upstreams: UpstreamConfig[];
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function parseConfig(text: string): GatewayConfig;
+export declare function loadConfig(path: string): GatewayConfig;

package/dist/config.js

@@ -0,0 +1,120 @@
+/**
+ * gateway.json lists the upstream MCP servers this process proxies.
+ * A header or env value is a credential. Nothing in this module prints it.
+ */
+import { readFileSync } from "node:fs";
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,40}$/;
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+function stringMap(value, label) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ConfigError(`${label} must be an object of strings`);
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== "string" || item.length === 0) {
+            throw new ConfigError(`${label}.${key} must be a non-empty string`);
+        }
+        out[key] = item;
+    }
+    return out;
+}
+function oneUpstream(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ConfigError(`upstreams[${index}] must be an object`);
+    }
+    const row = value;
+    const name = row.name;
+    const agentId = row.agent_id;
+    if (typeof name !== "string" || !NAME.test(name)) {
+        throw new ConfigError(`upstreams[${index}].name must match ${NAME.source}`);
+    }
+    if (typeof agentId !== "string" || agentId.trim() === "") {
+        throw new ConfigError(`upstreams[${index}].agent_id must be a non-empty string`);
+    }
+    const command = row.command;
+    const url = row.url;
+    const hasCommand = command !== undefined;
+    const hasUrl = url !== undefined;
+    if (hasCommand === hasUrl) {
+        throw new ConfigError(`upstreams[${index}] needs exactly one of command or url`);
+    }
+    let parsedCommand;
+    let parsedUrl;
+    if (hasCommand) {
+        if (!Array.isArray(command) || command.length === 0 || command.some((part) => typeof part !== "string" || part === "")) {
+            throw new ConfigError(`upstreams[${index}].command must be a non-empty array of strings`);
+        }
+        parsedCommand = command;
+    }
+    else {
+        if (typeof url !== "string" || url.trim() === "") {
+            throw new ConfigError(`upstreams[${index}].url must be a non-empty string`);
+        }
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new ConfigError(`upstreams[${index}].url is not a URL`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new ConfigError(`upstreams[${index}].url must be http or https`);
+        }
+        parsedUrl = url;
+    }
+    return {
+        name,
+        agentId: agentId.trim(),
+        command: parsedCommand,
+        url: parsedUrl,
+        headers: stringMap(row.headers, `upstreams[${index}].headers`),
+        env: stringMap(row.env, `upstreams[${index}].env`),
+        tools: stringMap(row.tools, `upstreams[${index}].tools`),
+    };
+}
+export function parseConfig(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ConfigError("gateway.json is not JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ConfigError("gateway.json must be an object");
+    }
+    const upstreams = parsed.upstreams;
+    if (!Array.isArray(upstreams) || upstreams.length === 0) {
+        throw new ConfigError("upstreams must be a non-empty array");
+    }
+    const rows = upstreams.map((row, index) => oneUpstream(row, index));
+    const names = rows.map((row) => row.name);
+    for (let i = 0; i < names.length; i += 1) {
+        for (let j = i + 1; j < names.length; j += 1) {
+            const left = names[i] ?? "";
+            const right = names[j] ?? "";
+            if (left === right || left.startsWith(`${right}_`) || right.startsWith(`${left}_`)) {
+                throw new ConfigError(`upstream names ${left} and ${right} overlap as tool prefixes`);
+            }
+        }
+    }
+    return { upstreams: rows };
+}
+export function loadConfig(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const code = err.code ?? "unreadable";
+        throw new ConfigError(`cannot read the gateway config (${code})`);
+    }
+    return parseConfig(text);
+}

package/dist/decide.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One Decision API call. A missing key, a transport failure, a redirect, or
+ * any outcome other than allow is a block. This client has no offline path:
+ * it never returns a synthetic allow.
+ */
+export interface DecisionRequest {
+    agentId: string;
+    action: string;
+    target: string;
+    payload: string;
+    requestId?: string;
+}
+export interface Decision {
+    outcome: string;
+    decisionId: string;
+    reasons: string[];
+}
+export declare class DecisionError extends Error {
+    constructor(message: string);
+}
+export declare function decide(request: DecisionRequest, env?: NodeJS.ProcessEnv): Promise<Decision>;

package/dist/decide.js

@@ -0,0 +1,93 @@
+/**
+ * One Decision API call. A missing key, a transport failure, a redirect, or
+ * any outcome other than allow is a block. This client has no offline path:
+ * it never returns a synthetic allow.
+ */
+import { randomUUID } from "node:crypto";
+const DEFAULT_BASE = "https://app.cognexuslabs.ai";
+const TIMEOUT_MS = 10_000;
+export class DecisionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DecisionError";
+    }
+}
+function failureKind(err) {
+    if (err && typeof err === "object") {
+        const named = err;
+        const name = named.name && named.name !== "Error" ? named.name : "";
+        const code = named.code ?? "";
+        const kind = [name, code].filter(Boolean).join(" ");
+        if (kind)
+            return kind;
+    }
+    return "Error";
+}
+function reasonsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+export async function decide(request, env = process.env) {
+    const key = env.COGNEXUS_API_KEY ?? "";
+    if (key.trim() === "") {
+        throw new DecisionError("No API key configured. Set COGNEXUS_API_KEY.");
+    }
+    const base = (env.COGNEXUS_API_BASE_URL ?? DEFAULT_BASE).replace(/\/+$/, "");
+    const url = `${base}/api/v1/decisions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            redirect: "manual",
+            signal: controller.signal,
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": key,
+            },
+            body: JSON.stringify({
+                agent_did: request.agentId,
+                action: request.action,
+                target: request.target,
+                payload: request.payload,
+                payload_kind: "tool_call",
+                surface: "mcp",
+                request_id: request.requestId ?? randomUUID(),
+                product: "artzain-mcp-gateway@0.1.0",
+            }),
+        });
+    }
+    catch (err) {
+        throw new DecisionError(`decision unavailable (${failureKind(err)}). Failing closed.`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.status >= 300 && response.status < 400) {
+        throw new DecisionError("decision unavailable (redirect). Failing closed.");
+    }
+    if (!response.ok) {
+        throw new DecisionError(`decision unavailable (HTTP ${response.status}). Failing closed.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new DecisionError("decision unavailable (bad response). Failing closed.");
+    }
+    if (!body || typeof body !== "object") {
+        throw new DecisionError("decision unavailable (bad response). Failing closed.");
+    }
+    const row = body;
+    if (typeof row.outcome !== "string" || row.outcome === "") {
+        throw new DecisionError("decision unavailable (no outcome). Failing closed.");
+    }
+    return {
+        outcome: row.outcome,
+        decisionId: typeof row.decision_id === "string" ? row.decision_id : "",
+        reasons: reasonsOf(row.reasons),
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The gateway speaks MCP on stdin and stdout. A tools/call is forwarded only
+ * when the Decision API returns allow. Every other outcome, including an
+ * outage, is isError and the upstream is not called.
+ */
+import { type GatewayConfig } from "./config.js";
+export declare class Gateway {
+    private readonly config;
+    private readonly sessions;
+    constructor(config: GatewayConfig);
+    listTools(): Promise<unknown>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    close(): void;
+    private route;
+    private session;
+}
+interface RpcRequest {
+    jsonrpc?: string;
+    id?: number | string | null;
+    method?: string;
+    params?: unknown;
+}
+export declare function handleRequest(gateway: Gateway, request: RpcRequest): Promise<string | undefined>;
+export declare function serve(config: GatewayConfig, input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<void>;
+export declare function run(argv: string[]): Promise<number>;
+export {};

package/dist/server.js

@@ -0,0 +1,219 @@
+/**
+ * The gateway speaks MCP on stdin and stdout. A tools/call is forwarded only
+ * when the Decision API returns allow. Every other outcome, including an
+ * outage, is isError and the upstream is not called.
+ */
+import { createInterface } from "node:readline";
+import { ConfigError, loadConfig } from "./config.js";
+import { decide, DecisionError } from "./decide.js";
+import { classifyTool } from "./taxonomy.js";
+import { openUpstream, UpstreamError } from "./upstream.js";
+const PROTOCOL = "2024-11-05";
+function textResult(text, isError) {
+    return { content: [{ type: "text", text }], isError };
+}
+function stringArgs(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
+            out[key] = String(item);
+        }
+    }
+    return out;
+}
+function refusal(decision) {
+    const id = decision.decisionId ? `\n(decision ${decision.decisionId})` : "";
+    if (decision.outcome === "review") {
+        return `QUEUED FOR REVIEW: this call needs human approval before it runs.${id}`;
+    }
+    if (decision.outcome === "deny") {
+        const reasons = decision.reasons.length > 0 ? decision.reasons.join("; ") : "policy denied this call";
+        return `REFUSED: ${reasons}${id}`;
+    }
+    return `REFUSED: unrecognised outcome ${JSON.stringify(decision.outcome)}. Failing closed.${id}`;
+}
+export class Gateway {
+    config;
+    sessions = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    async listTools() {
+        const tools = [];
+        for (const upstream of this.config.upstreams) {
+            let listed;
+            try {
+                listed = await this.session(upstream).then((session) => session.listTools());
+            }
+            catch (err) {
+                const kind = err instanceof UpstreamError ? err.message : "the upstream could not be listed";
+                throw new UpstreamError(`upstream ${upstream.name}: ${kind}`);
+            }
+            for (const tool of listed) {
+                if (!tool || typeof tool !== "object")
+                    continue;
+                const row = tool;
+                if (typeof row.name !== "string" || row.name === "")
+                    continue;
+                tools.push({
+                    name: `${upstream.name}__${row.name}`,
+                    description: typeof row.description === "string" ? row.description : "",
+                    inputSchema: row.inputSchema ?? { type: "object" },
+                });
+            }
+        }
+        return { tools };
+    }
+    async callTool(name, args) {
+        const routed = this.route(name);
+        if (!routed)
+            return textResult(`Unknown tool ${JSON.stringify(name)}.`, true);
+        const override = routed.upstream.tools[routed.tool];
+        const classified = classifyTool(routed.tool, stringArgs(args));
+        const action = override || classified.action;
+        const payload = JSON.stringify({ tool: action, arguments: args ?? {} });
+        let decision;
+        try {
+            decision = await decide({
+                agentId: routed.upstream.agentId,
+                action,
+                target: classified.target,
+                payload,
+            });
+        }
+        catch (err) {
+            const message = err instanceof DecisionError ? err.message : "decision unavailable (Error). Failing closed.";
+            return textResult(`REFUSED: ${message}`, true);
+        }
+        if (decision.outcome !== "allow")
+            return textResult(refusal(decision), true);
+        try {
+            const session = await this.session(routed.upstream);
+            const result = await session.callTool(routed.tool, args ?? {});
+            if (result && typeof result === "object")
+                return result;
+            return textResult("the upstream returned an empty result", true);
+        }
+        catch (err) {
+            const message = err instanceof UpstreamError ? err.message : "the upstream call failed";
+            return textResult(`FAILED: ${message}`, true);
+        }
+    }
+    close() {
+        for (const session of this.sessions.values())
+            session.close();
+        this.sessions.clear();
+    }
+    route(name) {
+        const upstream = this.config.upstreams.find((row) => name.startsWith(`${row.name}__`));
+        if (!upstream)
+            return undefined;
+        const tool = name.slice(upstream.name.length + 2);
+        if (tool === "")
+            return undefined;
+        return { upstream, tool };
+    }
+    async session(upstream) {
+        const existing = this.sessions.get(upstream.name);
+        if (existing)
+            return existing;
+        const opened = openUpstream(upstream);
+        try {
+            await opened.start();
+        }
+        catch (err) {
+            opened.close();
+            throw err;
+        }
+        this.sessions.set(upstream.name, opened);
+        return opened;
+    }
+}
+function reply(id, result) {
+    return `${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, result })}\n`;
+}
+function fail(id, code, message) {
+    return `${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error: { code, message } })}\n`;
+}
+export async function handleRequest(gateway, request) {
+    const { id, method, params } = request;
+    if (method === "notifications/initialized" || method === "notifications/cancelled")
+        return undefined;
+    if (id === undefined)
+        return undefined;
+    if (method === "initialize") {
+        return reply(id, {
+            protocolVersion: PROTOCOL,
+            capabilities: { tools: {} },
+            serverInfo: { name: "artzain-mcp-gateway", version: "0.1.0" },
+        });
+    }
+    if (method === "ping")
+        return reply(id, {});
+    if (method === "tools/list") {
+        try {
+            return reply(id, await gateway.listTools());
+        }
+        catch (err) {
+            const message = err instanceof UpstreamError ? err.message : "the tool list failed";
+            return fail(id, -32000, message);
+        }
+    }
+    if (method === "tools/call") {
+        const row = (params ?? {});
+        if (typeof row.name !== "string")
+            return fail(id, -32602, "tools/call needs a tool name");
+        return reply(id, await gateway.callTool(row.name, row.arguments));
+    }
+    return fail(id, -32601, "Method not found");
+}
+export async function serve(config, input, output) {
+    const gateway = new Gateway(config);
+    const stop = () => gateway.close();
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    process.on("exit", stop);
+    const lines = createInterface({ input });
+    for await (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let request;
+        try {
+            request = JSON.parse(trimmed);
+        }
+        catch {
+            output.write(fail(null, -32700, "Parse error"));
+            continue;
+        }
+        const response = await handleRequest(gateway, request);
+        if (response)
+            output.write(response);
+    }
+    gateway.close();
+}
+export async function run(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write("artzain-mcp-gateway --config gateway.json\n");
+        return 0;
+    }
+    const flag = argv.indexOf("--config");
+    const path = flag >= 0 ? argv[flag + 1] : process.env.ARTZAIN_GATEWAY_CONFIG || "gateway.json";
+    if (!path) {
+        process.stderr.write("a config path is required\n");
+        return 2;
+    }
+    let config;
+    try {
+        config = loadConfig(path);
+    }
+    catch (err) {
+        const message = err instanceof ConfigError ? err.message : "cannot read the gateway config";
+        process.stderr.write(`${message}\n`);
+        return 2;
+    }
+    await serve(config, process.stdin, process.stdout);
+    return 0;
+}

package/dist/taxonomy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The W15 tool taxonomy: a connector tool name becomes one action and one
+ * target. The action is what a policy rule matches. The target is
+ * `<system>:<kind>/<id>`, for example `slack:channel/C123` or
+ * `github:repo/acme/inventory`.
+ */
+export declare const UNKNOWN_ACTION = "unknown_tool";
+export interface ClassifiedTool {
+    action: string;
+    target: string;
+    known: boolean;
+}
+/**
+ * The action and target for a connector tool name. `args` fills the id in
+ * the target template. An unknown name is `unknown_tool` and
+ * `unknown:tool/<name>`.
+ */
+export declare function classifyTool(name: string, args?: Record<string, string>): ClassifiedTool;

package/dist/taxonomy.js

@@ -0,0 +1,58 @@
+/**
+ * The W15 tool taxonomy: a connector tool name becomes one action and one
+ * target. The action is what a policy rule matches. The target is
+ * `<system>:<kind>/<id>`, for example `slack:channel/C123` or
+ * `github:repo/acme/inventory`.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const UNKNOWN_ACTION = "unknown_tool";
+let cached;
+function readTaxonomy() {
+    if (cached)
+        return cached;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(here, "taxonomy.json"), join(here, "..", "src", "taxonomy.json")];
+    for (const path of candidates) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (!parsed || !Array.isArray(parsed.actions) || !parsed.tools) {
+                cached = { problem: "taxonomy.json is not a tool map" };
+                return cached;
+            }
+            cached = parsed;
+            return cached;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT") {
+                cached = { problem: code ?? "unreadable" };
+                return cached;
+            }
+        }
+    }
+    cached = { problem: "ENOENT" };
+    return cached;
+}
+function fill(template, args) {
+    const filled = template.replace(/\{([A-Za-z0-9_]+)\}/g, (_match, key) => args[key] ?? "");
+    return filled.replace(/\/+$/, "");
+}
+/**
+ * The action and target for a connector tool name. `args` fills the id in
+ * the target template. An unknown name is `unknown_tool` and
+ * `unknown:tool/<name>`.
+ */
+export function classifyTool(name, args = {}) {
+    const taxonomy = readTaxonomy();
+    const raw = name.trim();
+    if ("problem" in taxonomy) {
+        return { action: UNKNOWN_ACTION, target: `unknown:tool/${raw}`, known: false };
+    }
+    const row = taxonomy.tools[raw.toLowerCase()];
+    if (!row) {
+        return { action: UNKNOWN_ACTION, target: `unknown:tool/${raw}`, known: false };
+    }
+    return { action: row.action, target: fill(row.target, args), known: true };
+}

package/dist/taxonomy.json

@@ -0,0 +1,62 @@
+{
+  "actions": [
+    "send_email",
+    "send_chat_message",
+    "send_agent_message",
+    "post_public",
+    "create_ticket",
+    "update_ticket",
+    "create_event",
+    "update_event",
+    "purchase",
+    "delete_resource",
+    "share_resource",
+    "write_file",
+    "run_command",
+    "write_repo",
+    "publish_package",
+    "submit_form",
+    "unknown_tool"
+  ],
+  "tools": {
+    "send_email": { "action": "send_email", "target": "email:mailbox/{to}" },
+    "gmail_send_email": { "action": "send_email", "target": "gmail:message/{to}" },
+    "outlook_send_mail": { "action": "send_email", "target": "outlook:message/{to}" },
+    "compose_email": { "action": "send_email", "target": "email:mailbox/{to}" },
+    "slack_send_message": { "action": "send_chat_message", "target": "slack:channel/{channel}" },
+    "slack_post_message": { "action": "send_chat_message", "target": "slack:channel/{channel}" },
+    "post_message": { "action": "send_chat_message", "target": "slack:channel/{channel}" },
+    "teams_post_message": { "action": "send_chat_message", "target": "teams:channel/{channel}" },
+    "send_sms": { "action": "send_chat_message", "target": "sms:number/{to}" },
+    "send_chat_message": { "action": "send_chat_message", "target": "chat:channel/{channel}" },
+    "send_agent_message": { "action": "send_agent_message", "target": "agent:bot/{to}" },
+    "post_to_x": { "action": "post_public", "target": "x:post/{account}" },
+    "tweet": { "action": "post_public", "target": "x:post/{account}" },
+    "post_to_linkedin": { "action": "post_public", "target": "linkedin:post/{author}" },
+    "post_public": { "action": "post_public", "target": "web:post/{account}" },
+    "create_ticket": { "action": "create_ticket", "target": "ticket:issue/{title}" },
+    "jira_create_issue": { "action": "create_ticket", "target": "jira:issue/{project}" },
+    "update_ticket": { "action": "update_ticket", "target": "ticket:issue/{id}" },
+    "jira_update_issue": { "action": "update_ticket", "target": "jira:issue/{issue}" },
+    "create_event": { "action": "create_event", "target": "calendar:event/{calendar}" },
+    "gcal_create_event": { "action": "create_event", "target": "google:event/{calendar}" },
+    "update_event": { "action": "update_event", "target": "calendar:event/{event_id}" },
+    "purchase": { "action": "purchase", "target": "payment:order/{sku}" },
+    "place_order": { "action": "purchase", "target": "payment:order/{sku}" },
+    "checkout": { "action": "purchase", "target": "payment:order/{cart}" },
+    "pay_invoice": { "action": "purchase", "target": "payment:invoice/{invoice_id}" },
+    "wire_transfer": { "action": "purchase", "target": "bank:transfer/{account}" },
+    "delete_resource": { "action": "delete_resource", "target": "resource:item/{id}" },
+    "delete_file": { "action": "delete_resource", "target": "file:path/{path}" },
+    "share_resource": { "action": "share_resource", "target": "drive:file/{file}" },
+    "share_file": { "action": "share_resource", "target": "drive:file/{file}" },
+    "write_file": { "action": "write_file", "target": "file:path/{path}" },
+    "run_command": { "action": "run_command", "target": "shell:host/{host}" },
+    "execute_command": { "action": "run_command", "target": "shell:host/{host}" },
+    "write_repo": { "action": "write_repo", "target": "github:repo/{repo}" },
+    "github_create_pr": { "action": "write_repo", "target": "github:repo/{repo}" },
+    "publish_package": { "action": "publish_package", "target": "registry:package/{name}" },
+    "npm_publish": { "action": "publish_package", "target": "npm:package/{name}" },
+    "submit_form": { "action": "submit_form", "target": "form:page/{url}" }
+  }
+}

package/dist/upstream.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One upstream MCP session, over a child process or an HTTP POST.
+ * Stderr from a child, and response headers from an HTTP server, can carry
+ * a token. This module reads them only to keep the pipes moving, and it
+ * never writes them out.
+ */
+import type { UpstreamConfig } from "./config.js";
+export interface RpcMessage {
+    jsonrpc?: string;
+    id?: number | string | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code?: number;
+        message?: string;
+    };
+}
+export declare class UpstreamError extends Error {
+    constructor(message: string);
+}
+export declare class StdioUpstream {
+    private child;
+    private pending;
+    private nextId;
+    private readonly command;
+    private readonly env;
+    constructor(config: UpstreamConfig);
+    start(): Promise<void>;
+    listTools(): Promise<unknown[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    close(): void;
+    private notify;
+    private request;
+    private takeLine;
+    private failAll;
+}
+export declare class HttpUpstream {
+    private session;
+    private nextId;
+    private started;
+    private readonly url;
+    private readonly headers;
+    constructor(config: UpstreamConfig);
+    start(): Promise<void>;
+    listTools(): Promise<unknown[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    close(): void;
+    private request;
+    private post;
+}
+export type Upstream = StdioUpstream | HttpUpstream;
+export declare function openUpstream(config: UpstreamConfig): Upstream;

package/dist/upstream.js

@@ -0,0 +1,229 @@
+/**
+ * One upstream MCP session, over a child process or an HTTP POST.
+ * Stderr from a child, and response headers from an HTTP server, can carry
+ * a token. This module reads them only to keep the pipes moving, and it
+ * never writes them out.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+const PROTOCOL = "2024-11-05";
+const CLIENT = { name: "artzain-mcp-gateway", version: "0.1.0" };
+export class UpstreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UpstreamError";
+    }
+}
+function childEnv(extra) {
+    const env = {};
+    for (const key of ["PATH", "Path", "PATHEXT", "SYSTEMROOT", "SystemRoot", "COMSPEC", "HOME", "USERPROFILE", "TEMP", "TMP"]) {
+        const value = process.env[key];
+        if (value)
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(extra))
+        env[key] = value;
+    return env;
+}
+export class StdioUpstream {
+    child;
+    pending = new Map();
+    nextId = 1;
+    command;
+    env;
+    constructor(config) {
+        this.command = config.command ?? [];
+        this.env = config.env ?? {};
+    }
+    async start() {
+        if (this.child)
+            return;
+        const [file, ...args] = this.command;
+        if (!file)
+            throw new UpstreamError("the upstream command is empty");
+        const child = spawn(file, args, { stdio: ["pipe", "pipe", "pipe"], env: childEnv(this.env), windowsHide: true });
+        this.child = child;
+        child.stderr.on("data", () => undefined);
+        child.on("error", (err) => this.failAll(new UpstreamError(`the upstream process failed (${err.name})`)));
+        child.on("exit", () => this.failAll(new UpstreamError("the upstream process exited")));
+        const lines = createInterface({ input: child.stdout });
+        lines.on("line", (line) => this.takeLine(line));
+        await this.request("initialize", {
+            protocolVersion: PROTOCOL,
+            capabilities: {},
+            clientInfo: CLIENT,
+        });
+        this.notify("notifications/initialized");
+    }
+    async listTools() {
+        const result = await this.request("tools/list", {});
+        const tools = result.tools;
+        if (!Array.isArray(tools))
+            throw new UpstreamError("the upstream tools list is not an array");
+        return tools;
+    }
+    async callTool(name, args) {
+        return this.request("tools/call", { name, arguments: args ?? {} });
+    }
+    close() {
+        this.child?.kill();
+        this.child = undefined;
+    }
+    notify(method) {
+        this.child?.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method })}\n`);
+    }
+    request(method, params) {
+        const child = this.child;
+        if (!child)
+            return Promise.reject(new UpstreamError("the upstream is not running"));
+        const id = this.nextId;
+        this.nextId += 1;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new UpstreamError("the upstream timed out"));
+            }, 10_000);
+            this.pending.set(id, {
+                resolve: (message) => {
+                    clearTimeout(timer);
+                    if (message.error) {
+                        const code = message.error.code ?? -1;
+                        reject(new UpstreamError(`the upstream rejected the call (${code})`));
+                        return;
+                    }
+                    resolve(message.result);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        });
+    }
+    takeLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        if (typeof message.id !== "number")
+            return;
+        const waiter = this.pending.get(message.id);
+        if (!waiter)
+            return;
+        this.pending.delete(message.id);
+        waiter.resolve(message);
+    }
+    failAll(err) {
+        for (const waiter of this.pending.values())
+            waiter.reject(err);
+        this.pending.clear();
+        this.child = undefined;
+    }
+}
+export class HttpUpstream {
+    session;
+    nextId = 1;
+    started = false;
+    url;
+    headers;
+    constructor(config) {
+        this.url = config.url ?? "";
+        this.headers = config.headers ?? {};
+    }
+    async start() {
+        if (this.started)
+            return;
+        await this.request("initialize", {
+            protocolVersion: PROTOCOL,
+            capabilities: {},
+            clientInfo: CLIENT,
+        });
+        await this.post({ jsonrpc: "2.0", method: "notifications/initialized" });
+        this.started = true;
+    }
+    async listTools() {
+        const result = await this.request("tools/list", {});
+        const tools = result.tools;
+        if (!Array.isArray(tools))
+            throw new UpstreamError("the upstream tools list is not an array");
+        return tools;
+    }
+    async callTool(name, args) {
+        return this.request("tools/call", { name, arguments: args ?? {} });
+    }
+    close() {
+        this.started = false;
+    }
+    async request(method, params) {
+        const id = this.nextId;
+        this.nextId += 1;
+        const message = await this.post({ jsonrpc: "2.0", id, method, params });
+        if (message.error) {
+            const code = message.error.code ?? -1;
+            throw new UpstreamError(`the upstream rejected the call (${code})`);
+        }
+        return message.result;
+    }
+    async post(body) {
+        const headers = {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            ...this.headers,
+        };
+        if (this.session)
+            headers["mcp-session-id"] = this.session;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10_000);
+        let response;
+        try {
+            response = await fetch(this.url, {
+                method: "POST",
+                redirect: "manual",
+                signal: controller.signal,
+                headers,
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            const name = err && typeof err === "object" && "name" in err ? String(err.name) : "Error";
+            throw new UpstreamError(`the upstream is unreachable (${name})`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status >= 300 && response.status < 400) {
+            throw new UpstreamError("the upstream redirected the call");
+        }
+        const session = response.headers.get("mcp-session-id");
+        if (session)
+            this.session = session;
+        if (!response.ok) {
+            throw new UpstreamError(`the upstream rejected the call (HTTP ${response.status})`);
+        }
+        const type = response.headers.get("content-type") ?? "";
+        const text = await response.text();
+        const payload = type.includes("text/event-stream")
+            ? text.split("\n").find((line) => line.startsWith("data: "))?.slice(6)
+            : text;
+        if (body.id === undefined && !type.includes("text/event-stream"))
+            return {};
+        if (!payload)
+            throw new UpstreamError("the upstream returned an empty event stream");
+        try {
+            return JSON.parse(payload);
+        }
+        catch {
+            throw new UpstreamError("the upstream returned a response that is not JSON");
+        }
+    }
+}
+export function openUpstream(config) {
+    return config.command ? new StdioUpstream(config) : new HttpUpstream(config);
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@cognexuslabs/artzain-mcp-gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An MCP server that decides each upstream tool call with the ArtzAIn Decision API before it forwards the call.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "artzain-mcp-gateway": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CogNEXUSlabs/cognexus-tools.git",
+    "directory": "mcp-gateway"
+  },
+  "homepage": "https://cognexuslabs.ai",
+  "bugs": {
+    "url": "https://github.com/CogNEXUSlabs/cognexus-tools/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-taxonomy.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}