@zktx.io/sui-mcp 0.5.0

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

@@ -0,0 +1,14 @@
+import { registerDeepbookReadTools } from "./deepbookReadTools.js";
+import { registerReviewActivityListTool, registerReviewActivitySummaryTools } from "./reviewActivityTools.js";
+import { registerServerStatusTools, SUPPORTED_PROTOCOLS } from "./serverStatusTools.js";
+import { registerTransactionActivityTools } from "./transactionActivityTools.js";
+import { registerWalletReadTools } from "./walletReadTools.js";
+export { SUPPORTED_PROTOCOLS };
+export function registerReadTools(server, deps) {
+    registerServerStatusTools(server);
+    registerDeepbookReadTools(server, deps);
+    registerWalletReadTools(server, deps);
+    registerReviewActivityListTool(server, deps);
+    registerTransactionActivityTools(server, deps);
+    registerReviewActivitySummaryTools(server, deps);
+}

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

@@ -0,0 +1,97 @@
+import { CONNECTION_CONFLICT_MESSAGE } from "../../../core/session/walletConnection.js";
+import { ReadServiceCacheError, ReadServiceInputError } from "../../../core/read/readService.js";
+import { parseSuiAddress } from "../../../core/suiAddress.js";
+import { errorToolResult } from "../../result.js";
+import { activityStoreToolError } from "../../toolErrors.js";
+import { walletUnavailable } from "../../../core/session/walletConnection.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+export async function resolveExplicitOrActiveAccount(input, deps) {
+    if (input.mode === "explicit_or_connected" && input.account !== undefined) {
+        const explicitAccount = parseSuiAddress(input.account);
+        if (explicitAccount === undefined) {
+            return {
+                status: "error",
+                result: errorToolResult({
+                    kind: "input_invalid",
+                    details: {
+                        field: "account"
+                    }
+                })
+            };
+        }
+        return { status: "ok", account: explicitAccount };
+    }
+    let active;
+    try {
+        active = await deps.activityStore.getActiveAccount();
+    }
+    catch (error) {
+        return { status: "error", result: activityStoreToolError(error, deps.logger) };
+    }
+    if (!active && input.mode === "explicit_or_connected") {
+        const message = "Please provide a Sui address in chat.";
+        return {
+            status: "address_required", message,
+            result: errorToolResult({
+                kind: "active_account_not_set",
+                details: {
+                    action: "provide_account", message
+                }
+            })
+        };
+    }
+    try {
+        const context = deps.workflow?.readConnectionContext();
+        if (context?.assetReadAccount.status === "available")
+            return { status: "ok", account: context.assetReadAccount.account };
+        const availability = context?.walletAvailability ?? walletUnavailable("initialization_failed");
+        if (input.mode === "connected_only") {
+            if (availability.status !== "available")
+                return { status: "error", result: errorToolResult({ kind: "wallet_unavailable",
+                        details: { ...(availability.status === "unavailable" ? { reason: availability.reason } : {}), message: availability.message, walletAvailability: availability } }) };
+            return { status: "error", result: errorToolResult({ kind: active ? "input_invalid" : "active_account_not_set",
+                    details: { reason: "connected_account_required",
+                        message: context?.connectionConflict ? CONNECTION_CONFLICT_MESSAGE : "This tool requires a selected account with a usable wallet connection. An address alone cannot be used.",
+                        ...(context?.connectionConflict ? { connectionConflict: context.connectionConflict } : {}),
+                        followUp: { tool: TOOL_NAMES.sessionGetInteractionStatus,
+                            answerFields: ["walletAvailability", "connections", "pendingWalletConnections", "assetReadAccount"],
+                            reason: `Check current connections and pending operations. Use pendingWalletConnections.items[].cardId with ${TOOL_NAMES.sessionGetWalletConnection} or ${TOOL_NAMES.sessionWaitWalletConnection}. If no operation is pending and the user requests connection or account selection, open ${TOOL_NAMES.sessionCreateWalletConnection}. Only the user may act in that card.` } } }) };
+        }
+        const message = context?.connectionConflict ? CONNECTION_CONFLICT_MESSAGE + " Provide a Sui address in chat for this public read." : availability.status !== "available"
+            ? "The wallet connection cannot be checked. Please provide a Sui address in chat to view its assets."
+            : "No connected wallet is available for the selected account. Please provide a Sui address in chat.";
+        return { status: "address_required", message, result: errorToolResult({ kind: "input_invalid",
+                details: { field: "account", reason: "address_required", message, walletAvailability: availability } }) };
+    }
+    catch (error) {
+        return { status: "error", result: activityStoreToolError(error, deps.logger) };
+    }
+}
+export function readServiceError(error, deps) {
+    if (error instanceof ReadServiceCacheError) {
+        deps.logger.error("read service metadata cache failed", {
+            operation: error.details.operation,
+            error: error.cause instanceof Error ? error.cause.message : String(error.cause)
+        });
+        return errorToolResult({
+            kind: error.kind,
+            details: error.details
+        });
+    }
+    if (error instanceof ReadServiceInputError) {
+        return errorToolResult({
+            kind: error.kind,
+            details: error.details
+        });
+    }
+    deps.logger.error("read service call failed", {
+        error: error instanceof Error ? error.message : String(error)
+    });
+    return errorToolResult({
+        kind: "internal_error",
+        details: { message: "Read service call failed" }
+    });
+}
+export function activityStoreReadError(error, deps) {
+    return activityStoreToolError(error, deps.logger);
+}

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

