@zktx.io/sui-mcp 0.5.0

package/dist/mcp/toolNames.js

@@ -0,0 +1,58 @@
+export const TOOL_NAMES = {
+    uiOpenAccount: "ui.open_account",
+    uiOpenReceipt: "ui.open_receipt",
+    uiOpenChart: "ui.open_chart",
+    uiReadCard: "ui.read_card",
+    uiSubmitCard: "ui.submit_card",
+    uiActCard: "ui.act_card",
+    sessionOpenReviewManagement: "session.open_review_management",
+    readGetServerStatus: "read.get_server_status",
+    readListSupportedProtocols: "read.list_supported_protocols",
+    readListDeepbookPools: "read.list_deepbook_pools",
+    readListDeepbookTokens: "read.list_deepbook_tokens",
+    readInspectDeepbookOrderbook: "read.inspect_deepbook_orderbook",
+    readGetDeepbookMidPrice: "read.get_deepbook_mid_price",
+    readGetDeepbookUsdcPriceHistory: "read.get_deepbook_usdc_price_history",
+    readGetDeepbookUsdcPriceAtTime: "read.get_deepbook_usdc_price_at_time",
+    readQuoteDeepbookAction: "read.quote_deepbook_action",
+    readQuoteDeepbookDisplayAmount: "read.quote_deepbook_display_amount",
+    readSummarizeDeepbookAccountInventory: "read.summarize_deepbook_account_inventory",
+    readSummarizeWalletAssets: "read.summarize_wallet_assets",
+    readClassifyWalletAssets: "read.classify_wallet_assets",
+    readListSettlementAssetGroups: "read.list_settlement_asset_groups",
+    readSummarizeSettlementAssetGroupParity: "read.summarize_settlement_asset_group_parity",
+    readPreviewIntentEvidence: "read.preview_intent_evidence",
+    readListReviewActivity: "read.list_review_activity",
+    readSummarizeReviewFunnel: "read.summarize_review_funnel",
+    readGetReviewSessionDetail: "read.get_review_session_detail",
+    readInspectSuiTransaction: "read.inspect_sui_transaction",
+    readScanSuiAccountActivity: "read.scan_sui_account_activity",
+    readSummarizeSuiActivityScan: "read.summarize_sui_activity_scan",
+    readScanSuiFunctionActivity: "read.scan_sui_function_activity",
+    readSummarizeSuiFunctionActivityScan: "read.summarize_sui_function_activity_scan",
+    readSummarizeSuiAccountActivity: "read.summarize_sui_account_activity",
+    readGetAccountAssetTimeline: "read.get_account_asset_timeline",
+    settingsCreateLocalSettingsSession: "settings.create_local_settings_session",
+    settingsGetLocalSettings: "settings.get_local_settings",
+    actionPrepareSuiActionReview: "action.prepare_sui_action_review",
+    actionPrepareExternalProposalReview: "action.prepare_external_proposal_review",
+    sessionCreateWalletConnection: "session.create_wallet_connection",
+    sessionGetWalletConnection: "session.get_wallet_connection",
+    sessionWaitWalletConnection: "session.wait_wallet_connection",
+    sessionGetInteractionStatus: "session.get_interaction_status",
+    sessionGetReviewStatus: "session.get_review_status",
+    sessionGetExecutionResult: "session.get_execution_result",
+    sessionWaitExecutionResult: "session.wait_execution_result",
+    accountGetActiveAccount: "account.get_active_account",
+    accountClearActiveAccount: "account.clear_active_account"
+};
+export function assertValidToolName(name) {
+    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name)) {
+        throw new Error(`Invalid MCP tool name: ${name}`);
+    }
+}
+export function assertAllToolNamesValid() {
+    for (const name of Object.values(TOOL_NAMES)) {
+        assertValidToolName(name);
+    }
+}

