smartoption-mcp 0.1.1__tar.gz

smartoption_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: smartoption-mcp
+Version: 0.1.1
+Summary: MCP server exposing the smartoption-ai customer auto-trade API as tools for AI agents (Claude Desktop / Claude Code / any MCP client).
+Author-email: SmartOption <service.smartoption@gmail.com>
+License: Proprietary
+Project-URL: Homepage, https://github.com/SmartOption/smartoption-ai
+Project-URL: Repository, https://github.com/SmartOption/smartoption-ai
+Project-URL: Issues, https://github.com/SmartOption/smartoption-ai/issues
+Keywords: mcp,smartoption,claude,auto-trade,copy-trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: httpx>=0.27.0
+
+# smartoption-mcp
+
+MCP server that exposes the smartoption-ai **customer auto-trade API** as tools
+for AI agents (Claude Desktop, Claude Code, anything that speaks MCP).
+
+Phase 1 is **read-only**: 5 tools covering copy rules, virtual lots, agent
+status, parsed signal history (大单/喊单历史), and copy-run logs. Write
+operations (creating/modifying rules, placing orders) will be added in
+Phase 2 once the read path is battle-tested.
+
+## Architecture
+
+```
+Claude / Agent
+   │  MCP stdio
+   ▼
+smartoption-mcp  ──HTTP + Bearer JWT──▶  backend  /api/customer/auto-trade/*
+```
+
+The server is a thin wrapper: each tool maps 1:1 (or close) to a customer
+API endpoint, authenticated with a user JWT loaded from env at startup.
+
+## Install
+
+### End-user (recommended)
+
+```bash
+pip install smartoption-mcp
+# or, in an isolated venv:
+python3.11 -m venv ~/.smartoption-mcp && ~/.smartoption-mcp/bin/pip install smartoption-mcp
+```
+
+`smartoption-mcp` is published on [PyPI](https://pypi.org/project/smartoption-mcp/).
+This installs the `smartoption-mcp` CLI entry point. Upgrade with
+`pip install -U smartoption-mcp`.
+
+### Local dev (from this repo)
+
+```bash
+cd mcp-server
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configure auth
+
+**Recommended: long-lived API token** (1-year expiry, revocable any time).
+Log into [portal.smartoption.ai](https://portal.smartoption.ai) → 个人中心
+→ "API Token（用于 MCP / 脚本）" → 起个名字 → 复制生成的 token。
+管理页面随时可以吊销。
+
+**Fallback: session JWT** — if the API tokens page isn't deployed yet,
+open DevTools → Application → Local Storage → copy the `access_token`
+field. Expires in ~24h so you'll re-paste daily.
+
+Either way, the token goes into `SMARTOPTION_JWT`. Set
+`SMARTOPTION_API_BASE=https://api.smartoption.ai`.
+
+Smoke test from a shell:
+
+```bash
+export SMARTOPTION_API_BASE="https://api.smartoption.ai"
+export SMARTOPTION_JWT="eyJ..."   # no "Bearer " prefix
+.venv/bin/python -c "from smartoption_mcp.client import SmartoptionClient; \
+  print(SmartoptionClient().list_agents())"
+```
+
+## Register with Claude Code / Claude Desktop
+
+**Claude Code** (this repo's primary host) — edit `~/.claude.json` and add
+under the top-level `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "smartoption": {
+      "command": "smartoption-mcp",
+      "env": {
+        "SMARTOPTION_API_BASE": "https://api.smartoption.ai",
+        "SMARTOPTION_JWT": "eyJ..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code (or start a new session). The 5 `smartoption` tools
+should appear in the tool list.
+
+**Claude Desktop** — same JSON shape, but the file lives at
+`~/Library/Application Support/Claude/claude_desktop_config.json`. Restart
+the app after editing.
+
+Once registered, you should be able to ask things like:
+
+- "查一下最近一周苹果相关的喊单"
+- "我现在的虚拟仓有哪些标的？"
+- "我的跟单 agent 在线吗？最近一次心跳是什么时候？"
+- "今天 agent 跑了几条信号，有没有被跳过的？"
+
+## Tools
+
+### Read (Phase 1)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `list_copy_rules` | `GET /copy-rules` | Current copy-trading rules |
+| `list_virtual_lots` | `GET /virtual-ledger` | Open virtual lots + qty_by_key |
+| `get_agent_status` | `GET /agents` | Per-user agent online status |
+| `query_signal_history` | `GET /signal-history` | Search parsed alerts (大单) |
+| `list_run_logs` | `GET /copy-run-logs` | Per-signal execution outcomes |
+
+### Write (Phase 2)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `update_copy_rules` | `PUT /copy-rules` | Replace full copy-trading settings (rules + toggles) |
+| `ensure_agent` | `POST /agents/ensure` | Create / provision the user's agent k8s pod |
+| `refresh_broker_snapshot` | `POST /broker-account-snapshot/refresh` | Ask agent to push fresh broker snapshot |
+
+### Phase 2 extension (broker config + agent ops + signal detail + quant)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `list_broker_configurations` | `GET /broker-configurations` | All saved brokers + active (no creds returned) |
+| `get_active_broker` | `GET /broker-configurations` | Just the active broker name + display name |
+| `set_active_broker` | `PUT /active-broker` | Switch active broker — dry-run gated |
+| `test_broker_connection` | `POST /broker-configurations/test-{ib,tiger,futu,moomoo}` | Verify creds against broker; does NOT save |
+| `restart_agent_client` | `POST /agents/<id>/restart-client` | Restart in-pod agent process — dry-run gated |
+| `stop_agent` | `POST /agents/<id>/stop` | Scale agent deployment to 0 — dry-run gated |
+| `get_agent_logs` | `GET /agents/<id>/logs` | Tail recent agent-pod stdout |
+| `get_signal_detail` | `GET /signal-history/<id>` | Full SignalForwardRecord for one signal |
+| `get_signal_chain` | `GET /signal-history/<id>/chain-slots` | Paired/chained signal context (ROLL_UP pairs etc.) |
+| `list_virtual_followers` | `GET /api/customer/virtual-followers` | User's virtual-follower accounts + equity summary |
+| `list_quant_strategies` | `GET /api/customer/quant-strategies/list` | Available / subscribed quant strategies |
+| `get_quant_strategy_snapshot` | `GET /api/customer/quant-strategies/<id>/snapshot` | One strategy's positions + canonical valuation |
+
+**Confirmation model.** Destructive writes use a `confirmed: bool` flag,
+defaulting to `False` for **dry-run**:
+
+- `update_copy_rules(new_settings, confirmed=False)` → server fetches
+  current settings, returns a structured diff (top-level toggle changes +
+  rules added / removed / modified, keyed by `rule_id`). Nothing is
+  written. The model is instructed (via docstring) to show the diff to
+  the user and only call again with `confirmed=True` after approval.
+- `ensure_agent(force_redeploy=True, confirmed=False)` → returns a
+  description of the redeploy without doing it. Default `force_redeploy=False`
+  is idempotent and skips the dry-run gate.
+- `refresh_broker_snapshot` → no gate (non-destructive async request).
+
+The host (Claude Code / Desktop) also shows tool-call arguments to the
+user before each call, so `confirmed=True` is always visible in the
+approval UI — the in-tool `confirmed` flag is a second belt on top of
+that suspenders.
+
+**Validation.** `update_copy_rules` rejects partial settings: the proposed
+doc must contain `auto_buy_enabled`, `auto_sell_enabled`,
+`use_all_matched_rules`, and `rules`. The model is expected to start from
+`list_copy_rules`, mutate locally, and pass the full doc back —
+preserving every rule's `rule_id` so the diff stays stable.
+
+## Roadmap
+
+- **Phase 3 (✅ Phase 3a done)**: long-lived API tokens managed from the
+  customer portal — eliminates daily JWT re-paste, no protocol changes.
+  Tokens are still pasted into env; Phase 3b would be full MCP OAuth 2.1
+  with a remote HTTP MCP server so other users can connect from their own
+  Claude install without copy-paste. Deferred until there's a real
+  multi-user use case.

smartoption_mcp-0.1.1/README.md

@@ -0,0 +1,170 @@
+# smartoption-mcp
+
+MCP server that exposes the smartoption-ai **customer auto-trade API** as tools
+for AI agents (Claude Desktop, Claude Code, anything that speaks MCP).
+
+Phase 1 is **read-only**: 5 tools covering copy rules, virtual lots, agent
+status, parsed signal history (大单/喊单历史), and copy-run logs. Write
+operations (creating/modifying rules, placing orders) will be added in
+Phase 2 once the read path is battle-tested.
+
+## Architecture
+
+```
+Claude / Agent
+   │  MCP stdio
+   ▼
+smartoption-mcp  ──HTTP + Bearer JWT──▶  backend  /api/customer/auto-trade/*
+```
+
+The server is a thin wrapper: each tool maps 1:1 (or close) to a customer
+API endpoint, authenticated with a user JWT loaded from env at startup.
+
+## Install
+
+### End-user (recommended)
+
+```bash
+pip install smartoption-mcp
+# or, in an isolated venv:
+python3.11 -m venv ~/.smartoption-mcp && ~/.smartoption-mcp/bin/pip install smartoption-mcp
+```
+
+`smartoption-mcp` is published on [PyPI](https://pypi.org/project/smartoption-mcp/).
+This installs the `smartoption-mcp` CLI entry point. Upgrade with
+`pip install -U smartoption-mcp`.
+
+### Local dev (from this repo)
+
+```bash
+cd mcp-server
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configure auth
+
+**Recommended: long-lived API token** (1-year expiry, revocable any time).
+Log into [portal.smartoption.ai](https://portal.smartoption.ai) → 个人中心
+→ "API Token（用于 MCP / 脚本）" → 起个名字 → 复制生成的 token。
+管理页面随时可以吊销。
+
+**Fallback: session JWT** — if the API tokens page isn't deployed yet,
+open DevTools → Application → Local Storage → copy the `access_token`
+field. Expires in ~24h so you'll re-paste daily.
+
+Either way, the token goes into `SMARTOPTION_JWT`. Set
+`SMARTOPTION_API_BASE=https://api.smartoption.ai`.
+
+Smoke test from a shell:
+
+```bash
+export SMARTOPTION_API_BASE="https://api.smartoption.ai"
+export SMARTOPTION_JWT="eyJ..."   # no "Bearer " prefix
+.venv/bin/python -c "from smartoption_mcp.client import SmartoptionClient; \
+  print(SmartoptionClient().list_agents())"
+```
+
+## Register with Claude Code / Claude Desktop
+
+**Claude Code** (this repo's primary host) — edit `~/.claude.json` and add
+under the top-level `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "smartoption": {
+      "command": "smartoption-mcp",
+      "env": {
+        "SMARTOPTION_API_BASE": "https://api.smartoption.ai",
+        "SMARTOPTION_JWT": "eyJ..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code (or start a new session). The 5 `smartoption` tools
+should appear in the tool list.
+
+**Claude Desktop** — same JSON shape, but the file lives at
+`~/Library/Application Support/Claude/claude_desktop_config.json`. Restart
+the app after editing.
+
+Once registered, you should be able to ask things like:
+
+- "查一下最近一周苹果相关的喊单"
+- "我现在的虚拟仓有哪些标的？"
+- "我的跟单 agent 在线吗？最近一次心跳是什么时候？"
+- "今天 agent 跑了几条信号，有没有被跳过的？"
+
+## Tools
+
+### Read (Phase 1)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `list_copy_rules` | `GET /copy-rules` | Current copy-trading rules |
+| `list_virtual_lots` | `GET /virtual-ledger` | Open virtual lots + qty_by_key |
+| `get_agent_status` | `GET /agents` | Per-user agent online status |
+| `query_signal_history` | `GET /signal-history` | Search parsed alerts (大单) |
+| `list_run_logs` | `GET /copy-run-logs` | Per-signal execution outcomes |
+
+### Write (Phase 2)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `update_copy_rules` | `PUT /copy-rules` | Replace full copy-trading settings (rules + toggles) |
+| `ensure_agent` | `POST /agents/ensure` | Create / provision the user's agent k8s pod |
+| `refresh_broker_snapshot` | `POST /broker-account-snapshot/refresh` | Ask agent to push fresh broker snapshot |
+
+### Phase 2 extension (broker config + agent ops + signal detail + quant)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `list_broker_configurations` | `GET /broker-configurations` | All saved brokers + active (no creds returned) |
+| `get_active_broker` | `GET /broker-configurations` | Just the active broker name + display name |
+| `set_active_broker` | `PUT /active-broker` | Switch active broker — dry-run gated |
+| `test_broker_connection` | `POST /broker-configurations/test-{ib,tiger,futu,moomoo}` | Verify creds against broker; does NOT save |
+| `restart_agent_client` | `POST /agents/<id>/restart-client` | Restart in-pod agent process — dry-run gated |
+| `stop_agent` | `POST /agents/<id>/stop` | Scale agent deployment to 0 — dry-run gated |
+| `get_agent_logs` | `GET /agents/<id>/logs` | Tail recent agent-pod stdout |
+| `get_signal_detail` | `GET /signal-history/<id>` | Full SignalForwardRecord for one signal |
+| `get_signal_chain` | `GET /signal-history/<id>/chain-slots` | Paired/chained signal context (ROLL_UP pairs etc.) |
+| `list_virtual_followers` | `GET /api/customer/virtual-followers` | User's virtual-follower accounts + equity summary |
+| `list_quant_strategies` | `GET /api/customer/quant-strategies/list` | Available / subscribed quant strategies |
+| `get_quant_strategy_snapshot` | `GET /api/customer/quant-strategies/<id>/snapshot` | One strategy's positions + canonical valuation |
+
+**Confirmation model.** Destructive writes use a `confirmed: bool` flag,
+defaulting to `False` for **dry-run**:
+
+- `update_copy_rules(new_settings, confirmed=False)` → server fetches
+  current settings, returns a structured diff (top-level toggle changes +
+  rules added / removed / modified, keyed by `rule_id`). Nothing is
+  written. The model is instructed (via docstring) to show the diff to
+  the user and only call again with `confirmed=True` after approval.
+- `ensure_agent(force_redeploy=True, confirmed=False)` → returns a
+  description of the redeploy without doing it. Default `force_redeploy=False`
+  is idempotent and skips the dry-run gate.
+- `refresh_broker_snapshot` → no gate (non-destructive async request).
+
+The host (Claude Code / Desktop) also shows tool-call arguments to the
+user before each call, so `confirmed=True` is always visible in the
+approval UI — the in-tool `confirmed` flag is a second belt on top of
+that suspenders.
+
+**Validation.** `update_copy_rules` rejects partial settings: the proposed
+doc must contain `auto_buy_enabled`, `auto_sell_enabled`,
+`use_all_matched_rules`, and `rules`. The model is expected to start from
+`list_copy_rules`, mutate locally, and pass the full doc back —
+preserving every rule's `rule_id` so the diff stays stable.
+
+## Roadmap
+
+- **Phase 3 (✅ Phase 3a done)**: long-lived API tokens managed from the
+  customer portal — eliminates daily JWT re-paste, no protocol changes.
+  Tokens are still pasted into env; Phase 3b would be full MCP OAuth 2.1
+  with a remote HTTP MCP server so other users can connect from their own
+  Claude install without copy-paste. Deferred until there's a real
+  multi-user use case.

smartoption_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "smartoption-mcp"
+version = "0.1.1"
+description = "MCP server exposing the smartoption-ai customer auto-trade API as tools for AI agents (Claude Desktop / Claude Code / any MCP client)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+authors = [{ name = "SmartOption", email = "service.smartoption@gmail.com" }]
+keywords = ["mcp", "smartoption", "claude", "auto-trade", "copy-trading"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "mcp>=1.2.0",
+  "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SmartOption/smartoption-ai"
+Repository = "https://github.com/SmartOption/smartoption-ai"
+Issues = "https://github.com/SmartOption/smartoption-ai/issues"
+
+[project.scripts]
+smartoption-mcp = "smartoption_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["smartoption_mcp*"]

smartoption_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smartoption_mcp-0.1.1/smartoption_mcp/client.py

@@ -0,0 +1,166 @@
+"""Thin HTTP client for the smartoption-ai customer auto-trade API.
+
+All endpoints under /api/customer/auto-trade are user-JWT scoped: the
+authenticated user's id is derived from the token, so we never pass user_id
+explicitly. The JWT comes from env (SMARTOPTION_JWT) at server startup.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE = "https://api.smartoption.ai"
+
+
+class SmartoptionClient:
+    def __init__(self, base_url: str | None = None, jwt: str | None = None, timeout: float = 20.0):
+        self.base_url = (base_url or os.environ.get("SMARTOPTION_API_BASE") or DEFAULT_BASE).rstrip("/")
+        self.jwt = jwt or os.environ.get("SMARTOPTION_JWT") or ""
+        if not self.jwt:
+            raise RuntimeError("SMARTOPTION_JWT env var is required")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {self.jwt}"},
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        clean = {k: v for k, v in (params or {}).items() if v is not None and v != ""}
+        r = self._client.get(path, params=clean)
+        r.raise_for_status()
+        return self._unwrap(r.json())
+
+    def _post(self, path: str, json_body: dict[str, Any] | None = None) -> Any:
+        r = self._client.post(path, json=json_body or {})
+        r.raise_for_status()
+        return self._unwrap(r.json())
+
+    def _put(self, path: str, json_body: dict[str, Any] | None = None) -> Any:
+        r = self._client.put(path, json=json_body or {})
+        r.raise_for_status()
+        return self._unwrap(r.json())
+
+    @staticmethod
+    def _unwrap(body: Any) -> Any:
+        # ResponseFormatter wraps payloads as {success, data, message}
+        if isinstance(body, dict) and "data" in body:
+            return body.get("data")
+        return body
+
+    def list_copy_rules(self) -> Any:
+        return self._get("/api/customer/auto-trade/copy-rules")
+
+    def list_virtual_lots(self) -> Any:
+        return self._get("/api/customer/auto-trade/virtual-ledger")
+
+    def list_agents(self) -> Any:
+        return self._get("/api/customer/auto-trade/agents")
+
+    def query_signal_history(
+        self,
+        page: int = 1,
+        per_page: int = 20,
+        raw_content_search: str | None = None,
+        message_source_ids: list[str] | None = None,
+        created_at_from: str | None = None,
+        created_at_to: str | None = None,
+    ) -> Any:
+        return self._get(
+            "/api/customer/auto-trade/signal-history",
+            {
+                "page": page,
+                "per_page": per_page,
+                "raw_content_search": raw_content_search,
+                "message_source_ids": ",".join(message_source_ids) if message_source_ids else None,
+                "created_at_from": created_at_from,
+                "created_at_to": created_at_to,
+            },
+        )
+
+    def put_copy_rules(self, new_settings: dict[str, Any]) -> Any:
+        return self._put("/api/customer/auto-trade/copy-rules", new_settings)
+
+    def ensure_agent(
+        self,
+        label: str | None = None,
+        provision_k8s: bool = True,
+        force_redeploy: bool = False,
+    ) -> Any:
+        body: dict[str, Any] = {"provision_k8s": provision_k8s, "force_redeploy": force_redeploy}
+        if label:
+            body["label"] = label
+        return self._post("/api/customer/auto-trade/agents/ensure", body)
+
+    def refresh_broker_snapshot(self, agent_id: str | None = None) -> Any:
+        body = {"agent_id": agent_id} if agent_id else {}
+        return self._post("/api/customer/auto-trade/broker-account-snapshot/refresh", body)
+
+    # ---- Phase 2: broker configuration ----
+    def list_broker_configurations(self) -> Any:
+        return self._get("/api/customer/auto-trade/broker-configurations")
+
+    def set_active_broker(self, broker_name: str | None) -> Any:
+        return self._put("/api/customer/auto-trade/active-broker", {"active_broker": broker_name})
+
+    def test_broker_connection(self, broker_name: str, credentials: dict[str, Any]) -> Any:
+        slug = broker_name.lower().strip()
+        if slug not in {"ib", "tiger", "futu", "moomoo"}:
+            raise ValueError(f"unsupported broker for connection test: {broker_name}")
+        return self._post(f"/api/customer/auto-trade/broker-configurations/test-{slug}", credentials)
+
+    # ---- Phase 2: agent ops ----
+    def restart_agent_client(self, agent_id: str) -> Any:
+        return self._post(f"/api/customer/auto-trade/agents/{agent_id}/restart-client")
+
+    def stop_agent(self, agent_id: str) -> Any:
+        return self._post(f"/api/customer/auto-trade/agents/{agent_id}/stop")
+
+    def get_agent_logs(self, agent_id: str, lines: int = 200) -> Any:
+        return self._get(f"/api/customer/auto-trade/agents/{agent_id}/logs", {"lines": lines})
+
+    # ---- Phase 2: signal detail ----
+    def get_signal_detail(self, record_id: str) -> Any:
+        return self._get(f"/api/customer/auto-trade/signal-history/{record_id}")
+
+    def get_signal_chain_slots(self, record_id: str) -> Any:
+        return self._get(f"/api/customer/auto-trade/signal-history/{record_id}/chain-slots")
+
+    # ---- Phase 2: virtual followers ----
+    def list_virtual_followers(self) -> Any:
+        return self._get("/api/customer/virtual-followers")
+
+    # ---- Phase 2: quant strategies ----
+    def list_quant_strategies(self) -> Any:
+        return self._get("/api/customer/quant-strategies/list")
+
+    def get_quant_strategy_snapshot(self, strategy_id: str) -> Any:
+        return self._get(f"/api/customer/quant-strategies/{strategy_id}/snapshot")
+
+    def list_run_logs(
+        self,
+        page: int = 1,
+        per_page: int = 30,
+        signal_id: str | None = None,
+        call_content: str | None = None,
+        message_source_ids: list[str] | None = None,
+        created_after: str | None = None,
+        created_before: str | None = None,
+    ) -> Any:
+        return self._get(
+            "/api/customer/auto-trade/copy-run-logs",
+            {
+                "page": page,
+                "per_page": per_page,
+                "signal_id": signal_id,
+                "call_content": call_content,
+                "message_source_ids": ",".join(message_source_ids) if message_source_ids else None,
+                "created_after": created_after,
+                "created_before": created_before,
+            },
+        )

smartoption_mcp-0.1.1/smartoption_mcp/diff.py

@@ -0,0 +1,105 @@
+"""Structured diff for copy-trading settings dicts.
+
+Goal: give the model (and the user reading via the model) a compact,
+unambiguous view of what would change between current and proposed
+settings. Diffs by rule_id where possible so reordering rules doesn't
+produce noisy output.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+_SCALAR_KEYS = (
+    "auto_buy_enabled",
+    "auto_sell_enabled",
+    "use_all_matched_rules",
+    "active_time_start",
+    "active_time_end",
+    "active_weekdays",
+)
+
+
+def diff_copy_settings(current: dict[str, Any], proposed: dict[str, Any]) -> dict[str, Any]:
+    changes: list[dict[str, Any]] = []
+
+    for key in _SCALAR_KEYS:
+        cv = current.get(key)
+        pv = proposed.get(key)
+        if cv != pv:
+            changes.append({"path": key, "before": cv, "after": pv})
+
+    cur_rules = {r.get("rule_id"): r for r in (current.get("rules") or []) if isinstance(r, dict)}
+    new_rules = {r.get("rule_id"): r for r in (proposed.get("rules") or []) if isinstance(r, dict)}
+
+    added_rules = [r for rid, r in new_rules.items() if rid and rid not in cur_rules]
+    removed_rules = [r for rid, r in cur_rules.items() if rid and rid not in new_rules]
+
+    # Rules in proposed without rule_id are treated as new (frontend assigns
+    # uuid server-side, so this is the normal "add a new rule" path).
+    added_rules += [r for r in (proposed.get("rules") or []) if isinstance(r, dict) and not r.get("rule_id")]
+
+    modified_rules: list[dict[str, Any]] = []
+    for rid, new_rule in new_rules.items():
+        if not rid or rid not in cur_rules:
+            continue
+        cur_rule = cur_rules[rid]
+        rule_changes = _shallow_field_diff(cur_rule, new_rule)
+        if rule_changes:
+            modified_rules.append(
+                {
+                    "rule_id": rid,
+                    "name": new_rule.get("name") or cur_rule.get("name"),
+                    "fields": rule_changes,
+                }
+            )
+
+    return {
+        "top_level_changes": changes,
+        "rules_added": [
+            {"rule_id": r.get("rule_id"), "name": r.get("name"), "enabled": r.get("enabled")}
+            for r in added_rules
+        ],
+        "rules_removed": [
+            {"rule_id": r.get("rule_id"), "name": r.get("name")} for r in removed_rules
+        ],
+        "rules_modified": modified_rules,
+        "summary": {
+            "top_level_changed": len(changes),
+            "rules_added": len(added_rules),
+            "rules_removed": len(removed_rules),
+            "rules_modified": len(modified_rules),
+        },
+    }
+
+
+def _shallow_field_diff(a: dict[str, Any], b: dict[str, Any]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    keys = set(a.keys()) | set(b.keys())
+    # These are server-set echo fields; ignore.
+    keys.discard("updated_at")
+    for k in sorted(keys):
+        if a.get(k) != b.get(k):
+            out.append({"field": k, "before": a.get(k), "after": b.get(k)})
+    return out
+
+
+REQUIRED_TOP_LEVEL_KEYS = ("auto_buy_enabled", "auto_sell_enabled", "use_all_matched_rules", "rules")
+
+
+def validate_full_settings(proposed: dict[str, Any]) -> list[str]:
+    """Returns a list of validation errors. Empty list = OK."""
+    errors: list[str] = []
+    if not isinstance(proposed, dict):
+        return ["new_settings must be an object"]
+    for k in REQUIRED_TOP_LEVEL_KEYS:
+        if k not in proposed:
+            errors.append(
+                f"missing required top-level key '{k}'. You must pass the FULL settings doc "
+                f"(start from list_copy_rules and mutate locally), not a partial patch."
+            )
+    rules = proposed.get("rules")
+    if "rules" in proposed and not isinstance(rules, list):
+        errors.append("'rules' must be a list")
+    return errors

smartoption_mcp-0.1.1/smartoption_mcp/server.py

@@ -0,0 +1,436 @@
+"""MCP server exposing read-only smartoption-ai customer auto-trade tools.
+
+Phase 1 (read-only): 5 tools — copy rules, virtual lots, agent status,
+signal history (大单/喊单历史), and copy-run logs. Write operations
+(create/modify copy rules, place orders) are intentionally not exposed yet.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import SmartoptionClient
+from .diff import diff_copy_settings, validate_full_settings
+
+mcp = FastMCP("smartoption")
+_client: SmartoptionClient | None = None
+
+
+def _c() -> SmartoptionClient:
+    global _client
+    if _client is None:
+        _client = SmartoptionClient()
+    return _client
+
+
+def _dump(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, default=str)
+
+
+@mcp.tool()
+def list_copy_rules() -> str:
+    """List the current user's copy-trading rules and global settings.
+
+    Returns the same payload the customer frontend uses to render the
+    CopyRules panel: enabled rules, source channel filters, sizing,
+    premium controls, ROLL_UP options, etc.
+    """
+    return _dump(_c().list_copy_rules())
+
+
+@mcp.tool()
+def list_virtual_lots() -> str:
+    """List the user's virtual-ledger open lots (CopyTradingVirtualLot rows).
+
+    Useful to answer "what virtual positions am I currently holding?" and
+    "what's the unrealized pnl on my paper-traded copies?". Includes a
+    qty_by_key map for quick aggregation by position_key.
+    """
+    return _dump(_c().list_virtual_lots())
+
+
+@mcp.tool()
+def get_agent_status() -> str:
+    """Return the user's auto-trade agent(s): online/offline, last heartbeat,
+    active broker, k8s pod state. Use this to answer "is my copy-trade
+    bot running?" / "did it disconnect?".
+    """
+    return _dump(_c().list_agents())
+
+
+@mcp.tool()
+def query_signal_history(
+    raw_content_search: str | None = None,
+    message_source_ids: list[str] | None = None,
+    created_at_from: str | None = None,
+    created_at_to: str | None = None,
+    page: int = 1,
+    per_page: int = 20,
+) -> str:
+    """Search parsed trader-alert signals (a.k.a. 历史喊单 / 大单).
+
+    Each row is a SignalForwardRecord with the original raw alert text and
+    the LLM-parsed structured signal (action, instrument_kind, option_legs,
+    size_relative, etc.).
+
+    Args:
+      raw_content_search: free-text substring match on the raw alert (e.g.
+        "AAPL", "苹果", a strike, an expiry). Server-side ILIKE match.
+      message_source_ids: optional list of MessageSource ObjectIds to scope
+        to particular Discord channels / X-API accounts / etc.
+      created_at_from / created_at_to: ISO 8601 timestamps to bound the
+        search window. Prefer narrow windows (a few days) for relevance.
+      page / per_page: standard pagination; per_page capped server-side at 100.
+    """
+    return _dump(
+        _c().query_signal_history(
+            page=page,
+            per_page=per_page,
+            raw_content_search=raw_content_search,
+            message_source_ids=message_source_ids,
+            created_at_from=created_at_from,
+            created_at_to=created_at_to,
+        )
+    )
+
+
+@mcp.tool()
+def list_run_logs(
+    signal_id: str | None = None,
+    call_content: str | None = None,
+    message_source_ids: list[str] | None = None,
+    created_after: str | None = None,
+    created_before: str | None = None,
+    page: int = 1,
+    per_page: int = 30,
+) -> str:
+    """List CopyTradingRunLog rows — the agent's per-signal execution outcomes.
+
+    Use this to answer "did my agent act on signal X?", "why was it skipped?",
+    "show me today's executions". Each row carries the matched rule, the
+    submitted broker orders (with canonical view), and an outcome code such
+    as `buy_open_submitted`, `roll_up_close_skipped_no_rule`, `premium_blocked`.
+
+    Args:
+      signal_id: filter to a specific upstream signal id.
+      call_content: substring match against the original alert text.
+      message_source_ids: scope to specific source channels.
+      created_after / created_before: ISO 8601 timestamps.
+    """
+    return _dump(
+        _c().list_run_logs(
+            page=page,
+            per_page=per_page,
+            signal_id=signal_id,
+            call_content=call_content,
+            message_source_ids=message_source_ids,
+            created_after=created_after,
+            created_before=created_before,
+        )
+    )
+
+
+@mcp.tool()
+def update_copy_rules(new_settings: dict, confirmed: bool = False) -> str:
+    """Update the user's full copy-trading settings (rules + global toggles).
+
+    ⚠️ This is a **destructive write**. The customer backend PUT endpoint
+    replaces the entire settings document, so `new_settings` MUST be the
+    complete doc (start from `list_copy_rules`, mutate locally — never
+    construct from scratch or pass a partial patch).
+
+    Two-phase usage (required):
+      1. Call with `confirmed=False` (the default). The server fetches the
+         current settings, computes a structured diff vs `new_settings`,
+         and returns it WITHOUT writing. You MUST present this diff to the
+         user in natural language and get explicit approval.
+      2. Only after the user approves, call again with the same
+         `new_settings` and `confirmed=True` to actually persist.
+
+    Required top-level keys in new_settings: auto_buy_enabled,
+    auto_sell_enabled, use_all_matched_rules, rules. Optional:
+    active_time_start, active_time_end, active_weekdays.
+
+    Rule changes diff by `rule_id`, so preserve `rule_id` on every rule
+    you keep — otherwise the rule will look removed-and-re-added.
+    """
+    errors = validate_full_settings(new_settings)
+    if errors:
+        return _dump({"ok": False, "errors": errors})
+
+    if not confirmed:
+        current = _c().list_copy_rules() or {}
+        diff = diff_copy_settings(current, new_settings)
+        return _dump(
+            {
+                "ok": True,
+                "mode": "dry_run",
+                "diff": diff,
+                "next_step": (
+                    "Show this diff to the user. If they approve, call "
+                    "update_copy_rules again with the same new_settings and confirmed=True."
+                ),
+            }
+        )
+
+    result = _c().put_copy_rules(new_settings)
+    return _dump({"ok": True, "mode": "applied", "result": result})
+
+
+@mcp.tool()
+def ensure_agent(
+    label: str | None = None,
+    force_redeploy: bool = False,
+    confirmed: bool = False,
+) -> str:
+    """Ensure the user has an auto-trade agent pod provisioned in k8s.
+
+    Default (label=None, force_redeploy=False) is **idempotent**: if an
+    agent already exists it just returns its state; if not, it creates
+    one and provisions the k8s deployment. This default mode does NOT
+    require `confirmed=True`.
+
+    `force_redeploy=True` is **destructive** — it tears down and rebuilds
+    the user's agent pod (existing in-flight orders / heartbeats will be
+    interrupted). For this mode you MUST first call with
+    `confirmed=False` (returns a description of what will happen) and
+    then with `confirmed=True` after user approval.
+    """
+    if force_redeploy and not confirmed:
+        return _dump(
+            {
+                "ok": True,
+                "mode": "dry_run",
+                "action": "force_redeploy_agent",
+                "warning": (
+                    "This will tear down and rebuild the user's auto-trade agent k8s pod. "
+                    "In-flight broker connections and heartbeats will reset. "
+                    "Confirm with the user before calling again with confirmed=True."
+                ),
+            }
+        )
+    result = _c().ensure_agent(label=label, force_redeploy=force_redeploy)
+    return _dump({"ok": True, "mode": "applied", "result": result})
+
+
+@mcp.tool()
+def refresh_broker_snapshot(agent_id: str | None = None) -> str:
+    """Ask the user's auto-trade agent to push a fresh broker account
+    snapshot (positions + balances) up to the backend.
+
+    Non-destructive: just an async signal to the agent. Safe to call
+    without confirmation. If `agent_id` is omitted, uses the user's first
+    enabled agent.
+    """
+    return _dump(_c().refresh_broker_snapshot(agent_id=agent_id))
+
+
+# =========================================================================
+# Phase 2 tools — broker config, agent ops, signal detail, quant strategies
+# =========================================================================
+
+
+@mcp.tool()
+def list_broker_configurations() -> str:
+    """List the user's broker configurations + which broker is currently active.
+
+    Returns the same payload the customer "券商配置" page renders: which
+    brokers have credentials saved (configured), which one is active
+    (`active_broker`), and per-broker metadata. Credentials themselves
+    are NOT returned (server-side scrub).
+
+    Use this to answer "我配了哪些券商" / "现在在用哪个 broker".
+    """
+    return _dump(_c().list_broker_configurations())
+
+
+@mcp.tool()
+def get_active_broker() -> str:
+    """Return just the currently active broker name (and display name).
+
+    Thin wrapper over `list_broker_configurations` that narrows to the
+    `active_broker` / `active_broker_display_name` / `active_broker_configured`
+    fields. Use when the caller only needs "which broker is in use right now".
+    """
+    data = _c().list_broker_configurations() or {}
+    return _dump(
+        {
+            "active_broker": data.get("active_broker"),
+            "active_broker_display_name": data.get("active_broker_display_name"),
+            "active_broker_configured": data.get("active_broker_configured"),
+        }
+    )
+
+
+@mcp.tool()
+def set_active_broker(broker_name: str | None, confirmed: bool = False) -> str:
+    """Switch the user's active broker (or clear it with broker_name=None).
+
+    ⚠️ Destructive: changes which broker the auto-trade agent will route
+    orders through. In-flight orders on the previous broker are NOT
+    cancelled, but new copy-trade signals will go to the new broker.
+
+    Two-phase usage:
+      1. Call with confirmed=False to get a dry-run summary (current vs
+         target broker).
+      2. After user approval, call with confirmed=True.
+
+    `broker_name` must already have credentials configured (use
+    `list_broker_configurations` to check); pass None to clear active.
+    """
+    if not confirmed:
+        current = _c().list_broker_configurations() or {}
+        return _dump(
+            {
+                "ok": True,
+                "mode": "dry_run",
+                "current_active_broker": current.get("active_broker"),
+                "target_active_broker": broker_name,
+                "next_step": "Call again with confirmed=True after user approval.",
+            }
+        )
+    return _dump({"ok": True, "mode": "applied", "result": _c().set_active_broker(broker_name)})
+
+
+@mcp.tool()
+def test_broker_connection(broker_name: str, credentials: dict) -> str:
+    """Run the broker connection-test workflow for IB / Tiger / Futu / Moomoo.
+
+    Spawns a one-shot pod (or equivalent dry connection) against the
+    submitted `credentials` and returns the broker-side login + auth
+    result. Does NOT save the credentials — purely a verification call.
+
+    `credentials` shape is broker-specific; see the customer "券商配置"
+    form for the exact keys per broker (e.g. IB needs trading_mode +
+    login_id + login_password).
+    """
+    return _dump(_c().test_broker_connection(broker_name, credentials))
+
+
+@mcp.tool()
+def restart_agent_client(agent_id: str, confirmed: bool = False) -> str:
+    """Restart the agent-client process inside a user's auto-trade pod.
+
+    ⚠️ Destructive: in-flight socket connections to the gateway reset,
+    pending broker order-status polls are interrupted briefly (re-issued
+    on restart). Use when the agent looks stuck or after pushing a
+    config change that needs a process restart.
+
+    Two-phase: call with confirmed=False to get a dry-run, then with
+    confirmed=True to actually restart.
+    """
+    if not confirmed:
+        return _dump(
+            {
+                "ok": True,
+                "mode": "dry_run",
+                "action": "restart_agent_client",
+                "agent_id": agent_id,
+                "next_step": "Call again with confirmed=True after user approval.",
+            }
+        )
+    return _dump({"ok": True, "mode": "applied", "result": _c().restart_agent_client(agent_id)})
+
+
+@mcp.tool()
+def stop_agent(agent_id: str, confirmed: bool = False) -> str:
+    """Stop the user's auto-trade agent (scale deployment to 0 replicas).
+
+    ⚠️ Destructive: the agent will stop receiving trading_signal events
+    and stop polling broker order status until restarted (via
+    `ensure_agent` or in the UI). Use when the user wants to pause
+    copy-trading without deleting their config.
+
+    Two-phase: confirmed=False for dry-run, confirmed=True to apply.
+    """
+    if not confirmed:
+        return _dump(
+            {
+                "ok": True,
+                "mode": "dry_run",
+                "action": "stop_agent",
+                "agent_id": agent_id,
+                "next_step": "Call again with confirmed=True after user approval.",
+            }
+        )
+    return _dump({"ok": True, "mode": "applied", "result": _c().stop_agent(agent_id)})
+
+
+@mcp.tool()
+def get_agent_logs(agent_id: str, lines: int = 200) -> str:
+    """Fetch recent stdout logs from the user's auto-trade agent pod.
+
+    `lines` is the tail length (default 200, server may cap). Useful for
+    "why didn't my agent act on this signal" / "is the agent crashing".
+    """
+    return _dump(_c().get_agent_logs(agent_id, lines=lines))
+
+
+@mcp.tool()
+def get_signal_detail(record_id: str) -> str:
+    """Fetch the full SignalForwardRecord for one signal id.
+
+    Includes the raw alert text, the LLM-parsed structured signal, the
+    upstream message_source metadata, and any backfill/normalize traces.
+    Use this after `query_signal_history` returns a row id that the user
+    wants to drill into.
+    """
+    return _dump(_c().get_signal_detail(record_id))
+
+
+@mcp.tool()
+def get_signal_chain(record_id: str) -> str:
+    """Return the chain-slot context (the same signal across the trader's
+    recent signal chain) for one SignalForwardRecord id.
+
+    Used by the frontend to show "this signal is part of a ROLL_UP pair"
+    / "previous open from same trader" / paired-leg relationships. Pairs
+    nicely with ROLL_UP debugging.
+    """
+    return _dump(_c().get_signal_chain_slots(record_id))
+
+
+@mcp.tool()
+def list_virtual_followers() -> str:
+    """List the user's virtual-follower accounts.
+
+    Each VirtualFollower mirrors a trader's signals into a sandboxed
+    VirtualAccount (no real broker), tracked end-to-end through the
+    canonical valuation pipeline. Returns id, label, the followed
+    message-source, and current equity summary.
+    """
+    return _dump(_c().list_virtual_followers())
+
+
+@mcp.tool()
+def list_quant_strategies() -> str:
+    """List quant strategies available / subscribed by the user.
+
+    Returns id, name, description, visibility (public/private), and the
+    user's subscription state. Pairs with `get_quant_strategy_snapshot`
+    for per-strategy 持仓 + 业绩 detail.
+    """
+    return _dump(_c().list_quant_strategies())
+
+
+@mcp.tool()
+def get_quant_strategy_snapshot(strategy_id: str) -> str:
+    """Fetch one quant strategy's current positions + performance snapshot.
+
+    Backed by the canonical virtual-account valuation
+    (compute_virtual_account_totals), so the numbers match what the
+    `AIStrategyDetail.vue` page renders: total_value, cash_balance,
+    positions_detail, win-rate / realized PnL metrics.
+    """
+    return _dump(_c().get_quant_strategy_snapshot(strategy_id))
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

smartoption_mcp-0.1.1/smartoption_mcp.egg-info/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: smartoption-mcp
+Version: 0.1.1
+Summary: MCP server exposing the smartoption-ai customer auto-trade API as tools for AI agents (Claude Desktop / Claude Code / any MCP client).
+Author-email: SmartOption <service.smartoption@gmail.com>
+License: Proprietary
+Project-URL: Homepage, https://github.com/SmartOption/smartoption-ai
+Project-URL: Repository, https://github.com/SmartOption/smartoption-ai
+Project-URL: Issues, https://github.com/SmartOption/smartoption-ai/issues
+Keywords: mcp,smartoption,claude,auto-trade,copy-trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: httpx>=0.27.0
+
+# smartoption-mcp
+
+MCP server that exposes the smartoption-ai **customer auto-trade API** as tools
+for AI agents (Claude Desktop, Claude Code, anything that speaks MCP).
+
+Phase 1 is **read-only**: 5 tools covering copy rules, virtual lots, agent
+status, parsed signal history (大单/喊单历史), and copy-run logs. Write
+operations (creating/modifying rules, placing orders) will be added in
+Phase 2 once the read path is battle-tested.
+
+## Architecture
+
+```
+Claude / Agent
+   │  MCP stdio
+   ▼
+smartoption-mcp  ──HTTP + Bearer JWT──▶  backend  /api/customer/auto-trade/*
+```
+
+The server is a thin wrapper: each tool maps 1:1 (or close) to a customer
+API endpoint, authenticated with a user JWT loaded from env at startup.
+
+## Install
+
+### End-user (recommended)
+
+```bash
+pip install smartoption-mcp
+# or, in an isolated venv:
+python3.11 -m venv ~/.smartoption-mcp && ~/.smartoption-mcp/bin/pip install smartoption-mcp
+```
+
+`smartoption-mcp` is published on [PyPI](https://pypi.org/project/smartoption-mcp/).
+This installs the `smartoption-mcp` CLI entry point. Upgrade with
+`pip install -U smartoption-mcp`.
+
+### Local dev (from this repo)
+
+```bash
+cd mcp-server
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configure auth
+
+**Recommended: long-lived API token** (1-year expiry, revocable any time).
+Log into [portal.smartoption.ai](https://portal.smartoption.ai) → 个人中心
+→ "API Token（用于 MCP / 脚本）" → 起个名字 → 复制生成的 token。
+管理页面随时可以吊销。
+
+**Fallback: session JWT** — if the API tokens page isn't deployed yet,
+open DevTools → Application → Local Storage → copy the `access_token`
+field. Expires in ~24h so you'll re-paste daily.
+
+Either way, the token goes into `SMARTOPTION_JWT`. Set
+`SMARTOPTION_API_BASE=https://api.smartoption.ai`.
+
+Smoke test from a shell:
+
+```bash
+export SMARTOPTION_API_BASE="https://api.smartoption.ai"
+export SMARTOPTION_JWT="eyJ..."   # no "Bearer " prefix
+.venv/bin/python -c "from smartoption_mcp.client import SmartoptionClient; \
+  print(SmartoptionClient().list_agents())"
+```
+
+## Register with Claude Code / Claude Desktop
+
+**Claude Code** (this repo's primary host) — edit `~/.claude.json` and add
+under the top-level `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "smartoption": {
+      "command": "smartoption-mcp",
+      "env": {
+        "SMARTOPTION_API_BASE": "https://api.smartoption.ai",
+        "SMARTOPTION_JWT": "eyJ..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code (or start a new session). The 5 `smartoption` tools
+should appear in the tool list.
+
+**Claude Desktop** — same JSON shape, but the file lives at
+`~/Library/Application Support/Claude/claude_desktop_config.json`. Restart
+the app after editing.
+
+Once registered, you should be able to ask things like:
+
+- "查一下最近一周苹果相关的喊单"
+- "我现在的虚拟仓有哪些标的？"
+- "我的跟单 agent 在线吗？最近一次心跳是什么时候？"
+- "今天 agent 跑了几条信号，有没有被跳过的？"
+
+## Tools
+
+### Read (Phase 1)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `list_copy_rules` | `GET /copy-rules` | Current copy-trading rules |
+| `list_virtual_lots` | `GET /virtual-ledger` | Open virtual lots + qty_by_key |
+| `get_agent_status` | `GET /agents` | Per-user agent online status |
+| `query_signal_history` | `GET /signal-history` | Search parsed alerts (大单) |
+| `list_run_logs` | `GET /copy-run-logs` | Per-signal execution outcomes |
+
+### Write (Phase 2)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `update_copy_rules` | `PUT /copy-rules` | Replace full copy-trading settings (rules + toggles) |
+| `ensure_agent` | `POST /agents/ensure` | Create / provision the user's agent k8s pod |
+| `refresh_broker_snapshot` | `POST /broker-account-snapshot/refresh` | Ask agent to push fresh broker snapshot |
+
+### Phase 2 extension (broker config + agent ops + signal detail + quant)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `list_broker_configurations` | `GET /broker-configurations` | All saved brokers + active (no creds returned) |
+| `get_active_broker` | `GET /broker-configurations` | Just the active broker name + display name |
+| `set_active_broker` | `PUT /active-broker` | Switch active broker — dry-run gated |
+| `test_broker_connection` | `POST /broker-configurations/test-{ib,tiger,futu,moomoo}` | Verify creds against broker; does NOT save |
+| `restart_agent_client` | `POST /agents/<id>/restart-client` | Restart in-pod agent process — dry-run gated |
+| `stop_agent` | `POST /agents/<id>/stop` | Scale agent deployment to 0 — dry-run gated |
+| `get_agent_logs` | `GET /agents/<id>/logs` | Tail recent agent-pod stdout |
+| `get_signal_detail` | `GET /signal-history/<id>` | Full SignalForwardRecord for one signal |
+| `get_signal_chain` | `GET /signal-history/<id>/chain-slots` | Paired/chained signal context (ROLL_UP pairs etc.) |
+| `list_virtual_followers` | `GET /api/customer/virtual-followers` | User's virtual-follower accounts + equity summary |
+| `list_quant_strategies` | `GET /api/customer/quant-strategies/list` | Available / subscribed quant strategies |
+| `get_quant_strategy_snapshot` | `GET /api/customer/quant-strategies/<id>/snapshot` | One strategy's positions + canonical valuation |
+
+**Confirmation model.** Destructive writes use a `confirmed: bool` flag,
+defaulting to `False` for **dry-run**:
+
+- `update_copy_rules(new_settings, confirmed=False)` → server fetches
+  current settings, returns a structured diff (top-level toggle changes +
+  rules added / removed / modified, keyed by `rule_id`). Nothing is
+  written. The model is instructed (via docstring) to show the diff to
+  the user and only call again with `confirmed=True` after approval.
+- `ensure_agent(force_redeploy=True, confirmed=False)` → returns a
+  description of the redeploy without doing it. Default `force_redeploy=False`
+  is idempotent and skips the dry-run gate.
+- `refresh_broker_snapshot` → no gate (non-destructive async request).
+
+The host (Claude Code / Desktop) also shows tool-call arguments to the
+user before each call, so `confirmed=True` is always visible in the
+approval UI — the in-tool `confirmed` flag is a second belt on top of
+that suspenders.
+
+**Validation.** `update_copy_rules` rejects partial settings: the proposed
+doc must contain `auto_buy_enabled`, `auto_sell_enabled`,
+`use_all_matched_rules`, and `rules`. The model is expected to start from
+`list_copy_rules`, mutate locally, and pass the full doc back —
+preserving every rule's `rule_id` so the diff stays stable.
+
+## Roadmap
+
+- **Phase 3 (✅ Phase 3a done)**: long-lived API tokens managed from the
+  customer portal — eliminates daily JWT re-paste, no protocol changes.
+  Tokens are still pasted into env; Phase 3b would be full MCP OAuth 2.1
+  with a remote HTTP MCP server so other users can connect from their own
+  Claude install without copy-paste. Deferred until there's a real
+  multi-user use case.

smartoption_mcp-0.1.1/smartoption_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+smartoption_mcp/__init__.py
+smartoption_mcp/client.py
+smartoption_mcp/diff.py
+smartoption_mcp/server.py
+smartoption_mcp.egg-info/PKG-INFO
+smartoption_mcp.egg-info/SOURCES.txt
+smartoption_mcp.egg-info/dependency_links.txt
+smartoption_mcp.egg-info/entry_points.txt
+smartoption_mcp.egg-info/requires.txt
+smartoption_mcp.egg-info/top_level.txt

smartoption_mcp-0.1.1/smartoption_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

smartoption_mcp-0.1.1/smartoption_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+smartoption-mcp = smartoption_mcp.server:main

smartoption_mcp-0.1.1/smartoption_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.2.0
+httpx>=0.27.0

smartoption_mcp-0.1.1/smartoption_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+smartoption_mcp