@vinaystwt/xmpp-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xMPP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @vinaystwt/xmpp-mcp
+
+Installable MCP server for xMPP.
+
+It exposes xMPP fetch, wallet, receipt, route-planning, workflow-estimation, and operator-state tools for agent clients that speak MCP over stdio.
+
+Project documentation lives at the repo root:
+
+- https://github.com/Vinaystwt/xMPP
+- https://github.com/Vinaystwt/xMPP/blob/main/docs/sdk.md

package/dist/apps/mcp-server/src/index.d.ts

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

package/dist/apps/mcp-server/src/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runXmppMcpServer } from './server.js';
+runXmppMcpServer()
+    .then(() => {
+    console.error('[xMPP] MCP server running on stdio');
+})
+    .catch((error) => {
+    console.error('[xMPP] MCP server error', error);
+    process.exit(1);
+});

package/dist/apps/mcp-server/src/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createXmppMcpServer(options?: {
+    name?: string;
+    version?: string;
+}): McpServer;
+export declare function runXmppMcpServer(options?: {
+    name?: string;
+    version?: string;
+}): Promise<McpServer>;

package/dist/apps/mcp-server/src/server.js

@@ -0,0 +1,232 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { listAgentPolicySnapshots, listAgentSessions } from '@xmpp/contract-runtime';
+import { getXmppMetadata, getXmppOperatorState, listLocalSessions, listEffectiveXmppAgentProfiles, xmppFetch, } from '@xmpp/http-interceptor';
+import { createRouter } from '@xmpp/router';
+import { getWalletInfo, verifyXmppReceipt } from '@xmpp/wallet';
+const router = createRouter();
+const signedReceiptSchema = z.object({
+    receiptId: z.string(),
+    issuedAt: z.string(),
+    network: z.string(),
+    agent: z.string(),
+    serviceId: z.string(),
+    url: z.url(),
+    method: z.string(),
+    route: z.enum(['x402', 'mpp-charge', 'mpp-session-open', 'mpp-session-reuse']),
+    amountUsd: z.number(),
+    txHash: z.string().optional(),
+    explorerUrl: z.url().optional(),
+    paymentReference: z.string().optional(),
+    signature: z.string(),
+});
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function createXmppMcpServer(options = {}) {
+    let budgetAlertState = 'clear';
+    const server = new McpServer({
+        name: options.name ?? 'xmpp',
+        version: options.version ?? '0.1.0',
+    });
+    async function maybeSendBudgetAlert(metadata) {
+        const budget = metadata?.budget;
+        if (!budget) {
+            return;
+        }
+        const spent = budget.spentThisSessionUsd;
+        const remaining = budget.remainingDailyBudgetUsd;
+        const total = spent + remaining;
+        if (total <= 0) {
+            return;
+        }
+        const ratio = spent / total;
+        const nextState = ratio >= 1 ? 'critical' : ratio >= 0.8 ? 'warning' : 'clear';
+        if (nextState === 'clear' ||
+            (budgetAlertState === 'warning' && nextState === 'warning') ||
+            budgetAlertState === nextState) {
+            budgetAlertState = nextState;
+            return;
+        }
+        budgetAlertState = nextState;
+        await server.sendLoggingMessage({
+            level: nextState === 'critical' ? 'critical' : 'warning',
+            logger: 'xmpp-budget',
+            data: {
+                spentThisSessionUsd: budget.spentThisSessionUsd,
+                remainingDailyBudgetUsd: budget.remainingDailyBudgetUsd,
+                recommendation: budget.recommendation,
+                message: nextState === 'critical'
+                    ? 'xMPP budget exhausted. Pause or raise the operator ceiling before further autopay.'
+                    : 'xMPP budget has crossed the 80% threshold. Prefer session reuse or stop premium calls.',
+            },
+        });
+    }
+    server.registerTool('xmpp_fetch', {
+        description: 'Fetch a paid resource through xMPP and auto-route payment across x402 or MPP.',
+        inputSchema: {
+            url: z.url(),
+            method: z.string().default('GET'),
+            agentId: z.string().optional(),
+            serviceId: z.string().optional(),
+            projectedRequests: z.number().int().positive().optional(),
+            streaming: z.boolean().optional(),
+            maxAutoPayUsd: z.number().positive().optional(),
+            idempotencyKey: z.string().optional(),
+        },
+    }, async ({ url, method, agentId, serviceId, projectedRequests, streaming, maxAutoPayUsd, idempotencyKey, }) => {
+        const response = await xmppFetch(url, { method }, { agentId, serviceId, projectedRequests, streaming, maxAutoPayUsd, idempotencyKey });
+        const text = await response.text();
+        const metadata = getXmppMetadata(response);
+        await maybeSendBudgetAlert(metadata);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: response.status,
+                        payment: metadata,
+                        body: safeJson(text),
+                    }, null, 2),
+                },
+            ],
+            structuredContent: {
+                status: response.status,
+                payment: metadata,
+                body: safeJson(text),
+            },
+        };
+    });
+    server.registerTool('xmpp_agent_profiles', {
+        description: 'List xMPP shared-treasury agents, their budgets, and their current spend.',
+    }, async () => {
+        const profiles = await listEffectiveXmppAgentProfiles();
+        const result = {
+            profiles,
+            contractPolicies: await listAgentPolicySnapshots(),
+            state: getXmppOperatorState(profiles).agentStates,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+    server.registerTool('xmpp_receipt_verify', {
+        description: 'Verify a signed xMPP payment receipt against the agent public key.',
+        inputSchema: {
+            receipt: signedReceiptSchema,
+        },
+    }, async ({ receipt }) => {
+        const result = verifyXmppReceipt(receipt);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+    server.registerTool('xmpp_wallet_info', {
+        description: 'Return current xMPP wallet status.',
+    }, async () => {
+        const wallet = await getWalletInfo();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(wallet, null, 2) }],
+            structuredContent: wallet,
+        };
+    });
+    server.registerTool('xmpp_policy_preview', {
+        description: 'Preview the payment route xMPP would choose without paying.',
+        inputSchema: {
+            url: z.url(),
+            method: z.string().default('GET'),
+            serviceId: z.string().optional(),
+            projectedRequests: z.number().int().positive().optional(),
+            streaming: z.boolean().optional(),
+        },
+    }, async ({ url, method, serviceId, projectedRequests, streaming }) => {
+        const preview = await router.preview({
+            url,
+            method,
+            serviceId,
+            projectedRequests,
+            streaming,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(preview, null, 2) }],
+            structuredContent: preview,
+        };
+    });
+    server.registerTool('xmpp_explain', {
+        description: 'Explain how xMPP scores routes for a request, including cost and break-even context.',
+        inputSchema: {
+            url: z.url(),
+            method: z.string().default('GET'),
+            serviceId: z.string().optional(),
+            projectedRequests: z.number().int().positive().optional(),
+            streaming: z.boolean().optional(),
+            hasReusableSession: z.boolean().optional(),
+        },
+    }, async ({ url, method, serviceId, projectedRequests, streaming, hasReusableSession }) => {
+        const explanation = router.explain({
+            url,
+            method,
+            serviceId,
+            projectedRequests,
+            streaming,
+            hasReusableSession,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(explanation, null, 2) }],
+            structuredContent: explanation,
+        };
+    });
+    server.registerTool('xmpp_session_list', {
+        description: 'List local and contract-backed xMPP sessions for the current agent.',
+    }, async () => {
+        const localSessions = listLocalSessions();
+        const contractSessions = await listAgentSessions();
+        const merged = new Map(localSessions.map((session) => [session.sessionId, session]));
+        for (const session of contractSessions) {
+            merged.set(session.sessionId, session);
+        }
+        const result = {
+            totalSessions: merged.size,
+            localSessions,
+            contractSessions,
+            sessions: [...merged.values()],
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+    server.registerTool('xmpp_estimate_workflow', {
+        description: 'Estimate multi-step workflow cost, selected routes, and savings against naive x402.',
+        inputSchema: {
+            steps: z.array(z.object({
+                url: z.url(),
+                method: z.string().default('GET').optional(),
+                serviceId: z.string().optional(),
+                projectedRequests: z.number().int().positive(),
+                streaming: z.boolean().optional(),
+            })),
+        },
+    }, async ({ steps }) => {
+        const estimate = router.estimateWorkflow(steps);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(estimate, null, 2) }],
+            structuredContent: estimate,
+        };
+    });
+    return server;
+}
+export async function runXmppMcpServer(options) {
+    const server = createXmppMcpServer(options);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    return server;
+}

