MCP Solana Affiliate

MCP Solana联盟服务器

该项目提供了一个单独的MCP（模型上下文协议）服务器，用于管理与 mcp_solana_ico 项目。它的设计完全独立于主ICO服务器，处理联盟注册和佣金跟踪的各个方面。

主要特点

• 联盟注册： 提供 affiliate://register 生成唯一联盟ID和Solana Blink URL的资源。
• 闪烁URL处理： 生成的Blink URL指向一个端点(/affiliate_buy_tokens) *在此服务器内*.
• 代理功能： 这 /affiliate_buy_tokens 端点充当代理。它接收来自Blinks的请求，将购买请求转发到主ICO服务器的Action API，然后记录佣金。
• 永久存储： 联盟数据和佣金持久存储在JSON文件中(affiliate_data.json).
• 完全分离： 此服务器已 *不* 对main的依赖 mcp_solana_ico 服务器，而不是使用其Action API URL来构建购买交易。主ICO服务器不知道联盟计划。
• 健康监测： 内置健康检查和指标端点，用于监控服务状态。
• 类型安全： 完整的类型提示和Pydantic模型，用于稳健的数据验证。
• 综合日志记录： 具有可配置级别和文件输出的结构化日志记录。
• 安全： 整个应用程序的输入验证和安全措施。

需求

• Python 3.11+
• 诗歌
• 烧瓶

安装

1. 克隆存储库：

   git clone 
   cd mcp_solana_affiliate

1. 安装依赖项：

   poetry install

配置

.env 文件

创建一个 .env 根目录中的文件，内容如下：

MAIN_SERVER_URL="http://localhost:5000"  # URL of the main mcp_solana_ico server's Action API

重要提示： MAIN_SERVER_URL 必须指向主ICO服务器的操作API的正确位置。

用法

1. 启动服务器：

   poetry run python mcp_solana_affiliate/server.py

这将启动FastMCP服务器（用于 affiliate://register)端口5001和端口5002上的Flask应用程序（用于处理Blink请求和佣金记录）。

1. 注册附属公司： 使用MCP客户端调用 affiliate://register 资源。这将返回Solana Blink URL。

1. 通过Blinks购买代币： 当用户点击Blink URL时，它将向 /affiliate_buy_tokens 此服务器上的终结点。此端点将：

- 提取 amount 根据请求。 - 将购买请求（无任何关联信息）转发到主ICO服务器的Action API(/buy_tokens_action). - 从主服务器接收序列化的Solana事务。 - 将佣金记录在 affiliate_data.json. - 将序列化事务返回给Blink客户端。

API文档

MCP资源

affiliate://register

注册新的联盟并返回Solana Blink URL。

答复：

"Affiliate registered successfully! Your Solana Blink URL is: solana-action:http://localhost:5000/affiliate_buy_tokens?affiliate_id=123e4567-e89b-12d3-a456-426614174000"

REST端点

发布 /affiliate_buy_tokens

通过联盟链接处理代币购买。

请求：

{
  "amount": 1000.0,
  "affiliate_id": "123e4567-e89b-12d3-a456-426614174000"
}

响应（成功）：

{
  "transaction": "base64-encoded-transaction"
}

响应（错误）：

{
  "error": "Error message"
}

状态代码：

• 200 -成功
• 400 -错误请求（验证错误）
• 500 -内部服务器错误
• 502 -网关错误（主服务器错误）
• 503 -服务不可用（超时）

发布 /record_commission

手动记录联盟的佣金。

请求：

{
  "affiliate_id": "123e4567-e89b-12d3-a456-426614174000",
  "ico_id": "main_ico",
  "amount": 1000.0,
  "commission": 50.0,
  "client_ip": "127.0.0.1"
}

响应（成功）：

{
  "message": "Commission recorded successfully"
}

响应（错误）：

{
  "error": "Error message"
}

获取 /health

用于监视的健康检查端点。

答复：

{
  "status": "healthy",
  "timestamp": 1234567890,
  "service": "mcp-solana-affiliate",
  "version": "1.0.0",
  "checks": {
    "affiliate_data": "healthy",
    "main_server": "healthy",
    "database": "healthy"
  }
}

获取 /metrics

用于监视服务统计信息的度量端点。

答复：

{
  "total_affiliates": 10,
  "total_commissions": 25,
  "total_commission_amount": 1250.0,
  "timestamp": 1234567890
}

获取 /cache/stats

用于监控缓存性能的缓存统计端点。

答复：

{
  "affiliate_cache": {
    "total_items": 5,
    "expired_items": 1,
    "active_items": 4,
    "hit_count": 150,
    "miss_count": 25
  },
  "metrics_cache": { ... },
  "health_cache": { ... }
}

发布 /cache/clear

清除所有缓存数据。

答复：

{
  "message": "All caches cleared successfully"
}

发布 /cache/cleanup

从缓存中删除过期项目。

答复：

{
  "message": "Cache cleanup completed",
  "items_removed": 3
}

配置

该应用程序使用Pydantic模型进行配置管理。可以通过环境变量设置配置：

环境变量

数据模型

该应用程序使用以下数据模型：

调试记录

{
  "ico_id": "main_ico",
  "amount": 1000.0,
  "commission": 50.0,
  "client_ip": "192.168.1.1",
  "timestamp": 1234567890
}

附属数据