@@ -0,0 +1,179 @@
+import { TRANSACTION_REQUEST_STATUSES, transactionRequestSchema, transactionRequestStatusSchema } from "../../../core/session/transactionRequest.js";
+import { z } from "zod";
+import { actionPlanSchema, internalSessionStatusSchema, reviewStateOutputSchema } from "../../../core/action/schemas.js";
+import { REVIEW_ACTIVITY_LIST_DEFAULT_LIMIT, REVIEW_ACTIVITY_LIST_MAX_LIMIT, REVIEW_ACTIVITY_LOW_SAMPLE_THRESHOLD } from "../../../core/activity/activityStore.js";
+import { successOutputSchema } from "../../schemas.js";
+import { okToolResult } from "../../result.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+import { reviewActivityListUserAnswerUse, reviewFunnelUserAnswerUse, reviewSessionDetailUserAnswerUse } from "../../responseGuidance.js";
+import { fetchedAtSchema, reviewActivityAccountSourceSchema, reviewActivityDataScopeSchema, reviewActivityInputSchema, userAnswerUseSchema } from "./commonSchemas.js";
+import { activityStoreReadError } from "./readToolHelpers.js";
+const reviewActivityCommonOutput = {
+    dataScope: reviewActivityDataScopeSchema,
+    accountSource: reviewActivityAccountSourceSchema,
+    userAnswerUse: userAnswerUseSchema,
+    lowSampleWarning: z.boolean(),
+    lowSampleThreshold: z.literal(REVIEW_ACTIVITY_LOW_SAMPLE_THRESHOLD),
+    truncated: z.object({
+        activities: z.boolean(),
+        snapshots: z.boolean(),
+        transitions: z.boolean(),
+        requests: z.boolean().optional()
+    })
+};
+const reviewActivityRowSchema = z.object({
+    reviewSessionId: z.string(),
+    planId: z.string(),
+    actionKind: z.string(),
+    adapterId: z.string(),
+    protocol: z.string(),
+    reviewStatus: internalSessionStatusSchema,
+    currentAttemptId: z.string().optional(),
+    requestStatus: transactionRequestStatusSchema.optional(),
+    reviewRevision: z.number().int().nonnegative().optional(),
+    account: z.string(),
+    createdAt: fetchedAtSchema,
+    updatedAt: fetchedAtSchema,
+    executionStatus: z.enum(["success", "failure"]).optional(),
+    transactionDigest: z.string().optional(),
+    snapshotCount: z.number().int().nonnegative(),
+    transitionCount: z.number().int().nonnegative()
+});
+export function registerReviewActivityListTool(server, deps) {
+    server.registerTool(TOOL_NAMES.readListReviewActivity, {
+        title: "List review activity",
+        description: "List local Sui MCP review-session records for one account. Not wallet transaction history.",
+        inputSchema: z.object({
+            ...reviewActivityInputSchema,
+            reviewStatus: internalSessionStatusSchema.optional(),
+            requestStatus: transactionRequestStatusSchema.optional(),
+            executionStatus: z.enum(["success", "failure"]).optional(),
+            limit: z.number().int().min(1).max(REVIEW_ACTIVITY_LIST_MAX_LIMIT).optional()
+        }).strict(),
+        outputSchema: successOutputSchema({
+            ...reviewActivityCommonOutput,
+            activities: z.array(reviewActivityRowSchema)
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async ({ account, from, to, reviewStatus, requestStatus, executionStatus, limit }) => {
+        try {
+            const result = await deps.activityStore.listReviewActivity({
+                account,
+                from,
+                to,
+                reviewStatus, requestStatus, executionStatus,
+                limit: limit ?? REVIEW_ACTIVITY_LIST_DEFAULT_LIMIT
+            });
+            return okToolResult({
+                ...result,
+                userAnswerUse: reviewActivityListUserAnswerUse()
+            });
+        }
+        catch (error) {
+            return activityStoreReadError(error, deps);
+        }
+    });
+}
+export function registerReviewActivitySummaryTools(server, deps) {
+    server.registerTool(TOOL_NAMES.readSummarizeReviewFunnel, {
+        title: "Summarize review funnel",
+        description: "Lifecycle counts for local Sui MCP review sessions in one account scope.",
+        inputSchema: reviewActivityInputSchema,
+        outputSchema: successOutputSchema({
+            ...reviewActivityCommonOutput,
+            summary: z.object({
+                total: z.number().int().nonnegative(),
+                opened: z.number().int().nonnegative(),
+                walletConnected: z.number().int().nonnegative(),
+                stateComputed: z.number().int().nonnegative(),
+                reviewStatusCounts: z.record(internalSessionStatusSchema, z.number().int().nonnegative()),
+                requestStatusCounts: z.array(z.object({ requestStatus: z.enum(TRANSACTION_REQUEST_STATUSES), count: z.number().int().nonnegative() }).strict()),
+                executionStatusCounts: z.object({ success: z.number().int().nonnegative(), failure: z.number().int().nonnegative() }),
+                withoutRequest: z.number().int().nonnegative(),
+                withoutExecutionResult: z.number().int().nonnegative(),
+                everReachedReviewStateCounts: z.object({
+                    ready_for_wallet_review: z.number().int().nonnegative(),
+                    blocked: z.number().int().nonnegative(),
+                    refresh_required: z.number().int().nonnegative()
+                }),
+                everAwaitedChainResult: z.number().int().nonnegative(),
+                expiredWithoutExecutionResult: z.number().int().nonnegative(),
+                avgCreatedToSignatureVerifiedSeconds: z.number().nullable(),
+                avgOpenedToSignatureVerifiedSeconds: z.number().nullable()
+            })
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async ({ account, from, to }) => {
+        try {
+            const result = await deps.activityStore.summarizeReviewFunnel({ account, from, to });
+            return okToolResult({
+                ...result,
+                userAnswerUse: reviewFunnelUserAnswerUse()
+            });
+        }
+        catch (error) {
+            return activityStoreReadError(error, deps);
+        }
+    });
+    server.registerTool(TOOL_NAMES.readGetReviewSessionDetail, {
+        title: "Get review session detail",
+        description: "Return one stored Sui MCP review session with plan, snapshots, transitions, and result.",
+        inputSchema: {
+            reviewSessionId: z.string().min(1),
+            account: z.string().min(1).optional()
+        },
+        outputSchema: successOutputSchema({
+            ...reviewActivityCommonOutput,
+            session: reviewActivityRowSchema.omit({
+                executionStatus: true,
+                transactionDigest: true,
+                requestStatus: true,
+                reviewRevision: true,
+                snapshotCount: true,
+                transitionCount: true
+            }),
+            planJson: actionPlanSchema,
+            intentJson: z.unknown().optional(),
+            stateSnapshots: z.array(z.object({
+                id: z.number().int().positive(),
+                reviewRevision: z.number().int().nonnegative(),
+                planId: z.string(),
+                account: z.string(),
+                status: z.string(),
+                blockedReason: z.string().optional(),
+                refreshReason: z.string().optional(),
+                stateJson: reviewStateOutputSchema,
+                updatedAt: fetchedAtSchema,
+                recordedAt: fetchedAtSchema
+            })),
+            transitions: z.array(z.object({
+                id: z.number().int().positive(),
+                event: z.string(),
+                domain: z.enum(["review", "request"]),
+                attemptId: z.string().optional(),
+                fromStatus: z.string().optional(),
+                toStatus: z.string(),
+                isNoOp: z.boolean(),
+                account: z.string().optional(),
+                reason: z.string().optional(),
+                transitionedAt: fetchedAtSchema
+            })),
+            request: transactionRequestSchema.optional(),
+            requestCount: z.number().int().nonnegative(),
+            requests: z.array(transactionRequestSchema)
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async ({ reviewSessionId, account }) => {
+        try {
+            const result = await deps.activityStore.getReviewSessionDetail({ reviewSessionId, account });
+            return okToolResult({
+                ...result,
+                userAnswerUse: reviewSessionDetailUserAnswerUse({ hasCurrentRequest: !!result.request, hasCurrentExecution: !!result.request?.execution,
+                    hasHistoricalExecution: result.requests.some((request) => !!request.execution) })
+            });
+        }
+        catch (error) {
+            return activityStoreReadError(error, deps);
+        }
+    });
+}

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

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { noParamsInputSchema, successOutputSchema } from "../../schemas.js";
+import { okToolResult } from "../../result.js";
+import { MCP_PROMPTS } from "../../prompts.js";
+import { MCP_RESOURCES } from "../../resources.js";
+import { EVIDENCE_POLICY, FAIL_CLOSED_TOOLS, IMPLEMENTED_TOOLS, PACKAGE_NAME, SERVER_LIMITATIONS, SERVER_NAME, SERVER_NETWORK, SERVER_RUNTIME, SERVER_TRANSPORT, SERVER_VERSION } from "../../serverInfo.js";
+import { TOOL_NAMES } from "../../toolNames.js";
+// Executable swap adapters precede protocol-notes-only entries.
+export const SUPPORTED_PROTOCOLS = [
+    { id: "deepbook-v3", status: "mainnet", support: "read_and_local_review" },
+    { id: "deepbook-margin", status: "mainnet", support: "protocol_notes_only" }
+];
+export function registerServerStatusTools(server) {
+    server.registerTool(TOOL_NAMES.readGetServerStatus, {
+        title: "Get server status",
+        description: "Return package, runtime, tool, resource, and prompt status.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema({
+            packageName: z.string(),
+            serverName: z.string(),
+            version: z.string(),
+            evidencePolicy: z.object({
+                version: z.string(),
+                releaseGate: z.literal("intent_evidence_v1"),
+                requiredFirstCheck: z.literal(true),
+                requiredStatusFields: z.array(z.string()),
+                gates: z.array(z.string())
+            }),
+            network: z.literal("mainnet"),
+            runtime: z.literal("local_stdio"),
+            transport: z.literal("grpc_graphql"),
+            implementedTools: z.array(z.string()),
+            implementedToolsCount: z.number().int().nonnegative(),
+            failClosedTools: z.array(z.string()),
+            resources: z.object({
+                count: z.number().int().nonnegative(),
+                uris: z.array(z.string()),
+                items: z.array(z.object({
+                    name: z.string(),
+                    uri: z.string(),
+                    title: z.string(),
+                    description: z.string()
+                }))
+            }),
+            prompts: z.object({
+                count: z.number().int().nonnegative(),
+                names: z.array(z.string())
+            }),
+            protocolsTool: z.literal("read.list_supported_protocols"),
+            limitations: z.array(z.string())
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async () => okToolResult({
+        packageName: PACKAGE_NAME,
+        serverName: SERVER_NAME,
+        version: SERVER_VERSION,
+        evidencePolicy: {
+            ...EVIDENCE_POLICY,
+            requiredStatusFields: [...EVIDENCE_POLICY.requiredStatusFields],
+            gates: [...EVIDENCE_POLICY.gates]
+        },
+        network: SERVER_NETWORK,
+        runtime: SERVER_RUNTIME,
+        transport: SERVER_TRANSPORT,
+        implementedTools: [...IMPLEMENTED_TOOLS],
+        implementedToolsCount: IMPLEMENTED_TOOLS.length,
+        failClosedTools: [...FAIL_CLOSED_TOOLS],
+        resources: {
+            count: MCP_RESOURCES.length,
+            uris: MCP_RESOURCES.map((resource) => resource.uri),
+            items: MCP_RESOURCES.map((resource) => ({
+                name: resource.name,
+                uri: resource.uri,
+                title: resource.title,
+                description: resource.description
+            }))
+        },
+        prompts: {
+            count: MCP_PROMPTS.length,
+            names: MCP_PROMPTS.map((prompt) => prompt.name)
+        },
+        protocolsTool: TOOL_NAMES.readListSupportedProtocols,
+        limitations: [...SERVER_LIMITATIONS]
+    }));
+    server.registerTool(TOOL_NAMES.readListSupportedProtocols, {
+        title: "List supported protocols",
+        description: "List current mainnet protocol surfaces and support levels.",
+        inputSchema: noParamsInputSchema,
+        outputSchema: successOutputSchema({
+            protocols: z.array(z.object({
+                id: z.string(),
+                status: z.literal("mainnet"),
+                support: z.string()
+            }))
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async () => okToolResult({
+        protocols: [...SUPPORTED_PROTOCOLS]
+    }));
+}