@vallum/mcp-server 0.0.1-mcp.0

package/README.md

@@ -0,0 +1,66 @@
+# @vallum/mcp-server
+
+MCP tool facade for Vallum sponsored IOTA actions.
+
+This package exposes tool descriptors and a local callable server facade that
+routes sponsored actions through the Vallum SDK and policy gateway. It
+does not directly call IOTA, Gas Station, or transaction submission APIs.
+
+## Install
+
+For the npm prerelease, install:
+
+```sh
+npm install @vallum/mcp-server@next
+```
+
+## Current Status
+
+This source package builds both:
+
+- a programmatic MCP-shaped facade; and
+- a stdio CLI bin, `vallum-mcp`, for local MCP hosts.
+
+The CLI reads gateway configuration from the MCP server process environment
+and routes tool calls through the Vallum SDK and policy gateway. It does not
+directly call IOTA, Gas Station, or transaction submission APIs.
+
+The already-published `0.0.0-prerelease` package predates this runnable bin.
+The runnable MCP package is published as
+`@vallum/mcp-server@0.0.1-mcp.0` on the npm `next` dist-tag.
+Registry install plus local stdio execution is covered by
+`npm run smoke:npm-registry-mcp-stdio-consumer`.
+
+## Usage
+
+Run the stdio server from a package install or local tarball consumer:
+
+```sh
+VALLUM_GATEWAY_URL=http://127.0.0.1:8787 \
+VALLUM_API_KEY=replace-with-server-side-secret \
+npm exec -- vallum-mcp
+```
+
+Use placeholders in MCP host configuration files. Do not commit real
+`VALLUM_API_KEY` values.
+
+The programmatic facade remains available:
+
+```ts
+import { createIotaMcpServer } from "@vallum/mcp-server";
+
+const server = createIotaMcpServer({
+  gatewayBaseUrl: process.env.VALLUM_GATEWAY_URL!,
+  apiKey: process.env.VALLUM_API_KEY!,
+});
+
+const tools = server.listTools();
+const result = await server.callTool("iota.request_sponsored_transaction", {
+  manifest,
+});
+```
+
+Keep `VALLUM_API_KEY`, Gas Station bearer tokens, sponsor keys, raw
+transaction bytes, and user signatures server-side. See
+https://github.com/0xCozart/agentic-gaskit/blob/main/docs/vallum/package-integration-guide.md
+for the full package map and configuration boundary.

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export interface VallumMcpCliIo {
+    readonly stdout: Pick<NodeJS.WriteStream, "write">;
+    readonly stderr: Pick<NodeJS.WriteStream, "write">;
+}
+export declare function runVallumMcpCli(args: readonly string[], env: Record<string, string | undefined>, io: VallumMcpCliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import packageJson from "../package.json" with { type: "json" };
+import { VallumMcpConfigError, parseVallumMcpConfig, redactVallumMcpConfig, } from "./config.js";
+import { startVallumMcpStdioServer } from "./stdio.js";
+export async function runVallumMcpCli(args, env, io) {
+    if (args.includes("--help") || args.includes("-h")) {
+        io.stdout.write(usage());
+        return 0;
+    }
+    if (args.includes("--version")) {
+        io.stdout.write(`${packageJson.version}\n`);
+        return 0;
+    }
+    if (args.some((arg) => arg.startsWith("--") && arg !== "--check-config")) {
+        io.stderr.write("Unknown option. Run vallum-mcp --help for usage.\n");
+        return 1;
+    }
+    try {
+        const config = parseVallumMcpConfig(env, { packageVersion: packageJson.version });
+        if (args.includes("--check-config")) {
+            io.stdout.write(`${JSON.stringify(redactVallumMcpConfig(config), null, 2)}\n`);
+            return 0;
+        }
+        const session = await startVallumMcpStdioServer(config);
+        installShutdownHandlers(session.close);
+        await session.closed;
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+function installShutdownHandlers(close) {
+    const shutdown = () => {
+        void close();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}
+function usage() {
+    return `Usage: vallum-mcp [--help] [--version] [--check-config]
+
+Runs the Vallum MCP server. Configuration is read from the MCP server process environment.
+
+Required environment:
+  VALLUM_GATEWAY_URL    Vallum-compatible policy gateway base URL.
+  VALLUM_API_KEY        Gateway app credential.
+
+Optional environment:
+  VALLUM_MCP_SERVER_NAME       MCP server name, defaults to vallum.
+  VALLUM_MCP_SERVER_VERSION    MCP server version, defaults to package version.
+  VALLUM_MCP_LOG_LEVEL         silent, error, warn, info, or debug. Defaults to error.
+
+Flags:
+  --help          Print this help text without reading configuration.
+  --version       Print the package version without reading configuration.
+  --check-config  Validate configuration and print redacted status.
+`;
+}
+function formatCliError(error) {
+    if (error instanceof VallumMcpConfigError) {
+        return `Configuration error: ${error.message}`;
+    }
+    return "Vallum MCP failed before startup.";
+}
+if (isDirectCliExecution()) {
+    const exitCode = await runVallumMcpCli(process.argv.slice(2), process.env, {
+        stdout: process.stdout,
+        stderr: process.stderr,
+    });
+    process.exitCode = exitCode;
+}
+function isDirectCliExecution() {
+    const entrypoint = process.argv[1];
+    if (!entrypoint)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(entrypoint);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+export declare const VALLUM_GATEWAY_URL_ENV = "VALLUM_GATEWAY_URL";
+export declare const VALLUM_API_KEY_ENV = "VALLUM_API_KEY";
+export declare const VALLUM_MCP_SERVER_NAME_ENV = "VALLUM_MCP_SERVER_NAME";
+export declare const VALLUM_MCP_SERVER_VERSION_ENV = "VALLUM_MCP_SERVER_VERSION";
+export declare const VALLUM_MCP_LOG_LEVEL_ENV = "VALLUM_MCP_LOG_LEVEL";
+export type VallumMcpLogLevel = "silent" | "error" | "warn" | "info" | "debug";
+export interface VallumMcpConfig {
+    readonly gatewayBaseUrl: string;
+    readonly apiKey: string;
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly logLevel: VallumMcpLogLevel;
+}
+export interface VallumMcpConfigOptions {
+    readonly packageVersion?: string;
+}
+export interface RedactedVallumMcpConfig {
+    readonly gatewayUrl: "configured";
+    readonly apiKey: "configured";
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly logLevel: VallumMcpLogLevel;
+}
+export declare class VallumMcpConfigError extends Error {
+    readonly code = "VALLUM_MCP_CONFIG_ERROR";
+    constructor(message: string);
+}
+export declare function parseVallumMcpConfig(env: Record<string, string | undefined>, options?: VallumMcpConfigOptions): VallumMcpConfig;
+export declare function redactVallumMcpConfig(config: VallumMcpConfig): RedactedVallumMcpConfig;

package/dist/config.js

@@ -0,0 +1,66 @@
+export const VALLUM_GATEWAY_URL_ENV = "VALLUM_GATEWAY_URL";
+export const VALLUM_API_KEY_ENV = "VALLUM_API_KEY";
+export const VALLUM_MCP_SERVER_NAME_ENV = "VALLUM_MCP_SERVER_NAME";
+export const VALLUM_MCP_SERVER_VERSION_ENV = "VALLUM_MCP_SERVER_VERSION";
+export const VALLUM_MCP_LOG_LEVEL_ENV = "VALLUM_MCP_LOG_LEVEL";
+export class VallumMcpConfigError extends Error {
+    code = "VALLUM_MCP_CONFIG_ERROR";
+    constructor(message) {
+        super(message);
+        this.name = "VallumMcpConfigError";
+    }
+}
+export function parseVallumMcpConfig(env, options = {}) {
+    const gatewayBaseUrl = requiredEnv(env, VALLUM_GATEWAY_URL_ENV);
+    const apiKey = requiredEnv(env, VALLUM_API_KEY_ENV);
+    return {
+        gatewayBaseUrl: normalizeGatewayBaseUrl(gatewayBaseUrl),
+        apiKey,
+        serverName: optionalEnv(env, VALLUM_MCP_SERVER_NAME_ENV) ?? "vallum",
+        serverVersion: optionalEnv(env, VALLUM_MCP_SERVER_VERSION_ENV) ?? options.packageVersion ?? "0.0.0",
+        logLevel: parseLogLevel(optionalEnv(env, VALLUM_MCP_LOG_LEVEL_ENV)),
+    };
+}
+export function redactVallumMcpConfig(config) {
+    return {
+        gatewayUrl: "configured",
+        apiKey: "configured",
+        serverName: config.serverName,
+        serverVersion: config.serverVersion,
+        logLevel: config.logLevel,
+    };
+}
+function requiredEnv(env, name) {
+    const value = optionalEnv(env, name);
+    if (value === undefined) {
+        throw new VallumMcpConfigError(`${name} is required.`);
+    }
+    return value;
+}
+function optionalEnv(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+function normalizeGatewayBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new VallumMcpConfigError(`${VALLUM_GATEWAY_URL_ENV} must be an absolute http(s) URL.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new VallumMcpConfigError(`${VALLUM_GATEWAY_URL_ENV} must be an absolute http(s) URL.`);
+    }
+    url.hash = "";
+    url.search = "";
+    return url.toString().replace(/\/$/, "");
+}
+function parseLogLevel(value) {
+    if (value === undefined)
+        return "error";
+    if (value === "silent" || value === "error" || value === "warn" || value === "info" || value === "debug") {
+        return value;
+    }
+    throw new VallumMcpConfigError(`${VALLUM_MCP_LOG_LEVEL_ENV} must be one of silent, error, warn, info, or debug.`);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./server.js";
+export * from "./tools.js";
+export * from "./config.js";
+export * from "./stdio.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./server.js";
+export * from "./tools.js";
+export * from "./config.js";
+export * from "./stdio.js";

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { IOTA_MCP_TOOLS, type IotaMcpToolCallResult } from "./tools.js";
+export interface IotaMcpServerOptions {
+    readonly gatewayBaseUrl: string;
+    readonly apiKey: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => Date;
+}
+export interface IotaMcpServerFacade {
+    readonly listTools: () => typeof IOTA_MCP_TOOLS;
+    readonly callTool: (name: string, input: unknown) => Promise<IotaMcpToolCallResult>;
+}
+export declare function createIotaMcpServer(options: IotaMcpServerOptions): IotaMcpServerFacade;

package/dist/server.js

@@ -0,0 +1,16 @@
+import { IotaAgent } from "@vallum/sdk";
+import { callIotaMcpTool, IOTA_MCP_TOOLS } from "./tools.js";
+export function createIotaMcpServer(options) {
+    const agent = new IotaAgent({
+        gatewayBaseUrl: options.gatewayBaseUrl,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+    });
+    return {
+        listTools: () => IOTA_MCP_TOOLS,
+        callTool: (name, input) => callIotaMcpTool(name, input, {
+            agent,
+            now: options.now,
+        }),
+    };
+}

package/dist/stdio.d.ts

@@ -0,0 +1,22 @@
+import type { Readable, Writable } from "node:stream";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type VallumMcpConfig } from "./config.js";
+import { type IotaMcpServerOptions } from "./server.js";
+import { type IotaMcpToolCallResult } from "./tools.js";
+export interface VallumMcpProtocolServerOptions {
+    readonly fetchImpl?: IotaMcpServerOptions["fetchImpl"];
+    readonly now?: IotaMcpServerOptions["now"];
+    readonly stdin?: Readable;
+    readonly stdout?: Writable;
+}
+export interface VallumMcpStdioSession {
+    readonly server: Server;
+    readonly transport: StdioServerTransport;
+    readonly closed: Promise<void>;
+    readonly close: () => Promise<void>;
+}
+export declare function createVallumMcpProtocolServer(config: VallumMcpConfig, options?: VallumMcpProtocolServerOptions): Server;
+export declare function startVallumMcpStdioServer(config: VallumMcpConfig, options?: VallumMcpProtocolServerOptions): Promise<VallumMcpStdioSession>;
+export declare function toMcpToolResult(result: IotaMcpToolCallResult): CallToolResult;

package/dist/stdio.js

@@ -0,0 +1,69 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createIotaMcpServer } from "./server.js";
+export function createVallumMcpProtocolServer(config, options = {}) {
+    const facade = createIotaMcpServer({
+        gatewayBaseUrl: config.gatewayBaseUrl,
+        apiKey: config.apiKey,
+        fetchImpl: options.fetchImpl,
+        now: options.now,
+    });
+    const server = new Server({
+        name: config.serverName,
+        version: config.serverVersion,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: facade.listTools().map(toMcpTool),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const result = await facade.callTool(request.params.name, request.params.arguments ?? {});
+        return toMcpToolResult(result);
+    });
+    return server;
+}
+export async function startVallumMcpStdioServer(config, options = {}) {
+    const server = createVallumMcpProtocolServer(config, options);
+    const transport = new StdioServerTransport(options.stdin, options.stdout);
+    let closeStarted = false;
+    let resolveClosed;
+    const closed = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    server.onclose = resolveClosed;
+    await server.connect(transport);
+    return {
+        server,
+        transport,
+        closed,
+        close: async () => {
+            if (closeStarted)
+                return;
+            closeStarted = true;
+            await server.close();
+            resolveClosed();
+        },
+    };
+}
+export function toMcpToolResult(result) {
+    return {
+        content: [...result.content],
+        structuredContent: result.structuredContent,
+        isError: result.isError,
+    };
+}
+function toMcpTool(descriptor) {
+    return {
+        name: descriptor.name,
+        title: descriptor.title,
+        description: descriptor.description,
+        inputSchema: cloneJsonObject(descriptor.inputSchema),
+    };
+}
+function cloneJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/tools.d.ts

@@ -0,0 +1,39 @@
+import type { IotaAgent } from "@vallum/sdk";
+export declare const REQUEST_SPONSORED_TRANSACTION_TOOL = "iota.request_sponsored_transaction";
+export declare const OPEN_ESCROW_TOOL = "iota.open_escrow";
+export type IotaMcpToolName = typeof REQUEST_SPONSORED_TRANSACTION_TOOL | typeof OPEN_ESCROW_TOOL;
+export interface IotaMcpToolDescriptor {
+    readonly name: IotaMcpToolName;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+}
+export interface JsonSchemaObject {
+    readonly type: "object";
+    readonly additionalProperties?: boolean;
+    readonly required?: readonly string[];
+    readonly properties: Record<string, JsonSchemaProperty>;
+}
+export type JsonSchemaProperty = {
+    readonly type: "object";
+    readonly description?: string;
+    readonly additionalProperties?: boolean;
+} | {
+    readonly type: "string";
+    readonly description?: string;
+};
+export interface IotaMcpToolCallResult {
+    readonly content: readonly [{
+        readonly type: "text";
+        readonly text: string;
+    }];
+    readonly structuredContent: Record<string, unknown>;
+    readonly isError: boolean;
+}
+export interface IotaMcpToolHandlerOptions {
+    readonly agent: Pick<IotaAgent, "requestSponsoredAction">;
+    readonly now?: () => Date;
+}
+export declare const IOTA_MCP_TOOLS: readonly IotaMcpToolDescriptor[];
+export declare function callIotaMcpTool(name: string, input: unknown, options: IotaMcpToolHandlerOptions): Promise<IotaMcpToolCallResult>;
+export declare function isIotaMcpToolName(name: string): name is IotaMcpToolName;

package/dist/tools.js

@@ -0,0 +1,100 @@
+import { validateAgentTransactionManifest } from "@vallum/manifest";
+export const REQUEST_SPONSORED_TRANSACTION_TOOL = "iota.request_sponsored_transaction";
+export const OPEN_ESCROW_TOOL = "iota.open_escrow";
+export const IOTA_MCP_TOOLS = [
+    {
+        name: REQUEST_SPONSORED_TRANSACTION_TOOL,
+        title: "Request sponsored IOTA transaction",
+        description: "Submit an Agent Transaction Manifest through the Vallum SDK and policy gateway.",
+        inputSchema: manifestToolInputSchema(),
+    },
+    {
+        name: OPEN_ESCROW_TOOL,
+        title: "Open sponsored escrow",
+        description: "Submit an escrow Agent Transaction Manifest through the Vallum SDK and policy gateway.",
+        inputSchema: manifestToolInputSchema(),
+    },
+];
+export async function callIotaMcpTool(name, input, options) {
+    if (!isIotaMcpToolName(name)) {
+        return errorResult("UNKNOWN_TOOL", `Unknown IOTA MCP tool: ${name}`);
+    }
+    const manifestResult = manifestInput(input, options.now);
+    if (!manifestResult.ok) {
+        return errorResult("INVALID_TOOL_INPUT", manifestResult.message);
+    }
+    const result = await options.agent.requestSponsoredAction({
+        manifest: manifestResult.manifest,
+    });
+    return successResult(result);
+}
+export function isIotaMcpToolName(name) {
+    return name === REQUEST_SPONSORED_TRANSACTION_TOOL || name === OPEN_ESCROW_TOOL;
+}
+function manifestToolInputSchema() {
+    return {
+        type: "object",
+        additionalProperties: false,
+        required: ["manifest"],
+        properties: {
+            manifest: {
+                type: "object",
+                description: "Agent Transaction Manifest to submit through the policy gateway.",
+                additionalProperties: true,
+            },
+        },
+    };
+}
+function manifestInput(input, now) {
+    const record = asRecord(input);
+    if (!record)
+        return { ok: false, message: "Tool input must be a JSON object." };
+    const manifest = asRecord(record.manifest);
+    if (!manifest)
+        return { ok: false, message: "Tool input must include a manifest object." };
+    const validation = validateAgentTransactionManifest(manifest, { now: now?.() });
+    if (!validation.ok)
+        return { ok: false, message: "Tool manifest failed validation." };
+    return { ok: true, manifest: validation.manifest };
+}
+function successResult(result) {
+    if (!result.approved) {
+        return {
+            isError: true,
+            content: [{
+                    type: "text",
+                    text: result.decision.message,
+                }],
+            structuredContent: {
+                error: {
+                    code: result.decision.reasonCode,
+                    message: result.decision.message,
+                },
+                decision: result.decision,
+            },
+        };
+    }
+    return {
+        isError: false,
+        content: [{
+                type: "text",
+                text: JSON.stringify(result),
+            }],
+        structuredContent: result,
+    };
+}
+function errorResult(code, message) {
+    return {
+        isError: true,
+        content: [{
+                type: "text",
+                text: message,
+            }],
+        structuredContent: {
+            error: { code, message },
+        },
+    };
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@vallum/mcp-server",
+  "version": "0.0.1-mcp.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "vallum-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./stdio": {
+      "types": "./dist/stdio.d.ts",
+      "import": "./dist/stdio.js"
+    }
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@vallum/manifest": "0.0.0-prerelease",
+    "@vallum/sdk": "0.0.0-prerelease"
+  },
+  "devDependencies": {
+    "@vallum/policy-gateway": "0.0.0-prerelease"
+  },
+  "description": "MCP tool facade for Vallum sponsored IOTA actions.",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}