@zktx.io/sui-mcp 0.5.0

package/dist/mcp/tools/session/executionResultTools.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { waitForExecutionResult, WAIT_OUTCOMES } from "../../../core/session/wait.js";
+import { reviewStatusResponse } from "../../../core/session/status.js";
+import { errorToolResult, okToolResult } from "../../result.js";
+import { successOutputSchema } from "../../schemas.js";
+import { sessionStoreToolError } from "../../toolErrors.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+import { executionResultUserAnswerUse } from "../../responseGuidance.js";
+import { userAnswerUseSchema } from "../read/commonSchemas.js";
+import { reviewStatusResponseShape, waitExecutionInputSchema, readCurrentReview } from "./shared.js";
+export function registerExecutionResultTools(server, deps) {
+    server.registerTool(TOOL_NAMES.sessionGetExecutionResult, {
+        title: "Get transaction request result", description: "Read one review session's transaction request and any observed chain result.",
+        inputSchema: { reviewSessionId: z.string().min(1) },
+        outputSchema: successOutputSchema({ ...reviewStatusResponseShape, userAnswerUse: userAnswerUseSchema }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async ({ reviewSessionId }) => {
+        try {
+            const state = await readCurrentReview(deps, reviewSessionId, true);
+            if (!state)
+                return errorToolResult({ kind: "session_not_found", details: { reviewSessionId } });
+            const request = state.request;
+            return okToolResult({ ...reviewStatusResponse(state), userAnswerUse: executionResultUserAnswerUse({ hasConnectionConflict: !!state.connectionConflict, hasRequest: !!request, hasExecutionResult: !!request?.execution }) });
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+    server.registerTool(TOOL_NAMES.sessionWaitExecutionResult, {
+        title: "Wait for transaction request result", description: "Wait briefly for one admitted request or required user action.",
+        inputSchema: waitExecutionInputSchema(),
+        outputSchema: successOutputSchema({ waitOutcome: z.enum(WAIT_OUTCOMES), ...reviewStatusResponseShape, userAnswerUse: userAnswerUseSchema }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async ({ reviewSessionId, timeoutMs }, extra) => {
+        try {
+            const result = await waitForExecutionResult((id) => readCurrentReview(deps, id), reviewSessionId, { timeoutMs, signal: extra.signal });
+            return okToolResult({ waitOutcome: result.waitOutcome, ...reviewStatusResponse(result),
+                userAnswerUse: executionResultUserAnswerUse({ hasConnectionConflict: !!result.connectionConflict, hasRequest: !!result.request, hasExecutionResult: !!result.request?.execution, hasWaitOutcome: true }) });
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+}

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

@@ -0,0 +1,8 @@
+import { registerExecutionResultTools } from "./executionResultTools.js";
+import { registerSessionStatusTools } from "./statusTools.js";
+import { registerWalletConnectionTools } from "./walletConnectionTools.js";
+export function registerSessionTools(server, deps) {
+    registerWalletConnectionTools(server, deps);
+    registerSessionStatusTools(server, deps);
+    registerExecutionResultTools(server, deps);
+}

package/dist/mcp/tools/session/shared.js

@@ -0,0 +1,36 @@
+import { walletObservationSchema } from "../../../core/session/walletRuntime.js";
+import { walletAvailabilitySchema, workflowProgressSchema, walletUnavailable, connectionConflictSchema } from "../../../core/session/walletConnection.js";
+import { z } from "zod";
+import { actionPlanSchema, executionPollingStatusSchema, internalSessionStatusSchema, reviewStateOutputSchema } from "../../../core/action/schemas.js";
+import { EXECUTION_STATUS_CATEGORIES } from "../../../core/session/status.js";
+import { transactionExecutionSummarySchema, transactionRequestSchema, transactionRequestStatusSchema } from "../../../core/session/transactionRequest.js";
+import { DEFAULT_WAIT_TIMEOUT_MS, MAX_WAIT_TIMEOUT_MS } from "../../../core/session/wait.js";
+export const INTERACTION_STATUS_LIMIT = 5;
+export function executionPollingHintSchema() {
+    return z.object({ nonTerminalStatuses: z.array(executionPollingStatusSchema), waitStoppingStatuses: z.array(executionPollingStatusSchema),
+        finalStatuses: z.array(executionPollingStatusSchema), userActionRequiredStatuses: z.array(executionPollingStatusSchema),
+        recommendedIntervalSeconds: z.number().int().positive() });
+}
+export function executionStatusCategorySchema() { return z.enum(EXECUTION_STATUS_CATEGORIES); }
+export const timeoutInputSchema = z.number().int().min(1).max(MAX_WAIT_TIMEOUT_MS).default(DEFAULT_WAIT_TIMEOUT_MS).optional();
+export function waitExecutionInputSchema() { return { reviewSessionId: z.string().min(1), timeoutMs: timeoutInputSchema }; }
+export const reviewStatusResponseShape = {
+    connectionConflict: connectionConflictSchema.optional(), walletAvailability: walletAvailabilitySchema, walletObservation: walletObservationSchema.optional(), progress: workflowProgressSchema,
+    reviewSessionId: z.string(), status: internalSessionStatusSchema, reviewRevision: z.number().int().nonnegative(),
+    account: z.string().optional(), plans: z.array(actionPlanSchema), reviewState: reviewStateOutputSchema.optional(),
+    pollingStatus: executionPollingStatusSchema, statusCategory: executionStatusCategorySchema(), pollingHint: executionPollingHintSchema(),
+    expiresAt: z.string(), lastActivityAt: z.string(), attemptId: z.string().optional(), requestStatus: transactionRequestStatusSchema.optional(),
+    request: transactionRequestSchema.optional(), executionResult: transactionExecutionSummarySchema.optional()
+};
+export function latest(items) {
+    const sorted = [...items].sort((left, right) => right.lastActivityAt.localeCompare(left.lastActivityAt));
+    return { limit: INTERACTION_STATUS_LIMIT, items: sorted.slice(0, INTERACTION_STATUS_LIMIT), truncated: sorted.length > INTERACTION_STATUS_LIMIT };
+}
+// Runtime workflows own reconciliation/observation. A server without a wallet
+// workflow can still expose ordinary preparation facts, with explicit absence.
+export async function readCurrentReview(deps, id, explicitResult = false) {
+    if (deps.workflow)
+        return deps.workflow.readReview(id, explicitResult);
+    const session = await deps.sessions.getReviewSession(id);
+    return session ? { session, hasReviewInput: false, walletAvailability: walletUnavailable("initialization_failed"), progress: { status: "idle" } } : undefined;
+}

package/dist/mcp/tools/session/statusTools.js

@@ -0,0 +1,69 @@
+import { walletAvailabilitySchema, workflowProgressSchema, walletUnavailable, connectionConflictSchema } from "../../../core/session/walletConnection.js";
+import { walletObservationSchema } from "../../../core/session/walletRuntime.js";
+import { z } from "zod";
+import { activeAccountResponse, activeAccountResponseSchema } from "../../activeAccountResponse.js";
+import { errorToolResult, okToolResult } from "../../result.js";
+import { noParamsInputSchema, successOutputSchema } from "../../schemas.js";
+import { activityStoreToolError, sessionStoreToolError } from "../../toolErrors.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+import { interactionStatusUserAnswerUse, reviewStatusUserAnswerUse } from "../../responseGuidance.js";
+import { userAnswerUseSchema } from "../read/commonSchemas.js";
+import { isReviewInteractionPending, reviewStatusResponse } from "../../../core/session/status.js";
+import { latest, reviewStatusResponseShape, readCurrentReview } from "./shared.js";
+import { pendingConnectionStatusSchema, connectionViewSchema, assetReadAccountSchema } from "../../../core/session/workflowView.js";
+export function registerSessionStatusTools(server, deps) {
+    server.registerTool(TOOL_NAMES.sessionGetInteractionStatus, {
+        title: "Get local interaction status", description: "Read wallet connections, the default asset account, and pending interactions.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema({ walletAvailability: walletAvailabilitySchema, walletObservation: walletObservationSchema.optional(), activeAccount: activeAccountResponseSchema,
+            connections: z.array(connectionViewSchema), assetReadAccount: assetReadAccountSchema,
+            connectionConflict: connectionConflictSchema.optional(),
+            pendingWalletConnections: z.object({ limit: z.number().int().positive(), truncated: z.boolean(),
+                items: z.array(z.object({ cardId: z.string(), connectionId: z.string().optional(),
+                    status: pendingConnectionStatusSchema, progress: workflowProgressSchema, lastActivityAt: z.string() })) }),
+            pendingReviewSessions: z.object({ limit: z.number().int().positive(), truncated: z.boolean(), items: z.array(z.object(reviewStatusResponseShape)) }),
+            userAnswerUse: userAnswerUseSchema }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async () => {
+        let active;
+        try {
+            active = await deps.activityStore.getActiveAccount();
+        }
+        catch (error) {
+            return activityStoreToolError(error, deps.logger);
+        }
+        try {
+            // Connection reconciliation can invalidate reviews and interrupt requests.
+            // Complete that maintenance before projecting its dependent review facts.
+            const context = deps.workflow?.readConnectionContext() ?? { connections: [],
+                assetReadAccount: { status: "address_required" }, walletAvailability: walletUnavailable("initialization_failed") };
+            const connections = deps.workflow?.pendingConnections() ?? [];
+            const states = await Promise.all(deps.sessions.reviewSessionIds().map((id) => readCurrentReview(deps, id)));
+            const reviews = states.flatMap((state) => state && isReviewInteractionPending(state) ? [reviewStatusResponse(state)] : []);
+            return okToolResult({ activeAccount: activeAccountResponse(active), pendingWalletConnections: latest(connections),
+                pendingReviewSessions: latest(reviews), ...context,
+                userAnswerUse: interactionStatusUserAnswerUse("walletObservation" in context && context.walletObservation !== undefined, "connectionConflict" in context && !!context.connectionConflict) });
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+    server.registerTool(TOOL_NAMES.sessionGetReviewStatus, {
+        title: "Get review status", description: "Read one review session, its admitted request and any observed chain result.",
+        inputSchema: { reviewSessionId: z.string().min(1) },
+        outputSchema: successOutputSchema({ ...reviewStatusResponseShape, userAnswerUse: userAnswerUseSchema }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async ({ reviewSessionId }) => {
+        try {
+            const state = await readCurrentReview(deps, reviewSessionId);
+            if (!state)
+                return errorToolResult({ kind: "session_not_found", details: { reviewSessionId } });
+            const session = state.session;
+            return okToolResult({ ...reviewStatusResponse(state),
+                userAnswerUse: reviewStatusUserAnswerUse(!!session.reviewState, !!session.reviewState?.adapterLifecycle, !!session.reviewState?.humanReadableReview, !!session.reviewState?.simulation, !!state.connectionConflict) });
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+}

package/dist/mcp/tools/session/walletConnectionTools.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { cardMetadata, createWorkflowCard } from "../../../mcp-ui/tools.js";
+import { cardSnapshotSchema } from "../../../mcp-ui/contracts.js";
+import { waitForWalletConnection, WAIT_OUTCOMES } from "../../../core/session/wait.js";
+import { okToolResult } from "../../result.js";
+import { successOutputSchema } from "../../schemas.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+import { timeoutInputSchema } from "./shared.js";
+import { CardError } from "../../../core/session/cardSessionStore.js";
+import { sessionStoreToolError } from "../../toolErrors.js";
+export function registerWalletConnectionTools(server, deps) {
+    const failure = (error) => sessionStoreToolError(error, deps.logger);
+    server.registerTool(TOOL_NAMES.sessionCreateWalletConnection, {
+        title: "Open wallet connection controls", description: "Open a card for Sui wallet connection, disconnection and account selection.",
+        inputSchema: { intent: z.enum(["manage", "connect", "disconnect"]).default("manage") }, outputSchema: successOutputSchema(cardSnapshotSchema.shape),
+        _meta: cardMetadata("connect"), annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async ({ intent }) => { try {
+        return await createWorkflowCard(server, deps, "connect", { intent });
+    }
+    catch (error) {
+        return failure(error);
+    } });
+    server.registerTool(TOOL_NAMES.sessionGetWalletConnection, {
+        title: "Get wallet connection", description: "Read the saved state of one wallet connection card.",
+        inputSchema: { cardId: z.string().min(1) }, outputSchema: successOutputSchema(cardSnapshotSchema.shape),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async ({ cardId }) => {
+        try {
+            if (!deps.cards)
+                return failure(new CardError("Wallet card is unavailable."));
+            const snapshot = await deps.cards.store.readSaved(cardId);
+            if (snapshot.kind !== "connect")
+                return failure(new CardError("Wallet card is unavailable."));
+            return okToolResult(snapshot);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool(TOOL_NAMES.sessionWaitWalletConnection, {
+        title: "Wait for wallet connection", description: "Wait briefly for a wallet connection card's approval or required user input.",
+        inputSchema: { cardId: z.string().min(1), timeoutMs: timeoutInputSchema },
+        outputSchema: successOutputSchema({ waitOutcome: z.enum(WAIT_OUTCOMES), card: cardSnapshotSchema }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async ({ cardId, timeoutMs }, extra) => {
+        try {
+            if (!deps.cards)
+                return failure(new CardError("Wallet card is unavailable."));
+            const result = await waitForWalletConnection(deps.cards.store, cardId, { timeoutMs, signal: extra.signal });
+            return okToolResult({ waitOutcome: result.waitOutcome, card: result.snapshot });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool(TOOL_NAMES.sessionOpenReviewManagement, {
+        title: "Open transaction request management", description: "Open management for one existing review session and transaction attempt.",
+        inputSchema: { reviewSessionId: z.string().min(1), attemptId: z.string().min(1) },
+        outputSchema: successOutputSchema(cardSnapshotSchema.shape), _meta: cardMetadata("review"),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async (input) => {
+        try {
+            return await createWorkflowCard(server, deps, "review", { ...input, mode: "manage" });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+}

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

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { SETTINGS_APPLIES_AFTER_RESTART } from "../../../core/preferences/preferencesStore.js";
+import { registerSuiMcpTool } from "../../registerTool.js";
+import { errorToolResult, okToolResult } from "../../result.js";
+import { noParamsInputSchema, successOutputSchema } from "../../schemas.js";
+import { localSettingsToolError, sessionStoreToolError } from "../../toolErrors.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+const endpointSettingSchema = z.object({
+    storedValue: z.string(),
+    effectiveValue: z.string(),
+    source: z.enum(["environment", "local_db", "builtin_default"]),
+    pendingStoredValue: z.string().optional(),
+    appliesAfter: z.literal(SETTINGS_APPLIES_AFTER_RESTART).optional()
+});
+export function registerSettingsTools(server, deps) {
+    server.registerTool(TOOL_NAMES.settingsCreateLocalSettingsSession, {
+        title: "Create local settings session",
+        description: "Create a local settings page session.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema({
+            settingsSessionId: z.string(),
+            settingsUrl: z.string(),
+            status: z.literal("created"),
+            openTarget: z.literal("system_browser"),
+            accessScope: z.literal("same_machine_loopback"),
+            expiresAt: z.string(),
+            lastActivityAt: z.string()
+        }),
+        annotations: { readOnlyHint: false, openWorldHint: false }
+    }, async () => {
+        try {
+            if (!deps.reviewBaseUrl)
+                return errorToolResult({ kind: "ui_unavailable", details: { reason: "Settings UI is unavailable in this runtime." } });
+            const created = await deps.sessions.createSettingsSession();
+            return okToolResult({
+                settingsSessionId: created.session.id,
+                settingsUrl: `${deps.reviewBaseUrl}/settings/${created.session.id}#${created.token}`,
+                status: "created",
+                openTarget: "system_browser",
+                accessScope: "same_machine_loopback",
+                expiresAt: created.session.expiresAt,
+                lastActivityAt: created.session.lastActivityAt
+            });
+        }
+        catch (error) {
+            return sessionStoreToolError(error, deps.logger);
+        }
+    });
+    registerSuiMcpTool(server, TOOL_NAMES.settingsGetLocalSettings, {
+        title: "Get local settings",
+        description: "Read local Sui MCP settings.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema({
+            suiGrpcUrl: endpointSettingSchema,
+            suiGraphqlUrl: endpointSettingSchema
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async () => {
+        try {
+            return okToolResult(await deps.localSettings.getLocalSettings());
+        }
+        catch (error) {
+            return localSettingsToolError(error, deps.logger);
+        }
+    });
+}