MCP交易服务器

{
  "status": "error",
  "message": "Human-readable error description",
  "error_type": "ExceptionType",
  "metadata": {"context": "additional_info"}
}

# Clone and setup
git clone <repository>
cd alpaca-mcp-gold-standard

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your Alpaca API credentials

# Development mode
uv run python main.py

# Debug mode with verbose logging
LOG_LEVEL=DEBUG uv run python main.py

# Production mode with Docker
docker build -t alpaca-mcp-gold .
docker run -p 8000:8000 --env-file .env alpaca-mcp-gold

# Run all tests with coverage
uv run pytest tests/ -v --cov=src --cov-report=term-missing

# Test specific gold standard patterns
uv run pytest tests/test_resource_mirrors.py -v  # Resource mirror pattern
uv run pytest tests/test_state_management.py -v  # State management
uv run pytest tests/test_integration.py -v        # Full workflows

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

src/mcp_server/
├── config/                     # Environment-based configuration
│   ├── settings.py            # Pydantic settings management
│   └── simple_settings.py     # Simplified config loader
├── models/                    # Core business logic
│   ├── schemas.py            # Entity classification & state management
│   └── alpaca_clients.py     # Singleton API client management
├── tools/                     # 31 MCP tools by category
│   ├── account_tools.py               # Account operations
│   ├── market_data_tools.py           # Market data access
│   ├── order_management_tools.py      # Trading operations
│   ├── custom_strategy_execution.py   # Safe code execution
│   ├── advanced_analysis_tools.py     # Portfolio analytics
│   ├── execute_custom_analytics_code_tool.py  # Universal analytics
│   └── resource_mirror_tools.py       # Compatibility layer
├── resources/                 # URI-based data access
│   └── trading_resources.py  # trading:// scheme handlers
├── prompts/                   # Context-aware conversations
│   └── trading_prompts.py    # 4 adaptive prompt generators
└── server.py                  # FastMCP registration (31 tools)

tests/
├── conftest.py                # Mock Alpaca API & fixtures
├── test_account_tools.py      # Account operation tests
├── test_market_data_tools.py  # Market data tests
├── test_order_management_tools.py  # Order operation tests
├── test_resources.py          # Resource URI tests
├── test_resource_mirrors.py   # Mirror consistency validation
├── test_state_management.py   # Memory & state tests
└── test_integration.py        # Complete workflow tests

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

# Automatic cleanup and tracking
StateManager.add_symbol("AAPL", entity_info)
memory_usage = StateManager.get_memory_usage()  # Returns MB used
StateManager.clear_all()  # Clean slate

# Safe execution with timeout
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)

# Context-aware suggestions based on actual holdings
"Your portfolio shows high concentration in tech stocks (65%). 
Consider diversifying with healthcare or consumer staples for 
better risk balance. Use get_stock_snapshot('JNJ,PG,KO') to 
research defensive positions."

# Format code
uv run black src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type checking
uv run mypy src/

# Run all quality checks
uv run black src/ tests/ && uv run ruff check src/ tests/ && uv run mypy src/

# Build production image
docker build -t alpaca-mcp-gold .

# Run with environment file
docker run -d \
  --name alpaca-mcp \
  -p 8000:8000 \
  --env-file .env \
  --restart unless-stopped \
  alpaca-mcp-gold

# Required
ALPACA_API_KEY=your_api_key
ALPACA_SECRET_KEY=your_secret_key

# Optional
ALPACA_PAPER_TRADE=True  # Use paper trading (recommended)
LOG_LEVEL=INFO          # Logging verbosity
MCP_SERVER_NAME=alpaca-trading-gold