Voli MCP

VOLI-MCP{用于外汇交易时段波动性分析的MCP服务器}

_MCP（模型上下文协议）服务器，提供实时外汇交易时段波动分析和交易指导。利用历史模式匹配、市场数据和经济日历整合，为外汇交易者提供可操作的见解。_

Table of Contents

• 概述
• 主要特点
• 建筑
• 安装
• 配置
• 用法
• API 参考
• 项目结构
• 数据流
• 测试
• 贡献
• 许可证

概述

VOLI-MCP（外汇交易时段波动性分析）是一个MCP服务器，旨在分析不同交易时段（亚洲、伦敦、纽约）的外汇市场波动性。它结合了：

• 实时市场数据 来自十二数据API
• 经济日历集成 提高事件意识
• 历史模式匹配 使用30-60天的数据
• 高级波动率计算 包括距离分析和压缩检测
• 信心评分 基于历史准确性
• 代理特定交易指导 针对不同的交易风格量身定制

服务器公开了一个MCP工具 analyze_forex_session 接受货币对和目标交易时段，返回包括预期偏差、置信水平、市场驱动因素、指定宏观事件和交易建议在内的全面分析。

主要特点

综合分析

• 会话检测：自动检测当前/下一交易时段
• 波动性预测：未来交易时段的预期点数偏差
• 模式识别：历史模式与相似性阈值匹配
• 压缩分析：检测到会话前范围压缩，表明潜在突破

数据集成

• 市场数据：通过Twelve data API获取实时和历史外汇数据
• 经济日历：与经济事件数据整合，以加强分析
• 多个时间范围：支持日内（5分钟）和每日数据分析

智能制导

• 信心评分：基于历史准确性的统计置信度
• 市场驱动因素：明确解释影响波动性的因素
• 代理商指导：针对不同交易方式量身定制的建议
• 波动性分类：分类波动水平（低/中/高）

开发者友好

• MCP协议：使用stdio传输的符合标准的MCP服务器
• HTTP API包装器：用于测试和集成的基于FastAPI的REST API
• 全面测试：具有模拟数据支持的完整测试套件
• 模块化架构：干净的关注点分离，便于维护

建筑

VOLI遵循模块化架构，职责明确分离：

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Server    │────│  SessionAnalyzer │────│   Data Layer    │
│   (server.py)   │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │  Analysis Layer  │    │  External APIs  │
                       │                  │    │                 │
                       └──────────────────┘    └─────────────────┘

核心组件

• MCP服务器：处理MCP协议通信和工具暴露
• 会话分析器：分析工作流的主要编排逻辑
• 数据层：十二数据API和经济日历的客户
• 分析层：范围计算、模式匹配、置信度评分
• 公用事业：会话管理、数据格式化、验证

安装

先决条件

• Python 3.10或更高版本
• 有效的Twelve Data API密钥（可用的免费层）
• 用于访问API的Internet连接

步骤1：克隆存储库

git clone https://github.com/Ash-Cyber-and-Computer-Organization/Voli-MCP.git
cd Voli-MCP

第二步：创建虚拟环境

# Create virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate  # Linux/Mac
# OR
.venv\Scripts\activate     # Windows

步骤3：安装依赖项

# Install from pyproject.toml
pip install -e .

# OR install from requirements.txt
pip install -r requirements.txt

步骤4：验证安装

# Check installed packages
pip list

# Run basic import test
python -c "from src.tools.session_analyzer import analyze_forex_session; print('Installation successful')"

配置

环境变量

创建一个 .env 项目根目录中的文件：

# Copy example file
cp .env.example .env

# Edit with your API key(s)
TWELVE_DATA_API_KEYS=your_first_key_here,your_second_key_here
TWELVE_DATA_API_KEY=your_actual_api_key_here
MAX_REQUESTS_PER_DAY=800
REQUEST_DELAY_SECONDS=1
LOG_LEVEL=INFO

速率限制

服务器包括内置的速率限制：

• 免费等级：每12个数据键每天800个请求
• 密钥池：自动旋转 TWELVE_DATA_API_KEYS 当一个密钥耗尽时
• 可配置延迟：请求之间1秒（可配置）
• 自动后退：速率限制错误的指数回退

用法

MCP服务器（生产）

运行MCP服务器以与MCP兼容客户端集成：

# Start the MCP server
python -m src.server

与Claude Desktop集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "voli-forex": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/voli-mcp",
      "env": {
        "TWELVE_DATA_API_KEYS": "your_first_key_here,your_second_key_here"
      }
    }
  }
}

HTTP API包装器（测试）

对于测试和开发，请使用FastAPI包装器：

# Start HTTP server
python api_wrapper.py

# Server runs on http://localhost:8000
# Interactive docs at http://localhost:8000/docs

MCP检查员（开发）

使用MCP检查器进行目视测试：

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Run with inspector
npx @modelcontextprotocol/inspector python -m src.server

在以下位置打开web UI http://localhost:5173 用于交互式测试。

API 参考

MCP工具： analyze_forex_session

分析外汇交易时段波动并生成交易指导。

参数

支持的配对

• 主要货币：欧元/美元、英镑/美元、美元/日元、美元/瑞士法郎、澳元/美元、加元/加元、新西兰元/美元
• 未成年人：欧元/英镑、欧元/日元、英镑/日元等。
• 选择异国情调：欧元/土耳其里拉、美元/土耳其里拉等。

响应模式

