Adds mcp-server generator #1985

JoseCToscano · 2025-03-25T20:09:02Z

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

cmd/crates/soroban-spec-typescript/src/mcp_server.rs
- Core generator implementation
- Smart contract interface generation
- Dynamic import management
- Type conversion handling
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:

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
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

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.)
Operation Modes
- Read-only operations: Direct result return
- Write operations: Transaction XDR generation with signing instructions
- Proper error handling for both modes
Configuration Management
- Environment-based configuration
- Network settings (testnet/public)
- Contract ID and RPC URL configuration
- Optional rate limiting and admin authentication
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

Add comprehensive tests for the generator
Add documentation for advanced use cases
Consider adding support for additional contract types
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

Add support for generating MCP server bindings from Soroban contracts: - Implement MCP server code generator with TypeScript template - Add support for Buffer and array inputs in type validation - Include transaction simulation and submission capabilities - Add comprehensive error handling for Horizon responses

Fix the "Bad union switch: 1" error that was occurring when handling transaction responses from the Stellar network. The following changes were made: 1. Simplified submitTransaction function in helper.ts to immediately return success with the transaction hash without waiting for confirmation 2. Improved error handling in index.ts to properly handle XDR parsing errors These changes resolve the JSON parsing errors in the Claude app while still allowing users to track their transactions via the transaction hash and Stellar Explorer.

socket-security · 2025-03-25T20:10:08Z

New dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher
npm/@modelcontextprotocol/[email protected]	Transitive: environment, eval, filesystem, network, shell, unsafe	`+70`	6.48 MB	jspahrsummers
npm/@stellar/[email protected]	Transitive: network	`+1`	15 MB	stellar-npm-ci
npm/@types/[email protected]	None	`+1`	84.2 kB
npm/[email protected]	environment, filesystem	`0`	75.8 kB	motdotla
npm/[email protected]	environment, filesystem, network, shell	`+23`	224 MB	evanw
npm/[email protected]	None	`0`	67.2 kB	tyvdh
npm/[email protected]	Transitive: environment, filesystem, network, shell	`+29`	257 MB	hirokiosame
npm/[email protected]	None	`0`	699 kB	colinhacks

View full report↗︎

socket-security · 2025-03-25T20:10:10Z

👍 Dependency issues cleared. 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↗︎

…nsaction building parameters - Use SAC client instead of TransactionBuilder - Return XDR directly - Simplify response format [Author] Cursor Agent

…ies - Add proper environment variable handling - Add dotenv configuration [Author] Cursor Agent

…ate_tool [Author] Cursor Agent - Added import tracking in type_to_zod for type-specific converters - Updated generate_tool to track imports for parameter conversions - Fixed method calls to use instance methods instead of static methods - Refactored converter selection to track imports

…ursor Agent - Fixed import replacement in index.ts template - Aligned imports with helper.ts usage

…e formatted strings in variables to ensure proper lifetimes - Fix temporary value dropped while borrowed errors

…t values

janewang · 2025-05-07T20:31:37Z

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

Copilot

Pull Request Overview

This PR introduces an MCP server generator for Soroban smart contracts by adding a new command to the Soroban CLI and providing a TypeScript-based server template.