package/dist/packages/config/src/index.d.ts

@@ -0,0 +1,49 @@
+export declare const config: {
+    readonly nodeEnv: string;
+    readonly network: string;
+    readonly paymentExecutionMode: "mock" | "testnet";
+    readonly rpcUrl: string;
+    readonly networkPassphrase: string;
+    readonly gatewayPort: number;
+    readonly dashboardPort: number;
+    readonly dashboardGatewayUrl: string | undefined;
+    readonly dailyBudgetUsd: number;
+    readonly facilitatorUrl: string;
+    readonly wallet: {
+        readonly agentSecretKey: string | undefined;
+        readonly smartAccountContractId: string | undefined;
+        readonly smartAccountWasmHash: string;
+        readonly webauthnVerifierAddress: string;
+        readonly ed25519VerifierAddress: string;
+        readonly spendingLimitPolicyAddress: string;
+        readonly thresholdPolicyAddress: string;
+    };
+    readonly x402: {
+        readonly facilitatorUrl: string;
+        readonly facilitatorApiKey: string | undefined;
+        readonly maxTransactionFeeStroops: number;
+        readonly facilitatorPrivateKey: string | undefined;
+        readonly recipientAddress: string | undefined;
+    };
+    readonly mpp: {
+        readonly secretKey: string | undefined;
+        readonly recipientAddress: string | undefined;
+        readonly channelContractId: string | undefined;
+        readonly feeSponsorshipEnabled: boolean;
+        readonly feeSponsorship: {
+            readonly chargeEnabled: boolean;
+            readonly sessionEnabled: boolean;
+        };
+        readonly feeSponsorSecretKey: string | undefined;
+        readonly feeBumpSecretKey: string | undefined;
+    };
+    readonly services: {
+        readonly research: string;
+        readonly market: string;
+        readonly stream: string;
+    };
+    readonly contracts: {
+        readonly policyContractId: string | undefined;
+        readonly sessionRegistryContractId: string | undefined;
+    };
+};