package/dist/mcp/tools/account/index.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { activeAccountResponse, activeAccountResponseSchema } from "../../activeAccountResponse.js";
+import { registerSuiMcpTool } from "../../registerTool.js";
+import { okToolResult } from "../../result.js";
+import { noParamsInputSchema, successOutputSchema } from "../../schemas.js";
+import { activityStoreToolError } from "../../toolErrors.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+export function registerAccountTools(server, deps) {
+    server.registerTool(TOOL_NAMES.accountGetActiveAccount, {
+        title: "Get active account read context",
+        description: "Return the active account address for wallet-account reads. Read context only; not signing authorization.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: {
+            ok: z.literal(true),
+            data: activeAccountResponseSchema
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async () => {
+        try {
+            const active = await deps.activityStore.getActiveAccount();
+            return okToolResult(activeAccountResponse(active));
+        }
+        catch (error) {
+            return activityStoreToolError(error, deps.logger);
+        }
+    });
+    registerSuiMcpTool(server, TOOL_NAMES.accountClearActiveAccount, {
+        title: "Clear active account read context",
+        description: "Remove the active read context. Does not disconnect a wallet or revoke onchain permission.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema({
+            status: z.literal("cleared")
+        }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async () => {
+        try {
+            await deps.activityStore.clearActiveAccount();
+            return okToolResult({ status: "cleared" });
+        }
+        catch (error) {
+            return activityStoreToolError(error, deps.logger);
+        }
+    });
+}

package/dist/mcp/tools/action/prepareSuiActionReview.js

