emerald-exchange 0.10.0__tar.gz

emerald_exchange-0.10.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knuckles Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emerald_exchange-0.10.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: emerald-exchange
+Version: 0.10.0
+Summary: Emerald Exchange — Unified Finance MCP Server with fully abstracted exchange backends for equities, crypto, and derivatives trading. CONCEPT:EE-001
+Author-email: Audel Rouhi <knucklessg1@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-utilities[mcp]>=0.34.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Provides-Extra: alpaca
+Requires-Dist: alpaca-py>=0.30.0; extra == "alpaca"
+Provides-Extra: binance
+Requires-Dist: python-binance>=1.0.0; extra == "binance"
+Provides-Extra: crypto
+Requires-Dist: ccxt>=4.0.0; extra == "crypto"
+Provides-Extra: prediction-markets
+Requires-Dist: httpx>=0.24.0; extra == "prediction-markets"
+Requires-Dist: kalshi-python; extra == "prediction-markets"
+Requires-Dist: py-clob-client; extra == "prediction-markets"
+Provides-Extra: all
+Requires-Dist: agent-utilities[agent,logfire,mcp]>=0.34.0; extra == "all"
+Requires-Dist: alpaca-py>=0.30.0; extra == "all"
+Requires-Dist: ccxt>=4.0.0; extra == "all"
+Requires-Dist: httpx>=0.24.0; extra == "all"
+Requires-Dist: kalshi-python; extra == "all"
+Requires-Dist: py-clob-client; extra == "all"
+Provides-Extra: agent
+Requires-Dist: agent-utilities[agent,logfire]>=0.34.0; extra == "agent"
+Dynamic: license-file
+
+# Emerald Exchange - API | MCP | A2A
+
+![PyPI - Version](https://img.shields.io/pypi/v/emerald-exchange)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+
+*Version: 0.10.0*
+
+## Overview
+
+Emerald Exchange is a unified Finance MCP Server providing fully abstracted exchange backends
+for equities, crypto, and derivatives trading. All trading functionality is tool-driven via MCP,
+with built-in financial hardening controls (OS-5.1).
+
+**Key Features:**
+- **5 Exchange Backends**: Paper (default), Alpaca (FREE), CCXT (100+ exchanges), Freqtrade
+- **6 MCP Tool Domains**: market-data, orders, portfolio, risk, signals, strategy
+- **Financial Hardening**: Paper-first default, Kelly criterion position sizing, circuit breakers, kill switch
+- **Config-Driven**: All settings via `~/.config/agent-utilities/config.json`
+
+## Architecture
+
+```mermaid
+flowchart TB
+    A["Agent / IDE"] --> B["emerald-exchange MCP"]
+    B --> C["Risk Guard (OS-5.1)"]
+    C --> D{"Exchange Router"}
+    D --> E["Paper Backend (Default)"]
+    D --> F["Alpaca Backend (FREE)"]
+    D --> G["CCXT Backend (Binance/Coinbase/Kraken)"]
+    D --> H["Freqtrade Backend"]
+
+    style B fill:#10B981,stroke:#065F46,color:#fff
+    style C fill:#EF4444,stroke:#991B1B,color:#fff
+    style E fill:#6366F1,stroke:#4338CA,color:#fff
+```
+
+## MCP Tools
+
+| Domain | Tool Name | Actions | Tag |
+|--------|-----------|---------|-----|
+| Market Data | `emerald_market_data` | quote, historical, exchanges | market-data |
+| Orders | `emerald_orders` | submit, cancel, status, halt, resume | orders |
+| Portfolio | `emerald_portfolio` | positions, account | portfolio |
+| Prediction Markets | `emerald_prediction_markets` | kalshi_events, polymarket_events, open_meteo_ensemble | prediction-markets |
+| Risk | `emerald_risk` | status, drawdown_check, daily_loss_check, kelly, limits | risk |
+| Signals | `emerald_signals` | regime, alpha, fuse | signals |
+| Strategy | `emerald_strategy` | list, promote, export | strategy |
+
+## Exchange Backends
+
+| Backend | Assets | Paper | Live | Free |
+|---------|--------|-------|------|------|
+| Paper | All | ✅ | — | ✅ |
+| Alpaca | Equities, Crypto | ✅ | ✅ | ✅ |
+| CCXT (Binance) | Crypto | ✅ | ✅ | ✅ |
+| CCXT (Coinbase) | Crypto | ✅ | ✅ | ✅ |
+| CCXT (Kraken) | Crypto | ✅ | ✅ | ✅ |
+| Freqtrade | Crypto | ✅ | ✅ | ✅ |
+| Prediction Markets (Kalshi/Polymarket) | Events/Weather | ✅ | ✅ | ✅ |
+
+## Financial Hardening (OS-5.1)
+
+| Control | Default |
+|---------|---------|
+| Trading Mode | Paper (must explicitly opt into live) |
+| Max Position Size | 2% of portfolio (Kelly criterion) |
+| Max Portfolio Drawdown | 10% auto-halt |
+| Max Daily Loss | 3% auto-halt |
+| Regime Shift Detection | KS-test auto-halt |
+| Human Approval for Live | Required |
+| Kill Switch | `emerald_orders(action="halt")` |
+
+## Usage
+
+### MCP Configuration
+
+#### stdio Mode
+```json
+{
+  "mcpServers": {
+    "emerald-exchange": {
+      "command": "uv",
+      "args": ["run", "--with", "emerald-exchange", "emerald-exchange"],
+      "env": {}
+    }
+  }
+}
+```
+
+#### Streamable HTTP Mode
+```bash
+emerald-exchange --transport streamable-http --port 8100
+```
+
+### Configuration
+
+All trading settings are configured via `~/.config/agent-utilities/config.json`:
+
+```json
+{
+  "trading": {
+    "default_mode": "paper",
+    "default_exchange": "alpaca",
+    "exchanges": {
+      "alpaca": {
+        "enabled": true,
+        "api_key_env": "ALPACA_API_KEY",
+        "api_secret_env": "ALPACA_SECRET_KEY",
+        "base_url": "https://paper-api.alpaca.markets"
+      }
+    },
+    "risk_limits": {
+      "max_position_pct": 0.02,
+      "max_portfolio_drawdown_pct": 0.10,
+      "max_daily_loss_pct": 0.03,
+      "require_human_approval_live": true
+    }
+  }
+}
+```
+
+## ⚙️ Dynamic Tool Selection & Visibility
+
+This MCP server supports dynamic toolset selection and visibility filtering at runtime. This allows you to restrict the set of exposed tools in order to prevent blowing up the LLM's context window.
+
+You can configure tool filtering via multiple input channels:
+
+- **CLI Arguments:** Pass `--tools` or `--toolsets` (or their disabled counterparts `--disabled-tools` and `--disabled-toolsets`) during startup.
+- **Environment Variables:** Define standard environment variables:
+  - `MCP_ENABLED_TOOLS` / `MCP_DISABLED_TOOLS`
+  - `MCP_ENABLED_TAGS` / `MCP_DISABLED_TAGS`
+- **HTTP SSE Request Headers:** Pass custom headers during transport initialization:
+  - `x-mcp-enabled-tools` / `x-mcp-disabled-tools`
+  - `x-mcp-enabled-tags` / `x-mcp-disabled-tags`
+- **HTTP SSE Request Query Parameters:** Append query parameters directly to your transport connection URL:
+  - `?tools=tool1,tool2`
+  - `?tags=tag1`
+
+When query strings or parameters are supplied, an LLM-free **Knowledge Graph resolution layer** (using `DynamicToolOrchestrator`) matches query intents against known tool tags, names, or descriptions, with safe fallback and automated 24-hour background cache refreshing.
+
+
+---
+
+## Installation
+
+```bash
+pip install emerald-exchange           # Core + paper backend
+pip install emerald-exchange[alpaca]   # + Alpaca equities
+pip install emerald-exchange[crypto]   # + CCXT crypto
+pip install emerald-exchange[prediction_markets] # + Kalshi & Polymarket
+pip install emerald-exchange[all]      # Everything
+```
+
+## Docker
+
+```bash
+docker compose -f docker/compose.yml up -d
+```

emerald_exchange-0.10.0/README.md

@@ -0,0 +1,158 @@
+# Emerald Exchange - API | MCP | A2A
+
+![PyPI - Version](https://img.shields.io/pypi/v/emerald-exchange)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+
+*Version: 0.10.0*
+
+## Overview
+
+Emerald Exchange is a unified Finance MCP Server providing fully abstracted exchange backends
+for equities, crypto, and derivatives trading. All trading functionality is tool-driven via MCP,
+with built-in financial hardening controls (OS-5.1).
+
+**Key Features:**
+- **5 Exchange Backends**: Paper (default), Alpaca (FREE), CCXT (100+ exchanges), Freqtrade
+- **6 MCP Tool Domains**: market-data, orders, portfolio, risk, signals, strategy
+- **Financial Hardening**: Paper-first default, Kelly criterion position sizing, circuit breakers, kill switch
+- **Config-Driven**: All settings via `~/.config/agent-utilities/config.json`
+
+## Architecture
+
+```mermaid
+flowchart TB
+    A["Agent / IDE"] --> B["emerald-exchange MCP"]
+    B --> C["Risk Guard (OS-5.1)"]
+    C --> D{"Exchange Router"}
+    D --> E["Paper Backend (Default)"]
+    D --> F["Alpaca Backend (FREE)"]
+    D --> G["CCXT Backend (Binance/Coinbase/Kraken)"]
+    D --> H["Freqtrade Backend"]
+
+    style B fill:#10B981,stroke:#065F46,color:#fff
+    style C fill:#EF4444,stroke:#991B1B,color:#fff
+    style E fill:#6366F1,stroke:#4338CA,color:#fff
+```
+
+## MCP Tools
+
+| Domain | Tool Name | Actions | Tag |
+|--------|-----------|---------|-----|
+| Market Data | `emerald_market_data` | quote, historical, exchanges | market-data |
+| Orders | `emerald_orders` | submit, cancel, status, halt, resume | orders |
+| Portfolio | `emerald_portfolio` | positions, account | portfolio |
+| Prediction Markets | `emerald_prediction_markets` | kalshi_events, polymarket_events, open_meteo_ensemble | prediction-markets |
+| Risk | `emerald_risk` | status, drawdown_check, daily_loss_check, kelly, limits | risk |
+| Signals | `emerald_signals` | regime, alpha, fuse | signals |
+| Strategy | `emerald_strategy` | list, promote, export | strategy |
+
+## Exchange Backends
+
+| Backend | Assets | Paper | Live | Free |
+|---------|--------|-------|------|------|
+| Paper | All | ✅ | — | ✅ |
+| Alpaca | Equities, Crypto | ✅ | ✅ | ✅ |
+| CCXT (Binance) | Crypto | ✅ | ✅ | ✅ |
+| CCXT (Coinbase) | Crypto | ✅ | ✅ | ✅ |
+| CCXT (Kraken) | Crypto | ✅ | ✅ | ✅ |
+| Freqtrade | Crypto | ✅ | ✅ | ✅ |
+| Prediction Markets (Kalshi/Polymarket) | Events/Weather | ✅ | ✅ | ✅ |
+
+## Financial Hardening (OS-5.1)
+
+| Control | Default |
+|---------|---------|
+| Trading Mode | Paper (must explicitly opt into live) |
+| Max Position Size | 2% of portfolio (Kelly criterion) |
+| Max Portfolio Drawdown | 10% auto-halt |
+| Max Daily Loss | 3% auto-halt |
+| Regime Shift Detection | KS-test auto-halt |
+| Human Approval for Live | Required |
+| Kill Switch | `emerald_orders(action="halt")` |
+
+## Usage
+
+### MCP Configuration
+
+#### stdio Mode
+```json
+{
+  "mcpServers": {
+    "emerald-exchange": {
+      "command": "uv",
+      "args": ["run", "--with", "emerald-exchange", "emerald-exchange"],
+      "env": {}
+    }
+  }
+}
+```
+
+#### Streamable HTTP Mode
+```bash
+emerald-exchange --transport streamable-http --port 8100
+```
+
+### Configuration
+
+All trading settings are configured via `~/.config/agent-utilities/config.json`:
+
+```json
+{
+  "trading": {
+    "default_mode": "paper",
+    "default_exchange": "alpaca",
+    "exchanges": {
+      "alpaca": {
+        "enabled": true,
+        "api_key_env": "ALPACA_API_KEY",
+        "api_secret_env": "ALPACA_SECRET_KEY",
+        "base_url": "https://paper-api.alpaca.markets"
+      }
+    },
+    "risk_limits": {
+      "max_position_pct": 0.02,
+      "max_portfolio_drawdown_pct": 0.10,
+      "max_daily_loss_pct": 0.03,
+      "require_human_approval_live": true
+    }
+  }
+}
+```
+
+## ⚙️ Dynamic Tool Selection & Visibility
+
+This MCP server supports dynamic toolset selection and visibility filtering at runtime. This allows you to restrict the set of exposed tools in order to prevent blowing up the LLM's context window.
+
+You can configure tool filtering via multiple input channels:
+
+- **CLI Arguments:** Pass `--tools` or `--toolsets` (or their disabled counterparts `--disabled-tools` and `--disabled-toolsets`) during startup.
+- **Environment Variables:** Define standard environment variables:
+  - `MCP_ENABLED_TOOLS` / `MCP_DISABLED_TOOLS`
+  - `MCP_ENABLED_TAGS` / `MCP_DISABLED_TAGS`
+- **HTTP SSE Request Headers:** Pass custom headers during transport initialization:
+  - `x-mcp-enabled-tools` / `x-mcp-disabled-tools`
+  - `x-mcp-enabled-tags` / `x-mcp-disabled-tags`
+- **HTTP SSE Request Query Parameters:** Append query parameters directly to your transport connection URL:
+  - `?tools=tool1,tool2`
+  - `?tags=tag1`
+
+When query strings or parameters are supplied, an LLM-free **Knowledge Graph resolution layer** (using `DynamicToolOrchestrator`) matches query intents against known tool tags, names, or descriptions, with safe fallback and automated 24-hour background cache refreshing.
+
+
+---
+
+## Installation
+
+```bash
+pip install emerald-exchange           # Core + paper backend
+pip install emerald-exchange[alpaca]   # + Alpaca equities
+pip install emerald-exchange[crypto]   # + CCXT crypto
+pip install emerald-exchange[prediction_markets] # + Kalshi & Polymarket
+pip install emerald-exchange[all]      # Everything
+```
+
+## Docker
+
+```bash
+docker compose -f docker/compose.yml up -d
+```

emerald_exchange-0.10.0/emerald_exchange/__init__.py

@@ -0,0 +1,9 @@
+"""Emerald Exchange — Unified Finance MCP Server.
+
+CONCEPT:EE-001 — Emerald Exchange Core
+
+Provides fully abstracted exchange backends for equities, crypto, and
+derivatives trading. All functionality is tool-driven via MCP.
+"""
+
+__version__ = "0.10.0"

emerald_exchange-0.10.0/emerald_exchange/__main__.py

@@ -0,0 +1,7 @@
+"""Emerald Exchange entry point."""
+
+from emerald_exchange.mcp_server import mcp_server
+
+if __name__ == "__main__":
+    server = mcp_server()
+    server.run(transport="stdio")

emerald_exchange-0.10.0/emerald_exchange/agent_server.py

@@ -0,0 +1,94 @@
+#!/usr/bin/python
+# coding: utf-8
+"""Emerald Exchange A2A Agent Server — CONCEPT:EE-017.
+
+Launches the Emerald Exchange as a full Pydantic AI agent with A2A
+(Agent-to-Agent) communication support, backed by the MCP toolset.
+"""
+
+import os
+import sys
+import logging
+import warnings
+
+
+__version__ = "0.1.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+# Load identity and system prompt from workspace
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "Emerald Exchange")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get(
+            "description",
+            "Emerald Exchange — Unified Finance MCP with multi-exchange backend abstraction, "
+            "risk guards, and KG-native trading workflows. CONCEPT:EE-001",
+        ),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    # Start server using the auto-discovery pattern (from mcp_config.json)
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()