{
  "affiliate_id": "123e4567-e89b-12d3-a456-426614174000",
  "commissions": [CommissionRecord],
  "created_at": 1234567890,
  "last_updated": 1234567890
}

项目结构

mcp_solana_affiliate/
├── affiliates.py      # Core affiliate logic (generation, storage, commission recording)
├── server.py           # Main server code (FastMCP resource and Flask app)
├── config.py           # Configuration management with Pydantic models
├── models.py           # Data models using Pydantic
├── services.py         # Service layer for business logic
├── __init__.py
.env                    # Environment variables
.gitignore
pyproject.toml          # Poetry configuration
README.md               # This file

建筑

该应用程序遵循分层架构：

• 演示层： 处理HTTP请求/响应的Flask端点
• 服务层： 业务逻辑 services.py （关联服务、交易服务等）
• 数据层： 数据访问和持久性 affiliates.py
• 配置层： 集中配置管理 config.py
• 模型层： 数据验证和序列化 models.py

关键组件

• 附属服务： 处理联盟注册和数据检索
• 事务服务： 处理代币购买和佣金记录
• 医疗服务： 提供健康检查和监控功能
• 计量服务： 收集并公开服务指标
• 配置管理： 基于环境的配置与Pydantic验证
• 错误处理： 使用适当的HTTP状态代码进行全面的错误处理
• 登录中： 具有可配置级别和输出的结构化日志记录

发展

设置

1. 克隆存储库：

   git clone 
   cd mcp_solana_affiliate

1. 安装依赖项：

   poetry install

1. 设置环境：

   cp .env.example .env
   # Edit .env with your configuration

运行测试

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=mcp_solana_affiliate

# Run specific test file
poetry run pytest tests/test_server.py

运行应用程序

# Development mode
poetry run python -m mcp_solana_affiliate.server

# Production mode (with gunicorn)
poetry run gunicorn -w 4 -b 0.0.0.0:5002 mcp_solana_affiliate.server:app

代码质量

# Format code
poetry run black mcp_solana_affiliate tests

# Lint code
poetry run ruff check mcp_solana_affiliate tests

# Type checking
poetry run mypy mcp_solana_affiliate

监控

健康检查

该服务提供健康检查端点：

• GET /health -总体健康状况
• GET /metrics -服务指标和统计数据

日志记录

日志输出到：

• 控制台（默认为信息级别）
• 可选日志文件（如果设置了log_file环境变量）

日志级别可以通过LOGLEVEL环境变量进行配置。

安全

• 使用Pydantic模型进行输入验证
• 跨源请求的CORS配置
• 环境变量验证
• 速率限制支持（可配置）
• 基于IP的联盟限制（可配置）

演出

缓存策略

应用程序实现了多层缓存策略：

• 联盟缓存：联盟数据的TTL为5分钟，以减少数据库读取
• 指标缓存：1分钟TTL用于度量数据
• 健康缓存：健康检查数据的30秒TTL

性能优化

• 具有内存缓存的高效JSON文件存储
• 可配置的HTTP超时和重试逻辑
• 外部请求的连接池
• 具有自动清理功能的线程安全缓存
• 用于监控瓶颈的指标收集
• 延迟加载配置

缓存管理

缓存可以通过API端点进行管理：

• 监控缓存性能： GET /cache/stats
• 清除所有缓存： POST /cache/clear
• 清理过期项目： POST /cache/cleanup

监控

性能指标通过以下方式公开：

• GET /metrics -服务使用统计
• GET /health -健康状况与依赖性检查
• GET /cache/stats -缓存性能指标

未来的考虑因素

• 数据库存储： 用更强大的数据库（PostgreSQL、MongoDB）替换JSON文件存储
• 缓存： 对频繁访问的数据实施Redis缓存
• 身份验证： 为端点添加API密钥身份验证
• 速率限制： 实施更复杂的速率限制
• 监控： 与Prometheus/Grafana集成，实现高级监控
• 缩放比例： 通过负载平衡添加对水平扩展的支持

关键文件

• affiliates.py:

- generate_affiliate_id()：使用生成唯一的联盟ID uuid.uuid4(). - load_affiliate_data()：从加载联盟数据 affiliate_data.json. - save_affiliate_data()：将联盟数据保存到 affiliate_data.json. - store_affiliate_data()：存储联盟数据。 - get_affiliate_data()：检索联盟数据。 - record_commission()：为关联公司记录佣金。

• server.py:

- mcp = FastMCP(name="Solana Affiliate Server")：初始化FastMCP服务器。 - @mcp.resource("affiliate://register")：用于注册附属公司的FastMCP资源。 - app = Flask(__name__)：初始化Flask应用程序。 - @app.route('/affiliate_buy_tokens', methods=['POST', 'OPTIONS'])：处理Blink请求、将其转发到主服务器并记录佣金的Flask端点。 - @app.route('/record_commission', methods=['POST'])：用于手动记录佣金的Flask端点（不是严格要求的，但可能有用）。

未来的考虑因素

• 数据库存储： 用更强大的数据库（例如PostgreSQL、SQLite）替换JSON文件存储。
• 错误处理： 实施更全面的错误处理和日志记录。
• 安全： 实施安全措施，如身份验证和授权，特别是对于 /record_commission 终点。
• 可扩展性： 考虑使用消息队列（例如RabbitMQ、Kafka）异步处理佣金记录，以提高可扩展性。
• 测试： 添加单元和集成测试。