Adds mcp-server generator

[JoseCToscano]

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

[socket-security[bot]]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	esbuild@​0.20.2
	sac-sdk@​0.3.8
	@​types/​node@​20.19.7
	tsx@​4.20.3
	dotenv@​16.6.1
	zod@​3.25.76
	@​modelcontextprotocol/​sdk@​1.15.1

View full report

[socket-security[bot]]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

[janewang]

@JoseCToscano Awesome work, could you create this as a plugin? https://developers.stellar.org/docs/tools/cli/plugins

[fnando]

@JoseCToscano this is amazing! Thanks for this!

After some internal discussion, we came to the conclusion that we want to keep the CLI core as small as possible, pushing features like this as external plugins. This allows for a faster development cycle, without diverging too much from the native experience.

Could you please extract this work into its own executable, and make it available as a plugin instead? Here is the documentation around CLI plugins.

[janewang]

@JoseCToscano pinging again on this, to see if we can convert into a plugin. Thank you!

[JoseCToscano]

@JoseCToscano pinging again on this, to see if we can convert into a plugin. Thank you!

Sure, will take a look! 😎