骆驼-MCP-金版

Name: 骆驼-MCP-金版
Author: JOravetz

作者：JOravetz2 星标更新：2025-06-30

安装使用来源：spider==github.com

项目介绍

Alpaca MCP 金标准

这是一个全面实现专业交易操作的最终MCP（模型上下文协议）服务器架构，完全符合Quick Data MCP参考架构中记录的金标准模式。

🏆 什么使其成为金标准？

此实现代表了专业MCP开发的权威参考，实现了所有7个核心架构模式，并提供了涵盖交易操作、高级分析和通用数据分析能力的50多种工具。

📊 实现指标

31个MCP工具：全面覆盖交易操作
11个资源镜像：通用客户端兼容性
4个上下文提示：智能对话引导
7/7架构模式：100%符合金标准
超过50种功能：全面的交易平台
91次真实API测试：实际Alpaca API集成的通过率为100%

🎯 金标准架构模式

1. 自适应发现 ✅

自动分类股票和仓位，并进行智能角色分配：

增长候选：具有正动量指标的股票
波动资产：需要主动监控的高波动性仓位
收入生成器：分红或稳定回报的仓位
对冲工具：风险管理及投资组合保护资产
投机机会：高风险高回报的机会

2. 资源镜像模式 ✅

与任何MCP客户端通用兼容：

11个镜像工具提供与资源相同的功能
通过函数包装实现零维护开销
工具仅客户端的无缝回退
面向未来的迁移路径

3. 上下文感知提示 ✅

引用您实际投资组合的对话启动器：

portfolio_first_look - 分析您的具体持仓
trading_strategy_workshop - 根据您的投资组合组成定制
market_analysis_session - 关注您跟踪的符号
list_mcp_capabilities - 完整的功能指南

4. 安全自定义代码执行 ✅

在子进程隔离下执行自定义分析：

交易策略：在投资组合上下文中运行自定义算法
投资组合优化：带有风险参数的高级优化
风险分析：自定义风险度量和计算
通用分析：适用于任何数据集结构
带有全面错误处理的30秒超时保护

5. 高级分析工具 ✅

复杂的投资组合智能：

投资组合健康评估：100分评分系统
- 多样化分析
- 风险集中度指标
- 绩效平衡评估
- 具体工具的操作建议
市场相关性分析：30天相关矩阵
- 识别过度相关的仓位
- 多样化评分
- 风险见解和建议

6. 通用数据集无差别 ✅

超越交易——适用于任何结构化数据：

自动发现列类型和关系
通用的相关性和分割工具
适应性可视化能力
跨数据集集成模式

7. 一致的错误处理 ✅

专业级错误管理：

{
  "status": "error",
  "message": "人类可读的错误描述",
  "error_type": "异常类型",
  "metadata": {"context": "附加信息"}
}

🚀 快速开始

先决条件

Python 3.12+
uv 包管理器
Alpaca 交易账户（支持模拟交易）

安装

# 克隆并设置
git clone <仓库>
cd alpaca-mcp-gold-standard

# 安装依赖
uv sync

# 配置环境
cp .env.example .env
# 使用您的Alpaca API凭证编辑.env

运行服务器

# 开发模式
uv run python main.py

# 带详细日志的调试模式
LOG_LEVEL=DEBUG uv run python main.py

# 生产模式使用Docker
docker build -t alpaca-mcp-gold .
docker run -p 8000:8000 --env-file .env alpaca-mcp-gold

测试

# 运行所有测试并生成覆盖率报告
uv run pytest tests/ -v --cov=src --cov-report=term-missing

# 测试特定的金标准模式
uv run pytest tests/test_resource_mirrors.py -v  # 资源镜像模式
uv run pytest tests/test_state_management.py -v  # 状态管理
uv run pytest tests/test_integration.py -v        # 完整工作流

📋 MCP客户端配置

对于Claude桌面

添加到您的Claude配置：