{
  "pair": "EUR/USD",
  "session": "London Session",
  "time_window_minutes": 90,
  "volatility_expectation": "Medium",
  "expected_deviation_pips": 45.2,
  "confidence": 0.78,
  "drivers": [
    "Pre-session range compressed (18.7 pips vs 30-day avg of 26.4 pips)",
    "ECB Rate Decision scheduled at 12:45 UTC (High impact)",
    "Historical data shows mixed outcomes for similar conditions (23 comparable days)"
  ],
  "historical_context": {
    "similar_conditions_occurrences": 23,
    "expansion_rate": 0.52
  },
  "macro_events": [
    {
      "name": "ECB Rate Decision",
      "event_type": "ECB",
      "currency": "EUR",
      "country": "EUR",
      "impact": "high",
      "datetime": "2026-03-18T12:45:00+00:00",
      "minutes_until": 45,
      "source": "forexfactory"
    }
  ],
  "primary_macro_event": {
    "name": "ECB Rate Decision",
    "event_type": "ECB",
    "currency": "EUR",
    "country": "EUR",
    "impact": "high",
    "datetime": "2026-03-18T12:45:00+00:00",
    "minutes_until": 45,
    "source": "forexfactory"
  },
  "agent_guidance": "Monitor for breakout above/below pre-session high/low. Consider reducing position sizes due to moderate confidence."
}

示例用法

from src.tools.session_analyzer import analyze_forex_session

# Analyze EUR/USD for next session
result = analyze_forex_session("EUR/USD", "auto")
print(result)

HTTP API终结点

运行API包装程序时：

• GET / -API信息和可用端点
• GET /docs -交互式Swagger文档
• GET /health -健康检查
• POST /analyze -分析会话（与MCP工具相同）

项目结构

voli-mcp/
├── .env                    # Environment variables (API keys)
├── .env.example           # Environment template
├── .gitignore            # Git ignore rules
├── .python-version       # Python version specification
├── README.md             # This file
├── pyproject.toml        # Project configuration
├── requirements.txt      # Dependencies
├── api_wrapper.py        # FastAPI HTTP wrapper for testing
├── PULL_REQUEST.md       # Pull request template
├── docs/                 # Documentation
│   ├── huh.md           # Additional docs
│   └── readme/
│       └── eng.md       # Detailed developer guide
├── src/                  # Source code
│   ├── __init__.py
│   ├── server.py         # MCP server implementation
│   ├── analysis/         # Analysis modules
│   │   ├── __init__.py
│   │   ├── confidence_scorer.py
│   │   ├── pattern_matcher.py
│   │   └── range_calculator.py
│   ├── data/             # Data clients
│   │   ├── __init__.py
│   │   ├── calendar_client.py
│   │   └── twelve_data_client.py
│   ├── tools/            # MCP tools
│   │   ├── __init__.py
│   │   └── session_analyzer.py
│   └── utils/            # Utilities
│       ├── __init__.py
│       ├── formatters.py
│       └── sessions.py
└── tests/                # Test suite
    ├── __init__.py
    ├── test_analysis.py
    ├── test_data_clients.py
    ├── test_full_system.py
    └── test_utils.py

数据流

graph TD
    A[User Request] --> B[MCP Server]
    B --> C[Session Analyzer]
    C --> D{Target Session?}
    D -->|Auto| E[Detect Current/Next Session]
    D -->|Manual| F[Validate Session]
    E --> G[Fetch Market Data]
    F --> G
    G --> H[Twelve Data API]
    G --> I[Economic Calendar]
    H --> J[Calculate Ranges]
    I --> J
    J --> K[Pattern Matching]
    K --> L[Confidence Scoring]
    L --> M[Generate Drivers]
    M --> N[Agent Guidance]
    N --> O[Format Response]
    O --> P[Return to User]

详细流程步骤

1. 输入验证：验证货币对和会话参数
2. 会话检测：确定目标会话（必要时自动检测）
3. 数据获取：检索日内和历史市场数据
4. 范围分析：计算会前和历史范围
5. 压缩检测：确定当前范围与平均值是否压缩
6. 模式匹配：查找类似的历史条件
7. 事件检查：查询即将发生的事件的经济日历
8. 偏差计算：预计交易时段波动
9. 信心评分：计算统计置信度
10. 驱动程序生成：解释影响分析的因素
11. 指导创建：生成交易建议
12. 响应格式：根据模式构建输出

测试

VOLI包括一个涵盖所有组件的全面测试套件：

运行测试

# Run all tests
python -m pytest tests/

# Run specific test modules
python tests/test_utils.py
python tests/test_data_clients.py
python tests/test_analysis.py
python tests/test_full_system.py

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

测试类别

• 单元测试：单个组件测试
• 集成测试：全系统工作流程测试
• API测试：数据客户端可靠性测试
• 模拟测试：没有外部API依赖项的测试

测试数据

测试使用以下组合：

• 真实的API数据（需要有效的API密钥）
• 离线测试的模拟数据
• 历史测试场景

开发设置

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/your-feature
3. 设置开发环境（请参阅安装）
4. 进行更改
5. 运行测试： python -m pytest tests/
6. 提交更改： git commit -am 'Add your feature'
7. 推送到分支： git push origin feature/your-feature
8. 创建拉取请求

代码规范

• 遵循PEP 8风格指南
• 为函数参数和返回值添加类型提示
• 编写全面的文档字符串
• 为新功能添加单元测试
• 根据需要更新文档

致谢

• ctxprotocol 协议

支持

• 问题:

• 文档：参见 docs/ 详细指南目录

______________________________________________________________________