MEXC MCP Server

MEXC MCP 服务

一个使用 Encore.ts 实现的模型上下文协议（MCP）服务，用于集成 MEXC 加密货币交易所。

🚀 功能

• 实时市场数据：获取 MEXC 交易所的实时行情价格、订单簿和 24 小时统计数据
• 安全的 API 管理：使用 Encore.ts 密钥管理功能管理 API 密钥
• 速率限制与缓存：内置防护和性能优化
• 类型安全：使用 Encore.ts 接口实现的完整 TypeScript 代码
• 测试驱动开发：全面的测试套件，覆盖率超过 90%
• CI/CD 流水线：自动化测试、Lint 检查和部署
• 提交前钩子：自动化代码质量检查

📋 前提条件

• Bun >= 1.0.0
• Node.js >= 18.0.0
• Encore CLI（用于部署）
• MEXC API 凭据

🛠️ 本地开发设置

1. 克隆并安装

git clone https://github.com/RyanLisse/mexc-mcp-server.git
cd mexc-mcp-server
bun install

2. 环境配置

在项目根目录中创建 .env 文件：

# MEXC API Credentials
MEXC_API_KEY=your_mexc_api_key_here
MEXC_SECRET_KEY=your_mexc_secret_key_here

3. 开发工作流

# Start development server
bun run dev

# Run tests (with watch mode)
bun run test:watch

# Run all quality checks
bun run check

# Format and lint code
bun run format
bun run lint:fix

🧪 测试

# Run all tests
bun test

# Run tests with coverage
bun run test:coverage

# Run specific test file
bun test auth/auth.test.ts

# Test MEXC API connectivity
bun run test:mexc

🔧 可用的 MCP 工具

