内容
# 🌟 星际 MCP 服务器
一款全面的模型上下文协议（MCP）服务器，使 AI 助手能够与星际区块链网络交互。该服务器为星际经典操作和 Soroban 智能合约开发提供工具，允许大型语言模型（LLM）管理账户、处理支付、部署合约并执行复杂的区块链操作。
## 📋 目录
- [概述](#overview)
- [功能](#features)
- [架构](#architecture)
- [安装](#installation)
- [配置](#configuration)
- [用法](#usage)
- [可用工具](#available-tools)
- [开发](#development)
- [贡献](#contributing)
- [许可证](#license)
## 📚 文档
完整文档位于 [`apps/docs`](apps/docs) 作为 [Fumadocs](https://fumadocs.dev) 站点。
```bash
cd apps/docs
npm install
npm run dev # http://localhost:3000
```
参见 [部署文档](apps/docs/content/docs/deployment.mdx) 了解如何发布它（Vercel、Netlify、静态导出或 Docker）。
## 🎯 概述
星际 MCP 服务器弥合了 AI 助手和星际区块链网络之间的差距。它实现了模型上下文协议，为 LLM 提供了一个标准化的接口，用于：
- **管理星际账户** - 创建、资助和监控账户
- **处理支付** - 在网络中发送和接收支付
- **处理资产** - 创建自定义资产和管理信任线
- **部署智能合约** - 构建和部署 Soroban 合约
- **与合约交互** - 检索合约接口并调用方法
- **监控交易** - 跟踪交易历史和状态
## ✨ 功能
### 星际经典操作
- 账户创建和管理
- 余额查询
- 支付处理
- 资产创建和信任线管理
- 可认领余额操作
- 交易历史检索
- 通过 Friendbot 资助测试网账户
### Soroban 智能合约操作
- 合约构建和优化
- 合约部署，支持构造函数
- 合约接口检索
- 支持复杂数据类型（结构体、枚举、集合）
- 跨平台兼容性（Windows、Linux、macOS）
### 开发人员体验
- 类型安全的 TypeScript 实现
- 全面的 JSDoc 文档
- 跨平台支持
- 多种部署选项（本地、NPX、Docker）
- MCP Inspector 集成用于调试
## 🏗️ 架构
星际 MCP 服务器采用模块化架构，分离关注点，便于维护：
```
stellar-mcp-server/
├── src/
│ ├── index.ts # 主服务器入口点 + 工具路由
│ ├── config/ # 配置管理
│ │ └── environment.config.ts
│ ├── shared/ # 跨功能共享的类型
│ │ └── common.interface.ts
│ ├── features/ # 功能模块（共存逻辑/类型/测试）
│ │ ├── classic/ # 星际经典操作
│ │ │ ├── classic.ts
│ │ │ └── schemas.ts
│ │ ├── soroban/ # Soroban 智能合约操作
│ │ │ ├── soroban.ts
│ │ │ ├── schemas.ts
│ │ │ ├── deployContract.interface.ts
│ │ │ └── getContractMethods.interface.ts
│ │ └── core/ # 核心实用程序
│ │ ├── core.ts # 平台特定命令
│ │ ├── messages.ts # 消息格式化
│ │ ├── fileSystem.ts # 文件系统操作
│ │ ├── contractParser.ts # 合约源代码解析
│ │ ├── commands.interface.ts
│ │ └── contract.interface.ts
│ └── tools/ # MCP 工具定义
│ ├── classic.ts
│ ├── soroban.ts
│ └── tools.ts
├── apps/
│ └── docs/ # Fumadocs 文档站点
├── package.json
├── tsconfig.json
└── README.md
```
### 关键组件
- **服务器层** (`src/index.ts`)：MCP 服务器实现、工具路由和请求处理
- **功能层** (`src/features/`)：区块链逻辑，适用于 Classic 和 Soroban，以及共享的 `core` 实用程序
- **工具层** (`src/tools/`)：MCP 工具定义和模式
- **核心层** (`src/features/core/`)：跨平台实用程序和共享功能
- **共享层** (`src/shared/`)：跨功能使用的类型定义
## 📦 安装
### 先决条件
- Node.js 18+
- npm 或 yarn
- Git（用于克隆存储库）
### 安装依赖项
```bash
npm install
```
### 构建项目
```bash
npm run build
```
## ⚙️ 配置
### 环境变量
在项目根目录中创建一个 `.env` 文件，包含以下配置：
```env
STELLAR_SERVER_URL=https://horizon-testnet.stellar.org
```
**可用的星际网络：**
- **测试网**：`https://horizon-testnet.stellar.org`
- **公共网络**：`https://horizon.stellar.org`
- **未来网络**：`https://horizon-futurenet.stellar.org`
### MCP 客户端配置
配置您的 MCP 客户端（Cursor、Windsurf、Claude Desktop）以使用星际 MCP 服务器：
#### 本地安装
```json
{
"mcpServers": {
"stellar-mcp": {
"command": "node",
"args": ["/path/to/stellar-mcp-server/dist/index.js"]
}
}
}
```
#### NPX 安装
```json
{
"mcpServers": {
"stellar-mcp": {
"command": "npx",
"args": ["-y", "stellar-mcp-server"]
}
}
}
```
#### Docker 安装
```json
{
"mcpServers": {
"stellar-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e",
"STELLAR_SERVER_URL=https://horizon-testnet.stellar.org",
"stellar-mcp-server"
]
}
}
}
```
## 🚀 用法
### 运行服务器
**开发模式：**
```bash
npm run start:dev
```
**生产模式：**
```bash
npm run start:prod
```
### 使用 MCP Inspector 调试
调试服务器并监控交互：
```bash
npx @modelcontextprotocol/inspector node /path/to/stellar-mcp-server/dist/index.js
```
然后打开浏览器，访问 `http://localhost:5173` 查看 Inspector 界面。
## 🛠️ 可用工具
### 星际经典工具
#### `stellar_create_account`
使用随机密钥对创建新的星际账户。
**返回：** 新账户的公钥和私钥
#### `stellar_balance`
获取星际账户的余额，包括所有资产。
**参数：
- `account`（字符串）：要检查余额的账户公钥
#### `stellar_payment`
向另一个星际账户发送支付。
**参数：
- `destination`（字符串，必填）：目标账户公钥
- `amount`（字符串，必填）：要发送的金额
- `secretKey`（字符串，必填）：源账户的私钥
- `asset`（对象，可选）：自定义资产详情
- `code`（字符串）：资产代码
- `issuer`（字符串）：资产发行人公钥
#### `stellar_transactions`
获取星际账户的交易历史。
**参数：
- `account`（字符串）：要获取交易的账户公钥
#### `stellar_create_asset`
在星际网络上创建新的自定义资产。
**参数：
- `code`（字符串，必填）：资产代码
- `issuerSecretKey`（字符串，必填）：发行账户的私钥
- `distributorSecretKey`（字符串，必填）：分发账户的私钥
- `totalSupply`（字符串，必填）：资产的总供应量
#### `stellar_change_trust`
为自定义资产创建或修改信任线。
**参数：
- `asset`（对象，必填）：
- `code`（字符串，必填）：资产代码
- `issuer`（字符串，必填）：资产发行人公钥
- `limit`（字符串，必填）：信任限制
- `secretKey`（字符串，必填）：更改信任账户的私钥
#### `stellar_create_claimable_balance`
创建可认领余额，可由指定账户在特定条件下认领。
**参数：
- `asset`（对象，可选）：自定义资产详情。如果不提供，则使用原生 XLM
- `code`（字符串）：资产代码（例如“USD”，“EUR”）
- `issuer`（字符串）：资产发行人公钥
- `amount`（字符串，必填）：锁定到可认领余额的金额
- `claimants`（数组，必填）：可以认领此余额的账户列表
- `destination`（字符串）：可以认领的账户公钥
- `predicate`（对象）：认领条件
- `type`（字符串）：以下之一： “UNCONDITIONAL”，“BEFORE_RELATIVE_TIME”，“BEFORE_ABSOLUTE_TIME”，“NOT”，“AND”，“OR”
- `value`（数字或数组）：对于时间谓词：秒/时间戳，对于复合谓词：谓词数组
- `secretKey`（字符串，必填）：创建余额账户的私钥
#### `stellar_claim_claimable_balance`
使用其 ID 认领可认领余额。
**参数：
- `balanceId`（字符串，必填）：要认领的可认领余额 ID
- `secretKey`（字符串，必填）：认领账户的私钥
#### `stellar_fund_account`
使用 Friendbot 喷泉资助测试网账户。
**参数：
- `publicKey`（字符串）：要资助的账户公钥
### Soroban 工具
#### `soroban_build_and_optimize`
从源代码构建和优化 Soroban 智能合约。
**参数：
- `contractPath`（字符串，可选）：合约目录路径。默认为当前工作目录
**功能：
- 自动使用 `stellar contract build` 构建合约
- 查找目标目录中的所有 WASM 文件
- 使用 `stellar contract optimize` 优化每个 WASM 文件
- 提供整个过程的详细日志
#### `soroban_deploy`
将编译的 Soroban 合约部署到星际网络。
**参数：
- `wasmPath`（字符串，必填）：编译后的 WASM 文件路径
- `secretKey`（字符串，必填）：部署账户的私钥
- `constructorArgs`（数组，可选）：合约构造函数的参数（如果适用）
- 每个参数应为一个对象，包含：
- `name`（字符串）：构造函数参数名称
- `type`（字符串）：参数类型（例如“Address”，“String”等）
- `value`（字符串）：参数值
**功能：
- 自动检测合约是否有构造函数
- 在部署前验证构造函数参数
- 提供详细的部署日志和状态更新
- 支持简单合约和具有初始化逻辑的合约
#### `soroban_retrieve_contract_methods`
检索已部署的 Soroban 智能合约的完整接口。
**参数：
- `contractAddress`（字符串，必填）：已部署合约的地址（以“C”开头）
- `secretKey`（字符串，必填）：查询账户的私钥
**返回：** 一个结构化的 ContractInterface 对象，包含：
- `name`：合约名称
- `methods`：合约方法数组，包含参数和返回类型
- `structs`：合约结构体数组，包含字段
- `enums`：合约枚举数组，包含变体
**功能：
- 支持所有 Soroban 数据类型（原始类型、结构体、嵌套结构体、枚举）
- 处理复杂数据类型和嵌套结构
- 自动从方法签名中过滤掉 `env` 参数
- 支持各种枚举类型，包括错误枚举
## 💻 开发
### 项目结构
```
stellar-mcp-server/
├── src/
│ ├── index.ts # 主服务器入口点
│ ├── config/ # 配置管理
│ ├── shared/ # 共享 TypeScript 类型
│ ├── features/ # 功能模块（classic、soroban、core）
│ └── tools/ # MCP 工具定义
├── apps/docs/ # Fumadocs 文档站点
├── package.json
├── tsconfig.json
└── README.md
```
### 可用脚本
- `npm run build` - 将 TypeScript 编译为 JavaScript
- `npm run start:dev` - 在开发模式下运行，支持热重载
- `npm run start:prod` - 在生产模式下运行
- `npm run lint` - 运行 ESLint 进行代码质量检查
- `npm test` - 运行测试套件
### 添加新工具
添加新的星际工具：
1. 在 `src/features/[classic|soroban]/schemas.ts` 中定义工具模式
2. 在 `src/features/[classic|soroban]/[classic|soroban].ts` 中实现工具逻辑
3. 在 `src/tools/[classic|soroban].ts` 中添加工具定义
4. 在 `src/index.ts` 中添加工具处理程序
### 代码风格
- 对所有新代码使用 TypeScript
- 为所有公共函数和类添加 JSDoc 注释
- 遵循现有的代码模式和约定
- 使用约定提交消息
## 🤝 贡献
我们欢迎为星际 MCP 服务器做出贡献！请参阅我们的 [贡献指南](docs/CONTRIBUTING.md) 了解如何开始。
### 贡献者快速入门
1. 复刻存储库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 进行更改
4. 使用约定提交消息提交
5. 推送到您的复刻 (`git push origin feature/amazing-feature`)
6. 打开拉取请求
## 📄 许可证
该 MCP 服务器根据 MIT 许可证获得许可。这意味着您可以自由使用、修改和分发软件，但需遵守 MIT 许可证的条款和条件。有关详细信息，请参阅项目存储库中的 LICENSE 文件。