{
  "mcpServers": {
    "alpaca-trading-gold": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/绝对路径/to/alpaca-mcp-gold-standard",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

🛠️ 完整工具目录

账户与投资组合管理（4个工具）

get_account_info_tool() - 实时账户状态及投资组合洞察
get_positions_tool() - 持仓及自适应角色分类
get_open_position_tool(symbol) - 特定仓位详情
get_portfolio_summary_tool() - 全面分析及AI建议

市场数据与研究（4个工具）

get_stock_quote_tool(symbol) - 实时报价及价差分析
get_stock_trade_tool(symbol) - 最新交易信息
get_stock_snapshot_tool(symbols) - 完整市场数据及波动性
get_historical_bars_tool(symbol, timeframe) - 历史OHLCV数据

订单管理（5个工具）

place_market_order_tool(symbol, side, quantity) - 即时执行
place_limit_order_tool(symbol, side, quantity, price) - 价格目标
place_stop_loss_order_tool(symbol, side, quantity, stop_price) - 风险管理
get_orders_tool(status, limit) - 订单历史及追踪
cancel_order_tool(order_id) - 订单取消

自定义策略执行（3个工具）

execute_custom_trading_strategy_tool(code, symbols) - 运行自定义算法
execute_portfolio_optimization_strategy_tool(code, risk_tolerance) - 优化持仓
execute_risk_analysis_strategy_tool(code, benchmarks) - 风险分析

高级分析（2个工具）

generate_portfolio_health_assessment_tool() - 100分健康评分
generate_advanced_market_correlation_analysis_tool(symbols) - 相关矩阵

通用分析（2个工具）

execute_custom_analytics_code_tool(dataset, code) - 任意数据集分析
create_sample_dataset_from_portfolio_tool() - 将投资组合转换为数据集

资源镜像（11个工具）

每个资源都有一个对应的工具以确保通用兼容性：

resource_account_info_tool() → trading://account/info
resource_portfolio_summary_tool() → trading://portfolio/summary
及其他9个镜像工具...

实用工具（1个工具）

clear_portfolio_state_tool() - 重置状态用于测试

🏗️ 架构概述

src/mcp_server/
├── config/                     # 基于环境的配置
│   ├── settings.py            # Pydantic设置管理
│   └── simple_settings.py     # 简化的配置加载器
├── models/                    # 核心业务逻辑
│   ├── schemas.py            # 实体分类及状态管理
│   └── alpaca_clients.py     # 单例API客户端管理
├── tools/                     # 按类别划分的31个MCP工具
│   ├── account_tools.py               # 账户操作
│   ├── market_data_tools.py           # 市场数据访问
│   ├── order_management_tools.py      # 交易操作
│   ├── custom_strategy_execution.py   # 安全代码执行
│   ├── advanced_analysis_tools.py     # 投资组合分析
│   ├── execute_custom_analytics_code_tool.py  # 通用分析
│   └── resource_mirror_tools.py       # 兼容层
├── resources/                 # 基于URI的数据访问
│   └── trading_resources.py  # trading://方案处理器
├── prompts/                   # 上下文感知对话
│   └── trading_prompts.py    # 4个自适应提示生成器
└── server.py                  # FastMCP注册（31个工具）

🧪 测试卓越

综合测试套件

tests/
├── conftest.py                # 模拟Alpaca API及固定装置
├── test_account_tools.py      # 账户操作测试
├── test_market_data_tools.py  # 市场数据测试
├── test_order_management_tools.py  # 订单操作测试
├── test_resources.py          # 资源URI测试
├── test_resource_mirrors.py   # 镜像一致性验证
├── test_state_management.py   # 内存及状态测试
└── test_integration.py        # 完整工作流测试

测试固定装置提供

测试间自动状态清理
带有现实响应的模拟Alpaca API
响应验证的帮助函数
内存使用跟踪

💡 关键创新

1. 实体角色分类

每个股票/仓位都被智能分类：

entity = EntityInfo(
    symbol="AAPL",
    suggested_role=EntityRole.GROWTH_CANDIDATE,
    characteristics=["high_momentum", "tech_sector", "large_cap"],
    confidence_score=0.85
)

2. 内存高效的状态管理

# 自动清理和跟踪
StateManager.add_symbol("AAPL", entity_info)
memory_usage = StateManager.get_memory_usage()  # 返回已使用的MB数
StateManager.clear_all()  # 清空

3. 子进程隔离模式

# 带超时的安全执行
async def execute_custom_code(code: str) -> str:
    process = await asyncio.create_subprocess_exec(
        'uv', 'run', '--with', 'pandas', '--with', 'numpy',
        'python', '-c', execution_code,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.STDOUT
    )
    stdout, _ = await asyncio.wait_for(process.communicate(), timeout=30)

4. 自适应投资组合洞察

# 基于实际持仓的上下文感知建议
"您的投资组合显示科技股高度集中（65%）。考虑通过医疗保健或消费品来分散风险，以获得更好的风险平衡。使用get_stock_snapshot('JNJ,PG,KO')来研究防御性位置。"

📊 性能与监控

响应时间：数据操作平均<100毫秒
内存使用：闲置约50MB，满载投资组合约200MB
子进程超时：自定义代码的30秒保护
健康监控：持续的Alpaca API连接检查
状态跟踪：实时内存使用监控

🔧 开发指南

添加新工具

在适当的tools/category_tools.py中创建函数

遵循标准响应格式：

async def your_new_tool(param: str) -> Dict[str, Any]:
    try:
        # 实现
        return {
            "status": "success",
            "data": result_data,
            "metadata": {"operation": "your_new_tool"}
        }
    except Exception as e:
        return {
            "status": "error",
            "message": str(e),
            "error_type": type(e).__name__
        }

在server.py中使用@mcp.tool()装饰器注册
添加全面测试
更新文档

代码质量标准

# 格式化代码
uv run black src/ tests/

# 代码检查
uv run ruff check src/ tests/

# 类型检查
uv run mypy src/

# 运行所有质量检查
uv run black src/ tests/ && uv run ruff check src/ tests/ && uv run mypy src/

🔒 安全最佳实践

凭据管理：仅使用环境变量
输入验证：所有输入使用Pydantic模型
错误净化：错误消息中不包含凭据
子进程隔离：不受信任的代码在沙箱中运行
API速率限制：内置的Alpaca速率限制处理

📚 文档结构

README.md：本综合指南
CLAUDE.md：Claude代码开发指导
ai_docs/：AI优化的参考资料
- alpaca_py_sdk_reference.md - Alpaca SDK指南
- mcp_server_sdk_reference.md - MCP模式指南
specs/：架构规范
- architecture_overview.md - 金标准模式
- custom_analytic_code.md - 子进程设计
- poc_init_generic.md - 通用模式
- resource_workaround.md - 镜像模式
.claude/commands/：开发工作流程
- 并行实现模式
- 验证框架

🚢 生产部署

Docker部署

# 构建生产镜像
docker build -t alpaca-mcp-gold .

# 使用环境文件运行
docker run -d \
  --name alpaca-mcp \
  -p 8000:8000 \
  --env-file .env \
  --restart unless-stopped \
  alpaca-mcp-gold

环境变量

# 必需
ALPACA_API_KEY=your_api_key
ALPACA_SECRET_KEY=your_secret_key

# 可选
ALPACA_PAPER_TRADE=True  # 使用模拟交易（推荐）
LOG_LEVEL=INFO          # 日志详细程度
MCP_SERVER_NAME=alpaca-trading-gold

🤝 贡献

该项目作为MCP开发的金标准参考。当贡献时：

遵循架构模式：保持所有7个金标准模式
全面测试：新代码至少80%覆盖率
文档：更新相关文档以反映新功能
一致性：匹配现有代码风格和模式
审查清单：
- 测试通过且覆盖率达标
- 如需更新资源镜像
- 错误处理遵循标准格式
- 文档更新
- 包含类型提示

🌟 为什么这个实现重要

这不仅仅是另一个MCP服务器——它是软件架构的大师课：

参考实现：展示了每一个MCP最佳实践
生产就绪：全面的错误处理、监控和测试
通用模式：适用于任何领域的技术
教育价值：学习专业的MCP开发模式
可扩展基础：易于适应其他用例

📈 未来增强

架构设计为扩展：

实时WebSocket市场数据流
高级投资组合优化算法
多账户管理支持
交易策略回测框架
与其他经纪商的集成
基于机器学习的洞察

📄 许可

本项目根据原始Alpaca MCP服务器的相同条款许可。

🙏 致谢

基于原始Alpaca MCP服务器的基础，实现了父存储库分析中记录的全面最佳实践。特别感谢MCP和Alpaca社区提供的优秀文档和工具。

这是专业MCP开发的权威参考实现。 不论您是在构建交易系统、数据分析平台还是任何其他MCP驱动的应用程序，这个代码库都展示了引领生产就绪、可维护和可扩展系统的模式和实践。