package/dist/packages/config/src/index.js

@@ -0,0 +1,117 @@
+import { config as loadEnv } from 'dotenv';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(moduleDir, '../../../');
+loadEnv({ path: resolve(repoRoot, '.env') });
+loadEnv({ path: resolve(repoRoot, '.env.local'), override: true });
+loadEnv();
+const envSchema = z.object({
+    NODE_ENV: z.string().default('development'),
+    XMPP_NETWORK: z.string().default('stellar:testnet'),
+    XMPP_PAYMENT_EXECUTION_MODE: z.enum(['mock', 'testnet']).default('mock'),
+    XMPP_RPC_URL: z.string().default('https://soroban-testnet.stellar.org'),
+    XMPP_NETWORK_PASSPHRASE: z.string().default('Test SDF Network ; September 2015'),
+    XMPP_GATEWAY_PORT: z.coerce.number().default(4300),
+    XMPP_DASHBOARD_PORT: z.coerce.number().default(4310),
+    XMPP_DASHBOARD_GATEWAY_URL: z.string().optional(),
+    XMPP_DAILY_BUDGET_USD: z.coerce.number().default(0.5),
+    XMPP_AGENT_SECRET_KEY: z.string().optional(),
+    XMPP_SMART_ACCOUNT_CONTRACT_ID: z.string().optional(),
+    XMPP_SMART_ACCOUNT_WASM_HASH: z
+        .string()
+        .default('3e51f5b222dec74650f0b33367acb42a41ce497f72639230463070e666abba2c'),
+    XMPP_WEBAUTHN_VERIFIER_ADDRESS: z
+        .string()
+        .default('CATPTBRWVMH5ZCIKO5HN2F4FMPXVZEXC56RKGHRXCM7EEZGGXK7PICEH'),
+    XMPP_ED25519_VERIFIER_ADDRESS: z
+        .string()
+        .default('CAIKK32K3BZJYTWVTXHZFPIEEDBR6YCVTGPABH4UQUQ4XFA3OLYXG27G'),
+    XMPP_SPENDING_LIMIT_POLICY_ADDRESS: z
+        .string()
+        .default('CBYLPYZGLQ6JVY2IQ5P23QLQPR3KAMMKMZLNWG6RUUKJDNYGPLVHK7U4'),
+    XMPP_THRESHOLD_POLICY_ADDRESS: z
+        .string()
+        .default('CDDQLFG7CV74QHWPSP6NZIPNBR2PPCMTUVYCJF4P3ONDYHODRFGR7LWC'),
+    X402_FACILITATOR_URL: z.string().default('http://localhost:4022'),
+    X402_FACILITATOR_API_KEY: z.string().optional(),
+    X402_MAX_TRANSACTION_FEE_STROOPS: z.coerce.number().default(2000000),
+    X402_RECIPIENT_ADDRESS: z.string().optional(),
+    FACILITATOR_STELLAR_PRIVATE_KEY: z.string().optional(),
+    MPP_SECRET_KEY: z.string().optional(),
+    MPP_RECIPIENT_ADDRESS: z.string().optional(),
+    MPP_CHANNEL_CONTRACT_ID: z.string().optional(),
+    XMPP_ENABLE_MPP_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .default('false')
+        .transform((value) => value === 'true'),
+    XMPP_ENABLE_MPP_CHARGE_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value === 'true'),
+    XMPP_ENABLE_MPP_SESSION_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value === 'true'),
+    XMPP_MPP_FEE_SPONSOR_SECRET_KEY: z.string().optional(),
+    XMPP_MPP_FEE_BUMP_SECRET_KEY: z.string().optional(),
+    XMPP_RESEARCH_API_URL: z.string().default('http://localhost:4101'),
+    XMPP_MARKET_API_URL: z.string().default('http://localhost:4102'),
+    XMPP_STREAM_API_URL: z.string().default('http://localhost:4103'),
+    XMPP_POLICY_CONTRACT_ID: z.string().optional(),
+    XMPP_SESSION_REGISTRY_CONTRACT_ID: z.string().optional(),
+});
+const env = envSchema.parse(process.env);
+const mppFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_FEE_SPONSORSHIP;
+const mppChargeFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_CHARGE_FEE_SPONSORSHIP ?? mppFeeSponsorshipEnabled;
+const mppSessionFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_SESSION_FEE_SPONSORSHIP ?? mppFeeSponsorshipEnabled;
+export const config = {
+    nodeEnv: env.NODE_ENV,
+    network: env.XMPP_NETWORK,
+    paymentExecutionMode: env.XMPP_PAYMENT_EXECUTION_MODE,
+    rpcUrl: env.XMPP_RPC_URL,
+    networkPassphrase: env.XMPP_NETWORK_PASSPHRASE,
+    gatewayPort: env.XMPP_GATEWAY_PORT,
+    dashboardPort: env.XMPP_DASHBOARD_PORT,
+    dashboardGatewayUrl: env.XMPP_DASHBOARD_GATEWAY_URL,
+    dailyBudgetUsd: env.XMPP_DAILY_BUDGET_USD,
+    facilitatorUrl: env.X402_FACILITATOR_URL,
+    wallet: {
+        agentSecretKey: env.XMPP_AGENT_SECRET_KEY,
+        smartAccountContractId: env.XMPP_SMART_ACCOUNT_CONTRACT_ID,
+        smartAccountWasmHash: env.XMPP_SMART_ACCOUNT_WASM_HASH,
+        webauthnVerifierAddress: env.XMPP_WEBAUTHN_VERIFIER_ADDRESS,
+        ed25519VerifierAddress: env.XMPP_ED25519_VERIFIER_ADDRESS,
+        spendingLimitPolicyAddress: env.XMPP_SPENDING_LIMIT_POLICY_ADDRESS,
+        thresholdPolicyAddress: env.XMPP_THRESHOLD_POLICY_ADDRESS,
+    },
+    x402: {
+        facilitatorUrl: env.X402_FACILITATOR_URL,
+        facilitatorApiKey: env.X402_FACILITATOR_API_KEY,
+        maxTransactionFeeStroops: env.X402_MAX_TRANSACTION_FEE_STROOPS,
+        facilitatorPrivateKey: env.FACILITATOR_STELLAR_PRIVATE_KEY,
+        recipientAddress: env.X402_RECIPIENT_ADDRESS,
+    },
+    mpp: {
+        secretKey: env.MPP_SECRET_KEY,
+        recipientAddress: env.MPP_RECIPIENT_ADDRESS,
+        channelContractId: env.MPP_CHANNEL_CONTRACT_ID,
+        feeSponsorshipEnabled: mppFeeSponsorshipEnabled,
+        feeSponsorship: {
+            chargeEnabled: mppChargeFeeSponsorshipEnabled,
+            sessionEnabled: mppSessionFeeSponsorshipEnabled,
+        },
+        feeSponsorSecretKey: env.XMPP_MPP_FEE_SPONSOR_SECRET_KEY,
+        feeBumpSecretKey: env.XMPP_MPP_FEE_BUMP_SECRET_KEY,
+    },
+    services: {
+        research: env.XMPP_RESEARCH_API_URL,
+        market: env.XMPP_MARKET_API_URL,
+        stream: env.XMPP_STREAM_API_URL,
+    },
+    contracts: {
+        policyContractId: env.XMPP_POLICY_CONTRACT_ID,
+        sessionRegistryContractId: env.XMPP_SESSION_REGISTRY_CONTRACT_ID,
+    },
+};

