Adds mcp-server generator

[JoseCToscano]

trafficstars

MCP Server Generator for Soroban Smart Contracts

Overview

This PR adds a new MCP (Model Context Protocol)[https://modelcontextprotocol.io/introduction] server generator to the Soroban CLI. The generator creates a TypeScript-based server that provides a standardized interface for interacting with Soroban smart contracts, supporting both SAC (Stellar Asset Contract) and regular (WASM) contracts.

This will create the mcp server configuration for the XLM SAC with the relevant functions formated as tools a MCP client can call.

For instance generating the mcp server for (DoMath)[https://github.com/kalepail/do-math] will create something like this

Key Features

• Automatic generation of MCP server code from contract specifications
• Support for both SAC and WASM contracts
• Follows Typescript bindings standard for functions (tools) return argumens as AssembledTransactions XDR
• Proper handling of read-only and write operations
• Type-safe parameter handling with Zod validation

Technical Details

New Files Added

1. cmd/crates/soroban-spec-typescript/src/mcp_server.rs

   • Core generator implementation
   • Smart contract interface generation
   • Dynamic import management
   • Type conversion handling

2. Template Files:

   • .env.example: Environment configuration template
   • README.md: Documentation and setup instructions
   • build.ts: Production build script to enable runing the mcp-server as standalone built JS
   • package.json: Project dependencies and scripts
   • config.ts: Server configuration management
   • helper.ts: Utility functions
   • index.ts: Server implementation

Transaction Handling Architecture

Dual-Mode Operation

The MCP server implements a dual-mode operation pattern that mirrors the Stellar SDK's behavior while providing AI-friendly interfaces:

1. Read-Only Operations

   • Detected through transaction simulation
   • Returns direct results without requiring signatures
   • Optimizes performance by avoiding unnecessary transaction processing
   • Ideal for data queries and state inspection

2. Write Operations

   • Returns the AssembledTransaction as XDR
   • Follows the TypeScript bindings pattern where contract function calls return AssembledTransaction
   • Requires further processing (signing and submission) through companion tools

Integration with Stellar-MCP

The generator is designed to work seamlessly with the stellar-mcp project, which provides:

• Transaction signing capabilities for:
  • Standard Stellar accounts
  • Smart wallet policy signers
• Transaction submission handling
• AI-oriented interfaces for autonomous operations

Security and AI Agency

This architecture supports the emerging paradigm of Autonomous AI Agents by:

• Separating transaction assembly from signing authority
• Enabling granular permission control through policy signers
• Providing clear boundaries for AI operational capabilities
• Supporting restricted-capability patterns for enhanced security

This separation of concerns allows AI agents to construct valid transactions while maintaining security through controlled signing processes, making it an ideal foundation for autonomous financial operations.

Key Implementation Features

1. Smart Type Handling

   • Automatic conversion between TypeScript and Soroban types
   • Zod schema validation for runtime type safety
   • Proper handling of complex types (u128, i128, etc.)

2. Operation Modes

   • Read-only operations: Direct result return
   • Write operations: Transaction XDR generation with signing instructions
   • Proper error handling for both modes

3. Configuration Management

   • Environment-based configuration
   • Network settings (testnet/public)
   • Contract ID and RPC URL configuration
   • Optional rate limiting and admin authentication

4. Build System

   • ESBuild-based bundling to make sure we can build typescript based dependencies (sac-sdk)[https://www.npmjs.com/package/sac-sdk]

Usage Example

soroban contract bindings mcp-server \
  --contract-id CXYZ... \
  --output-dir ./my-contract-server \
  --name my-contract-server

Next Steps

1. Add comprehensive tests for the generator
2. Add documentation for advanced use cases
3. Consider adding support for additional contract types
4. Implement automated testing in CI pipeline

Breaking Changes

None. This is a new feature that doesn't affect existing functionality.

Dependencies Added

• @modelcontextprotocol/sdk: ^1.0.0
• @stellar/stellar-sdk: ^13.0.0
• sac-sdk: ^0.3.6
• zod: ^3.22.0
• dotenv: ^16.4.7

Development Dependencies Added

• @types/node: ^20.0.0
• typescript: ^5.0.0
• tsx: ^4.7.0
• esbuild: ^0.20.2