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

# Clone and setup
git clone 
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."

3. Register in `server.py` with `@mcp.tool()` decorator
4. Add comprehensive tests
5. Update documentation

### Code Quality Standards

## 🔒 Security Best Practices

- **Credential Management**: Environment variables only
- **Input Validation**: Pydantic models for all inputs
- **Error Sanitization**: No credentials in error messages
- **Subprocess Isolation**: Untrusted code runs in sandbox
- **API Rate Limiting**: Built-in Alpaca rate limit handling

## 📚 Documentation Structure

- **README.md**: This comprehensive guide
- **CLAUDE.md**: Guidance for Claude Code development
- **ai_docs/**: AI-optimized references
  - `alpaca_py_sdk_reference.md` - Alpaca SDK guide
  - `mcp_server_sdk_reference.md` - MCP patterns guide
- **specs/**: Architectural specifications
  - `architecture_overview.md` - Gold standard patterns
  - `custom_analytic_code.md` - Subprocess design
  - `poc_init_generic.md` - Universal patterns
  - `resource_workaround.md` - Mirror pattern
- **.claude/commands/**: Development workflows
  - Parallel implementation patterns
  - Validation frameworks

## 🚢 Production Deployment

### Docker Deployment

### Environment Variables

## 🤝 Contributing

This project serves as the gold standard reference for MCP development. When contributing:

1. **Follow Architecture Patterns**: Maintain all 7 gold standard patterns
2. **Comprehensive Testing**: Minimum 80% coverage for new code
3. **Documentation**: Update relevant docs for new features
4. **Consistency**: Match existing code style and patterns
5. **Review Checklist**:
   - [ ] Tests pass with coverage
   - [ ] Resource mirrors updated if needed
   - [ ] Error handling follows standard format
   - [ ] Documentation updated
   - [ ] Type hints included

## 🌟 Why This Implementation Matters

This is not just another MCP server - it's a **masterclass in software architecture**:

1. **Reference Implementation**: Demonstrates every MCP best practice
2. **Production Ready**: Comprehensive error handling, monitoring, and testing
3. **Universal Patterns**: Techniques applicable to ANY domain
4. **Educational Value**: Learn professional MCP development patterns
5. **Extensible Foundation**: Easy to adapt for other use cases

## 📈 Future Enhancements

The architecture is designed for expansion:
- Real-time WebSocket market data streaming
- Advanced portfolio optimization algorithms
- Multi-account management support
- Trading strategy backtesting framework
- Integration with additional brokers
- Machine learning-powered insights

## 📄 License

This project is licensed under the same terms as the original Alpaca MCP server.

## 🙏 Acknowledgments

Built upon the foundation of the original Alpaca MCP server, implementing the comprehensive best practices documented in the parent repository's analysis of gold standard MCP patterns. Special thanks to the MCP and Alpaca communities for their excellent documentation and tools.

---

**This is the definitive reference implementation for professional MCP development.** Whether you're building trading systems, data analytics platforms, or any other MCP-powered application, this codebase demonstrates the patterns and practices that lead to production-ready, maintainable, and extensible systems.