工具名称	描述	输入参数
mexc_get_ticker	获取当前行情价格和 24 小时统计数据	symbol: string, convert?: string
mexc_get_order_book	获取当前订单簿（买单／卖单）	symbol: string, limit?: number
mexc_get_24h_stats	获取 24 小时交易统计数据	symbol?: string
mexc_test_connectivity	测试 API 连接性和服务器时间	无
mexc_test_authentication	测试 API 身份验证	无
mexc_get_active_symbols	获取所有活跃交易品种	limit?: number
mexc_place_order	下买单／卖单	`symbol: string, side: 'buy'
mexc_cancel_order	取消现有订单	symbol: string, orderId: string
mexc_get_order_status	获取订单状态和详情	symbol: string, orderId: string
mexc_get_account_balance	获取账户余额	无
mexc_get_open_orders	获取所有未结订单	symbol?: string
mexc_get_order_history	获取订单历史记录	symbol?: string, limit?: number
mexc_get_trade_history	获取交易执行历史记录	symbol?: string, limit?: number

🚀 部署

Encore Cloud 部署

1. 安装 Encore CLI：

   curl -L https://encore.dev/install.sh | bash
   

2. 进行身份验证：

   encore auth login
   

3. 设置密钥：

   # For staging environment
   encore secret set --env=staging MEXC_API_KEY "your_api_key"
   encore secret set --env=staging MEXC_SECRET_KEY "your_secret_key"
   
   # For production environment
   encore secret set --env=production MEXC_API_KEY "your_api_key"
   encore secret set --env=production MEXC_SECRET_KEY "your_secret_key"
   

4. 部署：

   # Deploy to staging
   encore deploy --env=staging
   
   # Deploy to production
   encore deploy --env=production
   

自动化部署

项目包含用于自动化部署的 GitHub Actions 工作流：

• CI 流水线（.github/workflows/ci.yml）：在所有 PR 和推送时运行

  • 类型检查
  • Lint 检查和格式化
  • 执行测试
  • 安全扫描
  • 构建验证

• 部署流水线（.github/workflows/deploy.yml）：部署到 Encore Cloud

  • 在推送到 main 分支时触发
  • 支持手动部署并选择环境
  • 自动运行健康检查
  • 密钥管理

必需的 GitHub 密钥

在 GitHub 仓库设置中配置以下密钥：

ENCORE_AUTH_TOKEN=your_encore_auth_token
ENCORE_INSTALL_ID=your_encore_install_id
MEXC_API_KEY=your_mexc_api_key
MEXC_SECRET_KEY=your_mexc_secret_key
CODECOV_TOKEN=your_codecov_token  # Optional, for coverage reports

🔒 安全与密钥管理

Encore.ts 密钥

本项目使用 Encore.ts 内置的密钥管理功能安全存储凭据：

// In shared/config.ts
import { secret } from "encore.dev/config";

// Secrets are automatically injected by Encore.ts
const mexcApiKey = secret("MEXC_API_KEY");
const mexcSecretKey = secret("MEXC_SECRET_KEY");

// For local development, use environment variables
const localConfig = {
  apiKey: process.env.MEXC_API_KEY || mexcApiKey(),
  secretKey: process.env.MEXC_SECRET_KEY || mexcSecretKey(),
};

设置密钥

# Set secrets for different environments
encore secret set --env=development MEXC_API_KEY "your_dev_api_key"
encore secret set --env=development MEXC_SECRET_KEY "your_dev_secret_key"

encore secret set --env=staging MEXC_API_KEY "your_staging_api_key"
encore secret set --env=staging MEXC_SECRET_KEY "your_staging_secret_key"

encore secret set --env=production MEXC_API_KEY "your_prod_api_key"
encore secret set --env=production MEXC_SECRET_KEY "your_prod_secret_key"

最佳实践

• ✅ 切勿将 API 密钥提交到版本控制系统
• ✅ 使用特定于环境的密钥（暂存／生产）
• ✅ 定期轮换 API 密钥
• ✅ 监控 API 使用情况和速率限制
• ✅ 遵循最小权限访问原则

🔄 CI/CD 流水线

提交前钩子

Husky 提交前钩子可确保代码质量：

# Automatically runs on git commit
- Lint-staged (format & lint staged files)
- Type checking
- Test execution

GitHub Actions

CI 工作流（.github/workflows/ci.yml）

• 触发条件：拉取请求，以及推送到 main/develop
• 步骤：安装 → 类型检查 → Lint 检查 → 测试 → 安全扫描 → 构建

部署工作流（.github/workflows/deploy.yml）

• 触发条件：推送到 main 或手动触发
• 步骤：质量检查 → 部署 → 健康检查 → 通知

📊 API 端点

健康状态与信息

• GET /health - 服务健康检查
• GET /mcp/info - MCP 协议信息
• GET / - API 概览

身份验证服务

• POST /auth/validate - 验证 API 密钥
• GET /auth/status - 身份验证状态
• POST /auth/rate-limit - 速率限制状态
• GET /auth/test-mexc - 测试 MEXC 凭据

市场数据服务

• POST /market-data/ticker - 获取行情数据
• POST /market-data/order-book - 获取订单簿
• POST /market-data/24h-stats - 获取 24 小时统计数据
• GET /market-data/test-connectivity - 测试连接
• GET /market-data/test-auth - 测试身份验证
• POST /market-data/active-symbols - 获取活跃交易对
• GET /market-data/health - 市场数据服务健康状态
• GET /market-data/mcp/tools - 可用的 MCP 工具

交易服务

• POST /trading/place-order - 下新订单
• POST /trading/cancel-order - 取消现有订单
• POST /trading/order-status - 获取订单状态
• GET /trading/open-orders - 获取未结订单
• POST /trading/order-history - 获取订单历史记录
• POST /trading/trade-history - 获取交易历史记录
• GET /trading/health - 交易服务健康状态

投资组合服务

• GET /portfolio/balance - 获取账户余额
• GET /portfolio/positions - 获取未平仓头寸
• POST /portfolio/pnl - 获取盈亏数据
• GET /portfolio/health - 投资组合服务健康状态

工具服务（MCP 协议）

• GET /tools/list - 列出所有可用的 MCP 工具
• POST /tools/call - 执行 MCP 工具
• GET /tools/resources - 列出 MCP 资源
• POST /tools/resources/read - 读取 MCP 资源内容

🧩 架构

Encore.ts 服务

该应用采用微服务架构，由 5 个主要服务构成：

mexc-mcp-server/
├── encore.service.ts        # Main service definition
├── api.ts                   # Root API endpoints
├── auth/                    # Authentication service
│   ├── encore.service.ts    # Service definition
│   ├── api.ts              # Auth endpoints
│   └── auth.ts             # Auth logic
├── market-data/             # Market data service
│   ├── encore.service.ts    # Service definition
│   ├── api.ts              # Market data endpoints
│   ├── tools.ts            # MCP tools implementation
│   └── mexc-client.ts      # MEXC API client
├── trading/                 # Trading operations service
│   ├── encore.service.ts    # Service definition
│   ├── api.ts              # Trading endpoints
│   └── tools.ts            # Trading MCP tools
├── portfolio/               # Portfolio management service
│   ├── encore.service.ts    # Service definition
│   ├── api.ts              # Portfolio endpoints
│   └── tools.ts            # Portfolio MCP tools
└── tools/                   # MCP tools aggregation service
    ├── encore.service.ts    # Service definition
    └── api.ts              # MCP protocol endpoints

服务依赖关系

• auth：基础身份验证和速率限制
• market-data：实时市场数据（依赖 auth）
• trading：订单管理（依赖 auth、market-data）
• portfolio：账户和头寸跟踪（依赖 auth、trading）
• tools：MCP 协议实现（汇总所有服务）

🤝 参与贡献

1. Fork 代码仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 按照编码规范进行修改
4. 运行测试：bun test
5. 使用规范化提交信息：git commit -m "feat: add amazing feature"
6. 推送到你的分支：git push origin feature/amazing-feature
7. 创建 Pull Request

开发规范

• ✅ 使用严格模式的 TypeScript
• ✅ 测试驱动开发（TDD）
• ✅ 文件行数少于 500 行
• ✅ 使用 Encore.ts 接口确保类型安全
• ✅ 规范化提交
• ✅ 新功能的测试覆盖率达到 90% 以上
• ✅ 使用 Biome.js 进行代码检查和格式化

📝 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🆘 支持

• 📖 文档
• 🐛 问题反馈
• 💬 讨论
• 📧 电子邮箱：[email protected]