Updated the command handling to pass global arguments to the new MCP server command.
Added multiple new files for the MCP server generator including the core generator implementation in Rust and a full TypeScript project template with build scripts and helper functions.

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
cmd/soroban-cli/src/commands/contract/mod.rs	Updated the bindings command to pass global arguments correctly.
cmd/soroban-cli/src/commands/contract/bindings/mcp_server.rs	Added the new MCP server command implementation and error handling.
cmd/soroban-cli/src/commands/contract/bindings.rs	Integrated the new MCP server command into the existing bindings module.
cmd/crates/soroban-spec-typescript/src/mcp_server_template/*	Added TypeScript project template files, including build configurations, a runtime server implementation, helpers, documentation, and configuration management.
cmd/crates/soroban-spec-typescript/src/lib.rs & Cargo.toml	Integrated and referenced the new MCP server generator module.

Comments suppressed due to low confidence (3)

cmd/crates/soroban-spec-typescript/src/mcp_server_template/src/index.ts:50

[nitpick] The placeholder 'INSERT_TOOLS_HERE' should be replaced with the actual tool registrations or accompanied by clear instructions to ensure the server starts without runtime errors.

INSERT_TOOLS_HERE

cmd/crates/soroban-spec-typescript/src/mcp_server_template/README.md:53

[nitpick] Replace the 'INSERT_TOOL_LIST_HERE' placeholder with either the generated list of contract tools or a note detailing that this section will be auto-populated to improve clarity for users setting up the MCP server.

INSERT_TOOL_LIST_HERE

cmd/crates/soroban-spec-typescript/src/mcp_server_template/package.json:2

[nitpick] Update the 'INSERT_NAME_HERE' placeholder in package.json with the actual package name to ensure consistency and clarity in the generated project output.

"name": "INSERT_NAME_HERE",

fnando · 2025-06-16T17:36:34Z

@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.

JoseCToscano added 2 commits March 25, 2025 08:38

github-project-automation bot added this to DevX Mar 25, 2025

github-project-automation bot moved this to Backlog (Not Ready) in DevX Mar 25, 2025

JoseCToscano added 11 commits March 27, 2025 17:55

[Refactor] Update MCP server generator to use SAC client - Remove tra…

84ebe88

…nsaction building parameters - Use SAC client instead of TransactionBuilder - Return XDR directly - Simplify response format [Author] Cursor Agent

[Feat] Update MCP server template - Add missing imports and dependenc…

c2d7c78

…ies - Add proper environment variable handling - Add dotenv configuration [Author] Cursor Agent

[Refactor] Update generate function to use dynamic imports [Author] C…

608f1a7

…ursor Agent - Fixed import replacement in index.ts template - Aligned imports with helper.ts usage

[Fix] Fix lifetime issues in get_imports [Author] Cursor Agent - Stor…

1ce9540

…e formatted strings in variables to ensure proper lifetimes - Fix temporary value dropped while borrowed errors

checkpoint

3dcbda6

Working mcp generator for SAC

0ef7004

Working version for SAC

92bef50

checkpoint

3a8cfdf

Working version. Checkpoint before refactoring to read only fx calls

222bf07

Working version

3a8f819

JoseCToscano force-pushed the main branch from 3b253ab to 3a8f819 Compare March 28, 2025 19:00

JoseCToscano and others added 3 commits March 29, 2025 03:00

Merge branch 'stellar:main' into main

4dfdcc8

Adds repalcer to be used on JSON.stringify to avoid errors with bigin…

6b02708

…t values

Updates README.md template for generated mcp servers

40a2d9d

janewang requested a review from leighmcculloch June 16, 2025 15:23

sagpatil requested a review from Copilot June 16, 2025 15:46

Copilot AI reviewed Jun 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Adds mcp-server generator #1985

Adds mcp-server generator #1985

Uh oh!

JoseCToscano commented Mar 25, 2025 •

edited

Loading

Uh oh!

socket-security bot commented Mar 25, 2025 •

edited

Loading

Uh oh!

socket-security bot commented Mar 25, 2025 •

edited

Loading

Uh oh!

janewang commented May 7, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

fnando commented Jun 16, 2025

Uh oh!

Uh oh!

Adds mcp-server generator #1985

Are you sure you want to change the base?

Adds mcp-server generator #1985

Uh oh!

Conversation

JoseCToscano commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

MCP Server Generator for Soroban Smart Contracts

Overview

Key Features

Technical Details

New Files Added

Transaction Handling Architecture

Dual-Mode Operation

Integration with Stellar-MCP

Security and AI Agency

Key Implementation Features

Usage Example

Next Steps

Breaking Changes

Dependencies Added

Development Dependencies Added

Uh oh!

socket-security bot commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security bot commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

janewang commented May 7, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

fnando commented Jun 16, 2025

Uh oh!

Uh oh!

JoseCToscano commented Mar 25, 2025 •

edited

Loading

socket-security bot commented Mar 25, 2025 •

edited

Loading

socket-security bot commented Mar 25, 2025 •

edited

Loading