@@ -0,0 +1,126 @@
+import { cardMetadata, createWorkflowCard, supportsCards } from "../../../mcp-ui/tools.js";
+import { cardSnapshotSchema } from "../../../mcp-ui/contracts.js";
+import { z } from "zod";
+import { INTENT_PLAN_FACTORIES, resolveIntentPlanFactory, swapIntentInputSchema } from "../../../adapters/intentPlanFactories.js";
+import { actionPlanSchema, reviewCheckSchema } from "../../../core/action/schemas.js";
+import { externalProposalToActionPlan } from "../../../core/proposal/externalProposalReview.js";
+import { externalProposalSchema } from "../../../core/proposal/schemas.js";
+import { prepareActionReviewUserAnswerUse, prepareExternalProposalReviewUserAnswerUse } from "../../responseGuidance.js";
+import { registerSuiMcpTool } from "../../registerTool.js";
+import { successOutputSchema } from "../../schemas.js";
+import { errorToolResult } from "../../result.js";
+import { activityStoreToolError, sessionStoreToolError } from "../../toolErrors.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+import { userAnswerUseSchema } from "../read/commonSchemas.js";
+export function registerActionTools(server, deps) {
+    server.registerTool(TOOL_NAMES.actionPrepareSuiActionReview, {
+        title: "Prepare swap review",
+        description: "Create a local swap review session on a supported protocol. Returns an internal review card.",
+        inputSchema: {
+            intent: swapIntentInputSchema
+        },
+        outputSchema: successOutputSchema({
+            reviewSessionId: z.string(),
+            card: cardSnapshotSchema,
+            plans: z.array(actionPlanSchema),
+            preliminaryChecks: z.array(reviewCheckSchema),
+            userAnswerUse: userAnswerUseSchema
+        }),
+        _meta: cardMetadata("review"),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    }, async ({ intent }) => {
+        if (!supportsCards(server))
+            return errorToolResult({ kind: "ui_unavailable", details: { reason: "An internal review card is required." } });
+        const now = new Date();
+        // A swap review is account-bound: its evidence (balances, transaction
+        // material, digest, simulation) is computed for a specific sender, and
+        // no transaction can be built without that account. Refuse here when no
+        // wallet account is connected instead of creating a hollow proposal that
+        // can never be computed or signed. Connect first via
+        // session.create_wallet_connection.
+        let activeAccount;
+        try {
+            activeAccount = await deps.activityStore.getActiveAccount();
+        }
+        catch (error) {
+            return activityStoreToolError(error, deps.logger);
+        }
+        if (!activeAccount) {
+            return errorToolResult({
+                kind: "active_account_not_set",
+                details: { action: "connect_wallet_connection" }
+            });
+        }
+        const { protocol: protocolSlug, ...swapIntent } = intent;
+        const resolution = resolveIntentPlanFactory(INTENT_PLAN_FACTORIES, swapIntent.type, protocolSlug);
+        if (resolution.status !== "resolved") {
+            return errorToolResult({
+                kind: resolution.status === "unsupported_action" ? "unsupported_action" : "input_invalid",
+                details: resolution.status === "unsupported_action"
+                    ? { reason: "unsupported_action", actionKind: resolution.actionKind }
+                    : resolution.status === "unknown_protocol"
+                        ? {
+                            reason: "unknown_protocol",
+                            protocol: resolution.protocolSlug,
+                            availableProtocols: resolution.available
+                        }
+                        : {
+                            reason: "protocol_choice_required",
+                            availableProtocols: resolution.available,
+                            guidance: "Several protocols support this action; set intent.protocol to one of availableProtocols. Ask the user - do not pick a protocol silently."
+                        }
+            });
+        }
+        const plan = resolution.factory.createPlan(swapIntent, now);
+        try {
+            const { session } = await deps.sessions.createReviewSession([plan], now);
+            const preliminaryChecks = plan.preliminaryChecks ?? [];
+            const hasBlockingPreliminaryChecks = preliminaryChecks.some((check) => check.status === "fail");
+            const payload = {
+                reviewSessionId: session.id,
+                plans: session.plans,
+                preliminaryChecks,
+                userAnswerUse: prepareActionReviewUserAnswerUse({ hasBlockingPreliminaryChecks })
+            };
+            return await createWorkflowCard(server, deps, "review", { reviewSessionId: session.id }, payload);
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+    registerSuiMcpTool(server, TOOL_NAMES.actionPrepareExternalProposalReview, {
+        title: "Prepare external proposal review",
+        description: "Create a local non-signable review session from an untrusted external Sui proposal.",
+        inputSchema: {
+            proposal: externalProposalSchema
+        },
+        outputSchema: successOutputSchema({
+            reviewSessionId: z.string(),
+            card: cardSnapshotSchema,
+            plans: z.array(actionPlanSchema),
+            preliminaryChecks: z.array(reviewCheckSchema),
+            userAnswerUse: userAnswerUseSchema
+        }),
+        _meta: cardMetadata("review"),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    }, async ({ proposal }) => {
+        if (!supportsCards(server))
+            return errorToolResult({ kind: "ui_unavailable", details: { reason: "An internal review card is required." } });
+        const now = new Date();
+        const plan = externalProposalToActionPlan(proposal, now);
+        try {
+            const { session } = await deps.sessions.createReviewSession([plan], now);
+            const preliminaryChecks = plan.preliminaryChecks ?? [];
+            const payload = {
+                reviewSessionId: session.id,
+                plans: session.plans,
+                preliminaryChecks,
+                userAnswerUse: prepareExternalProposalReviewUserAnswerUse()
+            };
+            return await createWorkflowCard(server, deps, "review", { reviewSessionId: session.id }, payload);
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+}

package/dist/mcp/tools/read/commonSchemas.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { DEEPBOOK_MID_PRICE_PRECISION } from "../../../core/read/readService.js";
+export const fetchedAtSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+export const readSourceSchema = z.object({
+    sdk: z.string(),
+    transport: z.literal("grpc"),
+    simulation: z.literal("client.core.simulateTransaction").optional(),
+    method: z.string().optional(),
+    methods: z.array(z.string()).optional(),
+    returnValueEncoding: z.string().optional(),
+    precision: z.literal(DEEPBOOK_MID_PRICE_PRECISION).optional()
+});
+export const reviewActivityAccountSourceSchema = z.enum(["active_account_context", "explicit_filter"]);
+export const reviewActivityDataScopeSchema = z.object({
+    account: z.string(),
+    from: fetchedAtSchema.optional(),
+    to: fetchedAtSchema.optional(),
+    recordCount: z.number().int().nonnegative()
+});
+export const reviewActivityInputSchema = {
+    account: z.string().min(1).optional(),
+    from: fetchedAtSchema.optional(),
+    to: fetchedAtSchema.optional()
+};
+export const userAnswerUseSchema = z.object({
+    canAnswer: z.array(z.string()),
+    cannotAnswer: z.array(z.string()),
+    answerFields: z.array(z.string()),
+    preconditionFields: z.array(z.string()).optional(),
+    conclusionRuleFields: z.array(z.string()).optional(),
+    diagnosticOnlyFields: z.array(z.string()).optional(),
+    followUp: z
+        .object({
+        tool: z.string(),
+        inputFields: z.array(z.string()).optional(),
+        answerFields: z.array(z.string()),
+        reason: z.string()
+    })
+        .optional()
+}).strict();