moomoo-api-mcp 0.1.6__py3-none-any.whl

moomoo_api_mcp-0.1.6.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+      Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

moomoo_mcp/server.py

@@ -0,0 +1,117 @@
+import logging
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+
+from mcp.server.fastmcp import FastMCP
+from moomoo.common import ft_logger
+from moomoo_mcp.services.base_service import MoomooService
+from moomoo_mcp.services.market_data_service import MarketDataService
+from moomoo_mcp.services.trade_service import TradeService
+
+logger = logging.getLogger(__name__)
+
+
+# Disable moomoo library console logging to prevent corruption of MCP stdout protocol
+if hasattr(ft_logger, "logger") and hasattr(ft_logger.logger, "console_logger"):
+    # Clear existing handlers
+    ft_logger.logger.console_logger.handlers = []
+    # Replace the internal consoleHandler reference with a NullHandler.
+    # This ensures that when fontColor/info/error is called and it tries to re-add 
+    # self.consoleHandler, it adds a harmless NullHandler instead of a StreamHandler.
+    ft_logger.logger.consoleHandler = logging.NullHandler()
+
+
+@dataclass
+class AppContext:
+    """Application context with typed dependencies."""
+    moomoo_service: MoomooService
+    trade_service: TradeService
+    market_data_service: MarketDataService
+
+
+def _auto_unlock_trade(trade_service: TradeService) -> None:
+    """Attempt to auto-unlock trade using environment variables.
+
+    Reads MOOMOO_TRADE_PASSWORD (plain text, preferred) or MOOMOO_TRADE_PASSWORD_MD5.
+    Logs status and handles failures gracefully without crashing.
+    """
+    password = os.environ.get("MOOMOO_TRADE_PASSWORD")
+    password_md5 = os.environ.get("MOOMOO_TRADE_PASSWORD_MD5")
+
+    if not password and not password_md5:
+        logger.info(
+            "No trade password configured (MOOMOO_TRADE_PASSWORD or "
+            "MOOMOO_TRADE_PASSWORD_MD5 not set). Running in SIMULATE-only mode."
+        )
+        return
+
+    try:
+        # Must fetch account list before unlock to initialize account context
+        accounts = trade_service.get_accounts()
+        logger.info(f"Found {len(accounts)} trading account(s)")
+
+        if password:
+            trade_service.unlock_trade(password=password)
+            logger.info("Trade unlocked successfully. REAL account access enabled.")
+        else:
+            trade_service.unlock_trade(password_md5=password_md5)
+            logger.info("Trade unlocked successfully (via MD5). REAL account access enabled.")
+    except RuntimeError as e:
+        logger.warning(
+            f"Failed to unlock trade: {e}. "
+            "REAL account access will not be available. "
+            "Use unlock_trade tool to retry manually."
+        )
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Manage moomoo connections lifecycle."""
+    moomoo_service = MoomooService()
+    moomoo_service.connect()
+
+    # Read security firm from environment (e.g., FUTUSG for Singapore, FUTUSECURITIES for HK)
+    security_firm = os.environ.get("MOOMOO_SECURITY_FIRM")
+    if security_firm:
+        logger.info(f"Using security firm: {security_firm}")
+
+    trade_service = TradeService(security_firm=security_firm)
+    trade_service.connect()
+
+    # Auto-unlock trade if password is configured in environment
+    _auto_unlock_trade(trade_service)
+
+    # Create market data service using the shared quote context
+    market_data_service = MarketDataService(quote_ctx=moomoo_service.quote_ctx)
+
+    try:
+        yield AppContext(
+            moomoo_service=moomoo_service,
+            trade_service=trade_service,
+            market_data_service=market_data_service,
+        )
+    finally:
+        trade_service.close()
+        moomoo_service.close()
+
+mcp = FastMCP(
+    "Moomoo Trading",
+    lifespan=app_lifespan,
+    dependencies=["moomoo-api", "pandas"] 
+)
+
+# Import tools to register them
+import moomoo_mcp.tools.system
+import moomoo_mcp.tools.account
+import moomoo_mcp.tools.market_data
+import moomoo_mcp.tools.trading
+
+def main():
+    """Entry point for the MCP server."""
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

moomoo_mcp/services/base_service.py

@@ -0,0 +1,39 @@
+from moomoo import OpenQuoteContext, RET_OK
+
+class MoomooService:
+    """Service to manage Moomoo API connections."""
+    
+    def __init__(self, host: str = '127.0.0.1', port: int = 11111):
+        self.host = host
+        self.port = port
+        self.quote_ctx: OpenQuoteContext | None = None
+
+    def connect(self) -> None:
+        """Initialize connection to OpenD."""
+        # OpenQuoteContext connects on initialization
+        self.quote_ctx = OpenQuoteContext(host=self.host, port=self.port)
+        
+    def close(self) -> None:
+        """Close connection."""
+        if self.quote_ctx:
+            self.quote_ctx.close()
+            self.quote_ctx = None
+
+    def check_health(self) -> dict[str, str]:
+        """Check connection health."""
+        if not self.quote_ctx:
+            return {"status": "disconnected", "error": "Context not initialized"}
+        
+        # Simple check: get_global_state or similar if available, or just heuristic
+        # moomoo-api doesn't have a direct 'ping', but we can check if socket is alive 
+        # or try a lightweight call.
+        # For now, if we instantiated it and it didn't raise, we assume connected 
+        # (though OpenQuoteContext is sync and might strict connect).
+        
+        # Let's try to get global state if possible, or just return connected.
+        # Actually moomoo-api often logs errors if connection fails.
+        # We can implement a try-catch around a simple call later.
+        
+        # Returning connected for now as a basic check.
+        # Real implementation would call something lightweight.
+        return {"status": "connected", "host": f"{self.host}:{self.port}"}

moomoo_mcp/services/market_data_service.py

@@ -0,0 +1,219 @@
+"""Market data service for accessing quote data via Moomoo API."""
+
+from moomoo import OpenQuoteContext, RET_OK, SubType, KLType, AuType
+
+
+class MarketDataService:
+    """Service to access market data via OpenQuoteContext.
+
+    This service provides methods to retrieve market quotes, historical K-line data,
+    snapshots, and order book data. It uses the shared OpenQuoteContext from MoomooService.
+    """
+
+    def __init__(self, quote_ctx: OpenQuoteContext):
+        """Initialize MarketDataService with an existing quote context.
+
+        Args:
+            quote_ctx: An already-connected OpenQuoteContext instance.
+        """
+        self.quote_ctx = quote_ctx
+
+    def subscribe(self, codes: list[str], sub_types: list[SubType]) -> None:
+        """Subscribe to real-time data for specified stocks and data types.
+
+        Args:
+            codes: List of stock codes (e.g., ['US.AAPL', 'HK.00700']).
+            sub_types: List of subscription types (e.g., [SubType.QUOTE, SubType.ORDER_BOOK]).
+
+        Raises:
+            RuntimeError: If subscription fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        ret, err = self.quote_ctx.subscribe(codes, sub_types, subscribe_push=False)
+        if ret != RET_OK:
+            raise RuntimeError(f"subscribe failed: {err}")
+
+    def get_stock_quote(self, codes: list[str]) -> list[dict]:
+        """Get real-time quotes for stocks.
+
+        This method automatically subscribes to the stocks before fetching quotes.
+        Returns current price, open, high, low, close, volume and other quote data.
+
+        Args:
+            codes: List of stock codes (e.g., ['US.AAPL']).
+
+        Returns:
+            List of quote dictionaries with price, volume, and other quote fields.
+
+        Raises:
+            RuntimeError: If quote retrieval fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        # Auto-subscribe before getting quotes
+        self.subscribe(codes, [SubType.QUOTE])
+
+        ret, data = self.quote_ctx.get_stock_quote(codes)
+        if ret != RET_OK:
+            raise RuntimeError(f"get_stock_quote failed: {data}")
+
+        return data.to_dict("records")
+
+    def get_historical_klines(
+        self,
+        code: str,
+        ktype: str = "K_DAY",
+        start: str | None = None,
+        end: str | None = None,
+        max_count: int = 100,
+        autype: str = "QFQ",
+    ) -> list[dict]:
+        """Get historical candlestick (K-line) data.
+
+        Args:
+            code: Stock code (e.g., 'US.AAPL').
+            ktype: K-line type. Options: K_1M, K_3M, K_5M, K_15M, K_30M, K_60M,
+                   K_DAY, K_WEEK, K_MON, K_QUARTER, K_YEAR.
+            start: Start date (YYYY-MM-DD format). Defaults to 365 days before end.
+            end: End date (YYYY-MM-DD format). Defaults to today.
+            max_count: Maximum number of candles to return (default 100).
+            autype: Adjustment type. Options: QFQ (forward), HFQ (backward), NONE.
+
+        Returns:
+            List of K-line dictionaries with time_key, open, high, low, close, volume.
+
+        Raises:
+            RuntimeError: If K-line retrieval fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        # Convert string ktype to enum
+        ktype_enum = getattr(KLType, ktype, KLType.K_DAY)
+        autype_enum = getattr(AuType, autype, AuType.QFQ)
+
+        ret, data, _ = self.quote_ctx.request_history_kline(
+            code=code,
+            start=start,
+            end=end,
+            ktype=ktype_enum,
+            autype=autype_enum,
+            max_count=max_count,
+        )
+        if ret != RET_OK:
+            raise RuntimeError(f"request_history_kline failed: {data}")
+
+        return data.to_dict("records")
+
+    def get_market_snapshot(self, codes: list[str]) -> list[dict]:
+        """Get market snapshot for multiple stocks.
+
+        This is efficient for batch queries and does not require subscription.
+        Returns current price, change, volume, and comprehensive market data.
+
+        Args:
+            codes: List of stock codes (up to 400). E.g., ['US.AAPL', 'US.TSLA'].
+
+        Returns:
+            List of snapshot dictionaries with last_price, open_price, high_price,
+            low_price, prev_close_price, volume, turnover, and more.
+
+        Raises:
+            RuntimeError: If snapshot retrieval fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        if not codes:
+            return []
+
+        ret, data = self.quote_ctx.get_market_snapshot(codes)
+        if ret != RET_OK:
+            raise RuntimeError(f"get_market_snapshot failed: {data}")
+
+        return data.to_dict("records")
+
+    def get_order_book(self, code: str, num: int = 10) -> dict:
+        """Get order book (market depth) for a stock.
+
+        This method automatically subscribes to the stock before fetching the order book.
+        Returns bid and ask price levels with volumes.
+
+        Args:
+            code: Stock code (e.g., 'HK.00700').
+            num: Number of price levels to return (default 10).
+
+        Returns:
+            Dictionary with 'code', 'Bid' (list of tuples), and 'Ask' (list of tuples).
+            Each tuple contains (price, volume, order_count, order_details).
+
+        Raises:
+            RuntimeError: If order book retrieval fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        # Auto-subscribe before getting order book
+        self.subscribe([code], [SubType.ORDER_BOOK])
+
+        ret, data = self.quote_ctx.get_order_book(code, num=num)
+        if ret != RET_OK:
+            raise RuntimeError(f"get_order_book failed: {data}")
+
+        return data
+
+    def get_user_security_group(self, group_type: int = 0) -> list[dict]:
+        """Get list of user-defined security groups (watchlists).
+
+        Args:
+            group_type: Type of groups to return. Options:
+                - 0: All groups (default)
+                - 1: Custom groups only
+                - 2: System groups only
+
+        Returns:
+            List of group dictionaries with group_name, group_id, etc.
+
+        Raises:
+            RuntimeError: If retrieval fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        from moomoo import UserSecurityGroupType
+
+        group_type_enum = UserSecurityGroupType.ALL
+        if group_type == 1:
+            group_type_enum = UserSecurityGroupType.CUSTOM
+        elif group_type == 2:
+            group_type_enum = UserSecurityGroupType.SYSTEM
+
+        ret, data = self.quote_ctx.get_user_security_group(group_type=group_type_enum)
+        if ret != RET_OK:
+            raise RuntimeError(f"get_user_security_group failed: {data}")
+
+        return data.to_dict("records")
+
+    def get_user_security(self, group_name: str) -> list[dict]:
+        """Get list of securities in a specific user-defined group (watchlist).
+
+        Args:
+            group_name: Name of the security group (e.g., 'Favorites').
+
+        Returns:
+            List of security dictionaries with code, name, lot_size, etc.
+
+        Raises:
+            RuntimeError: If retrieval fails.
+        """
+        if not self.quote_ctx:
+            raise RuntimeError("Quote context not connected")
+
+        ret, data = self.quote_ctx.get_user_security(group_name)
+        if ret != RET_OK:
+            raise RuntimeError(f"get_user_security failed: {data}")
+
+        return data.to_dict("records")