package/dist/packages/contract-runtime/src/index.d.ts

@@ -0,0 +1,44 @@
+import type { RouteKind, XmppAgentPolicySnapshot, XmppContractAgentTreasuryState, XmppContractTreasurySnapshot, XmppSessionRecord } from '@xmpp/types';
+export type PolicyRuntimeSnapshot = {
+    source: 'local' | 'contract' | 'fallback';
+    pauseFlag: boolean;
+    globalPolicy: {
+        maxSpendUsdCents: number;
+        allowUnknownServices: boolean;
+        allowPostAutopay: boolean;
+    } | null;
+    servicePolicy: {
+        serviceId: string;
+        enabled: boolean;
+        maxSpendUsdCents: number;
+        preferredRoute: string;
+        allowSessionReuse: boolean;
+    } | null;
+};
+export type AgentPolicyRuntimeSnapshot = {
+    source: 'local' | 'contract' | 'fallback';
+    agentPolicy: XmppAgentPolicySnapshot | null;
+};
+export type SessionRouteEventInput = {
+    sessionId: string;
+    serviceId: string;
+    route: RouteKind;
+    status: 'open' | 'reused' | 'closed';
+    callCount: number;
+    receiptId: string;
+    totalAmountUsdCents?: number;
+};
+export declare function getAgentPolicySnapshot(agentId: string): Promise<AgentPolicyRuntimeSnapshot>;
+export declare function listAgentPolicySnapshots(): Promise<XmppAgentPolicySnapshot[]>;
+export declare function getTreasurySnapshot(): Promise<XmppContractTreasurySnapshot | null>;
+export declare function getAgentTreasuryState(agentId: string): Promise<XmppContractAgentTreasuryState | null>;
+export declare function listAgentTreasuryStates(): Promise<XmppContractAgentTreasuryState[]>;
+export declare function getPolicyRuntimeSnapshot(serviceId?: string): Promise<PolicyRuntimeSnapshot>;
+export declare function recordTreasurySpend(input: {
+    agentId: string;
+    serviceId: string;
+    route: RouteKind;
+    amountUsdCents: number;
+}): Promise<XmppContractAgentTreasuryState | null>;
+export declare function recordSessionRouteEvent(input: SessionRouteEventInput): Promise<XmppSessionRecord | null>;
+export declare function listAgentSessions(): Promise<XmppSessionRecord[]>;