🎛️feat(mcp): add orchestrate-escrow tool — single MCP command drives the full deploy → fund → release lifecycle

[sotoJ24]

Title

feat(mcp): add orchestrate-escrow tool — single MCP command drives the full deploy → fund → release lifecycle, guiding Claude through each XDR signing step

Issue Summary

Currently a developer using the SafeTrust MCP must call deploy-escrow, then manually handle the XDR signing in Freighter, then call fund-escrow, then sign again. There is no single tool that explains the full sequence and tracks state across steps. This issue adds orchestrate-escrow — a stateless tool that accepts a step parameter and returns exactly what to do next, including the XDR that needs signing and the subsequent MCP tool call to make. It does not introduce state — each call is independent and the caller passes engagementId and contractId to resume a sequence.

Type of Issue

• Feature Request

Branch strategy

✅ feat/issue-N-orchestrate-escrow → consolidation-pattern
❌ feat/issue-N-orchestrate-escrow → main

Current Behavior

Developer workflow (3 separate tool calls + manual XDR handling):
1. MCP: deploy-escrow → gets unsignedXDR
2. Developer: manually opens Freighter, signs XDR, gets signedXDR
3. MCP: (no submit tool) → developer calls frontend send-transaction manually
4. MCP: fund-escrow → gets another unsignedXDR
5. Developer: signs again in Freighter
6. MCP: (no release tool) → manual again

Expected Behavior

mcp/src/tools/
├── apartments.ts     ← unchanged
├── escrow.ts         ← add orchestrate-escrow tool here
└── hasura.ts         ← unchanged

New orchestrate-escrow tool

server.registerTool(
  'orchestrate-escrow',
  {
    title: 'Orchestrate escrow',
    description:
      'Step-by-step guide for the full SafeTrust escrow lifecycle. ' +
      'Call with step="start" to begin, then follow the "next" instruction ' +
      'in each response. Stateless — pass engagementId and contractId from ' +
      'previous steps to resume.',
    inputSchema: z.object({
      step: z.enum(['start', 'after-deploy', 'after-fund', 'status'])
        .describe('Current step in the lifecycle'),
      apartmentId: z.string().uuid().optional(),
      senderAddress: stellarAddress.optional(),
      receiverAddress: stellarAddress.optional(),
      amount: z.number().positive().optional(),
      engagementId: z.string().optional(),
      contractId: z.string().optional(),
    }),
  },
  async ({ step, apartmentId, senderAddress, receiverAddress, amount, engagementId, contractId }) => {
    switch (step) {
      case 'start':
        if (!apartmentId || !senderAddress || !receiverAddress || !amount) {
          return errorResult(
            'For step=start, provide: apartmentId, senderAddress, receiverAddress, amount'
          );
        }
        return textResult(
          '── Step 1: Deploy escrow ──────────────────────────────────',
          'Call deploy-escrow with these parameters:',
          jsonBlock({ apartmentId, senderAddress, receiverAddress, amount }),
          '',
          'deploy-escrow will return an unsignedXDR.',
          'Sign it with Freighter in the browser.',
          'Then call orchestrate-escrow again with:',
          '  step: "after-deploy"',
          '  engagementId: (from deploy-escrow response)',
          '  contractId: (from deploy-escrow response)',
          '  senderAddress: (same as above)',
          '  amount: (same as above)',
        );

      case 'after-deploy':
        if (!contractId || !senderAddress || !amount) {
          return errorResult(
            'For step=after-deploy, provide: contractId, senderAddress, amount'
          );
        }
        return textResult(
          '── Step 2: Fund escrow ────────────────────────────────────',
          `contractId: ${contractId}`,
          '',
          'The deploy XDR has been signed and submitted.',
          'Now call fund-escrow with:',
          jsonBlock({ contractId, signer: senderAddress, amount }),
          '',
          'fund-escrow returns another unsignedXDR.',
          'Sign it with Freighter.',
          'Then call orchestrate-escrow with step="after-fund" to continue.',
        );

      case 'after-fund':
        return textResult(
          '── Step 3: Escrow funded ──────────────────────────────────',
          'The escrow is now funded and locked on Stellar.',
          '',
          'When the host completes the service:',
          '  1. Host marks milestone done (POST /api/escrow/milestone-status)',
          '  2. Tenant calls release-funds (POST /api/escrow/release-funds)',
          '',
          'To check current status:',
          '  call get-escrow-status with contractId or engagementId',
          '',
          escrowRolesDoc(),
        );

      case 'status':
        if (!contractId && !engagementId) {
          return errorResult('Provide contractId or engagementId to check status.');
        }
        return textResult(
          'Call get-escrow-status with:',
          jsonBlock({ contractId, engagementId }),
        );
    }
  },
);

Consolidation pattern alignment

This tool respects the Compute Resource Consolidation pattern:

• orchestrate-escrow with step=start → guides caller to use deploy-escrow
• deploy-escrow → calls apps/api POST /api/escrow/deploy → calls TrustlessWork
• MCP never calls TrustlessWork directly
• XDR signing always happens in the browser (Freighter) — never server-side

Files to create / modify

File	Status	Action
mcp/src/tools/escrow.ts	✅ exists	Add orchestrate-escrow tool
mcp/README.md	✅ exists	Document the orchestration flow

Acceptance Criteria

• orchestrate-escrow step=start without required fields returns clear error
• orchestrate-escrow step=start with all fields returns correct next-step instructions
• orchestrate-escrow step=after-deploy returns fund-escrow parameters
• Tool never calls TrustlessWork directly — always routes through apps/api
• pnpm --filter @safetrust/mcp test still passes

[rudrasatani13]

A stateless step tool that returns the next call in the deploy -> fund -> release sequence with its exact arguments, so a developer stops rebuilding the sequence by hand between two Freighter signing round-trips. The tool never calls TrustlessWork itself; it only says which call to make next.

Writing it surfaced that fund-escrow never sends the engagementId that POST /api/escrow/fund requires, so that tool could only ever return 400. I would fix that in the same PR, because the guide hands over exactly that call, and cover both with tests through a real MCP server and client.

[guptakumarranjeet150]

Hi everyone,

I would love to take this on. My planned approach:

• Implement 🎛️feat(mcp): add orchestrate-escrow tool — single MCP command drives the full deploy → fund → release lifecycle with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.

Looking forward to contributing—please feel free to assign!

[Okorie2000-code]

The issue description is crystal clear, and I’d be glad to work on it. I’ll ensure the implementation is clean, tested, and submit a clean PR. Kindly assign it to me. 🙏

[Iker2522]

Hi, I’d like to take this issue. I have experience with backend development, APIs, TypeScript, testing, and integrating services through structured workflows. I’m interested in this task because it combines MCP tooling with an existing escrow flow while keeping the architecture stateless and easy to follow.

I can implement the orchestrate-escrow tool with the required step-based flow, clear validation and instructions for each stage, while ensuring that TrustlessWork is only accessed through the existing API layer and that XDR signing remains on the client side through Freighter.

I’ll also update the MCP documentation and add or adjust tests to cover the different steps and validation cases, while making sure the existing MCP test suite continues to pass.