futu-stock-mcp-server 0.1.0__tar.gz → 0.1.1__tar.gz

{futu_stock_mcp_server-0.1.0 → futu_stock_mcp_server-0.1.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Futu Stock MCP Server
+Copyright (c) 2024 yanghengxing
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{futu_stock_mcp_server-0.1.0 → futu_stock_mcp_server-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: futu-stock-mcp-server
-Version: 0.1.0
+Version: 0.1.1
 Summary: A Model Context Protocol (MCP) server for accessing Futu OpenAPI functionality
 Project-URL: Homepage, https://github.com/shuizhengqi1/futu-stock-mcp-server
 Project-URL: Documentation, https://github.com/shuizhengqi1/futu-stock-mcp-server#readme
@@ -216,22 +216,75 @@ Run formatting:
 ruff format .
 ```
 
-## Usage
+## 🔧 MCP Server 配置
 
-1. Start the server:
-```bash
-python -m futu_stock_mcp_server.server
+### 在 Claude Desktop 中配置
+
+1. **找到配置文件位置**：
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. **添加服务器配置**：
+```json
+{
+  "mcpServers": {
+    "futu-stock": {
+      "command": "futu-mcp-server",
+      "env": {
+        "FUTU_HOST": "127.0.0.1",
+        "FUTU_PORT": "11111"
+      }
+    }
+  }
+}
 ```
 
-2. Connect to the server using an MCP client:
+3. **如果使用虚拟环境或从源码运行**：
+```json
+{
+  "mcpServers": {
+    "futu-stock": {
+      "command": "/path/to/your/venv/bin/futu-mcp-server",
+      "env": {
+        "FUTU_HOST": "127.0.0.1",
+        "FUTU_PORT": "11111"
+      }
+    }
+  }
+}
+```
+
+或者使用 Python 模块方式：
+```json
+{
+  "mcpServers": {
+    "futu-stock": {
+      "command": "python",
+      "args": ["-m", "futu_stock_mcp_server.server"],
+      "cwd": "/path/to/futu-stock-mcp-server",
+      "env": {
+        "FUTU_HOST": "127.0.0.1",
+        "FUTU_PORT": "11111"
+      }
+    }
+  }
+}
+```
+
+### 在其他 MCP 客户端中配置
+
+#### 使用 Python MCP 客户端
 ```python
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
 async def main():
     server_params = StdioServerParameters(
-        command="python",
-        args=["src/server.py"]
+        command="futu-mcp-server",
+        env={
+            "FUTU_HOST": "127.0.0.1",
+            "FUTU_PORT": "11111"
+        }
     )
     
     async with stdio_client(server_params) as (read, write):
@@ -241,7 +294,120 @@ async def main():
             
             # List available tools
             tools = await session.list_tools()
+            print("Available tools:", [tool.name for tool in tools.tools])
+```
             
+#### 使用 Node.js MCP 客户端
+```javascript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "futu-mcp-server",
+  env: {
+    FUTU_HOST: "127.0.0.1",
+    FUTU_PORT: "11111"
+  }
+});
+
+const client = new Client({
+  name: "futu-stock-client",
+  version: "1.0.0"
+}, {
+  capabilities: {}
+});
+
+await client.connect(transport);
+```
+
+## 📋 使用方法
+
+### 1. 启动服务器（独立运行）
+```bash
+# 通过 pip 安装后
+futu-mcp-server
+
+# 或从源码运行
+python -m futu_stock_mcp_server.server
+```
+
+### 2. 环境变量配置
+创建 `.env` 文件或设置环境变量：
+```bash
+FUTU_HOST=127.0.0.1
+FUTU_PORT=11111
+LOG_LEVEL=INFO
+```
+
+### 3. 验证连接
+启动服务器后，你应该看到类似的日志：
+```
+2024-10-02 14:20:52 | INFO | Initializing Futu connection...
+2024-10-02 14:20:52 | INFO | Successfully initialized Futu connection
+2024-10-02 14:20:52 | INFO | Starting MCP server in stdio mode...
+2024-10-02 14:20:52 | INFO | Press Ctrl+C to stop the server
+```
+
+### 4. 在 AI 工具中使用
+配置完成后，重启 Claude Desktop 或其他 MCP 客户端，你就可以：
+- 查询股票实时行情
+- 获取历史K线数据
+- 订阅股票数据推送
+- 查询账户信息
+- 执行交易操作（需要交易权限）
+
+## 🔧 故障排除
+
+### 常见问题
+
+#### 1. 命令 `futu-mcp-server` 找不到
+```bash
+# 确保已正确安装
+pip install futu-stock-mcp-server
+
+# 或者检查是否在虚拟环境中
+which futu-mcp-server
+```
+
+#### 2. Ctrl+C 无法退出服务器
+- 新版本已修复此问题
+- 如果仍然遇到，可以使用 `kill -9 <pid>` 强制终止
+
+#### 3. 连接富途 OpenD 失败
+```bash
+# 检查 OpenD 是否运行
+netstat -an | grep 11111
+
+# 检查环境变量
+echo $FUTU_HOST
+echo $FUTU_PORT
+```
+
+#### 4. Claude Desktop 无法识别服务器
+- 确保配置文件路径正确
+- 检查 JSON 格式是否有效
+- 重启 Claude Desktop
+- 查看 Claude Desktop 的日志文件
+
+#### 5. 权限问题
+```bash
+# 确保有执行权限
+chmod +x ~/.local/bin/futu-mcp-server
+
+# 或者使用完整路径
+python -m futu_stock_mcp_server.server
+```
+
+### 日志调试
+启用详细日志：
+```bash
+export LOG_LEVEL=DEBUG
+futu-mcp-server
+```
+
+日志文件位置：`./logs/futu_server.log`
+            tools = await session.list_tools()
+
             # Call a tool
             result = await session.call_tool(
                 "get_stock_quote",

{futu_stock_mcp_server-0.1.0 → futu_stock_mcp_server-0.1.1}/README.md

@@ -174,22 +174,75 @@ Run formatting:
 ruff format .
 ```
 
-## Usage
+## 🔧 MCP Server 配置
 
-1. Start the server:
-```bash
-python -m futu_stock_mcp_server.server
+### 在 Claude Desktop 中配置
+
+1. **找到配置文件位置**：
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. **添加服务器配置**：
+```json
+{
+  "mcpServers": {
+    "futu-stock": {
+      "command": "futu-mcp-server",
+      "env": {
+        "FUTU_HOST": "127.0.0.1",
+        "FUTU_PORT": "11111"
+      }
+    }
+  }
+}
 ```
 
-2. Connect to the server using an MCP client:
+3. **如果使用虚拟环境或从源码运行**：
+```json
+{
+  "mcpServers": {
+    "futu-stock": {
+      "command": "/path/to/your/venv/bin/futu-mcp-server",
+      "env": {
+        "FUTU_HOST": "127.0.0.1",
+        "FUTU_PORT": "11111"
+      }
+    }
+  }
+}
+```
+
+或者使用 Python 模块方式：
+```json
+{
+  "mcpServers": {
+    "futu-stock": {
+      "command": "python",
+      "args": ["-m", "futu_stock_mcp_server.server"],
+      "cwd": "/path/to/futu-stock-mcp-server",
+      "env": {
+        "FUTU_HOST": "127.0.0.1",
+        "FUTU_PORT": "11111"
+      }
+    }
+  }
+}
+```
+
+### 在其他 MCP 客户端中配置
+
+#### 使用 Python MCP 客户端
 ```python
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
 async def main():
     server_params = StdioServerParameters(
-        command="python",
-        args=["src/server.py"]
+        command="futu-mcp-server",
+        env={
+            "FUTU_HOST": "127.0.0.1",
+            "FUTU_PORT": "11111"
+        }
     )
     
     async with stdio_client(server_params) as (read, write):
@@ -199,7 +252,120 @@ async def main():
             
             # List available tools
             tools = await session.list_tools()
+            print("Available tools:", [tool.name for tool in tools.tools])
+```
             
+#### 使用 Node.js MCP 客户端
+```javascript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "futu-mcp-server",
+  env: {
+    FUTU_HOST: "127.0.0.1",
+    FUTU_PORT: "11111"
+  }
+});
+
+const client = new Client({
+  name: "futu-stock-client",
+  version: "1.0.0"
+}, {
+  capabilities: {}
+});
+
+await client.connect(transport);
+```
+
+## 📋 使用方法
+
+### 1. 启动服务器（独立运行）
+```bash
+# 通过 pip 安装后
+futu-mcp-server
+
+# 或从源码运行
+python -m futu_stock_mcp_server.server
+```
+
+### 2. 环境变量配置
+创建 `.env` 文件或设置环境变量：
+```bash
+FUTU_HOST=127.0.0.1
+FUTU_PORT=11111
+LOG_LEVEL=INFO
+```
+
+### 3. 验证连接
+启动服务器后，你应该看到类似的日志：
+```
+2024-10-02 14:20:52 | INFO | Initializing Futu connection...
+2024-10-02 14:20:52 | INFO | Successfully initialized Futu connection
+2024-10-02 14:20:52 | INFO | Starting MCP server in stdio mode...
+2024-10-02 14:20:52 | INFO | Press Ctrl+C to stop the server
+```
+
+### 4. 在 AI 工具中使用
+配置完成后，重启 Claude Desktop 或其他 MCP 客户端，你就可以：
+- 查询股票实时行情
+- 获取历史K线数据
+- 订阅股票数据推送
+- 查询账户信息
+- 执行交易操作（需要交易权限）
+
+## 🔧 故障排除
+
+### 常见问题
+
+#### 1. 命令 `futu-mcp-server` 找不到
+```bash
+# 确保已正确安装
+pip install futu-stock-mcp-server
+
+# 或者检查是否在虚拟环境中
+which futu-mcp-server
+```
+
+#### 2. Ctrl+C 无法退出服务器
+- 新版本已修复此问题
+- 如果仍然遇到，可以使用 `kill -9 <pid>` 强制终止
+
+#### 3. 连接富途 OpenD 失败
+```bash
+# 检查 OpenD 是否运行
+netstat -an | grep 11111
+
+# 检查环境变量
+echo $FUTU_HOST
+echo $FUTU_PORT
+```
+
+#### 4. Claude Desktop 无法识别服务器
+- 确保配置文件路径正确
+- 检查 JSON 格式是否有效
+- 重启 Claude Desktop
+- 查看 Claude Desktop 的日志文件
+
+#### 5. 权限问题
+```bash
+# 确保有执行权限
+chmod +x ~/.local/bin/futu-mcp-server
+
+# 或者使用完整路径
+python -m futu_stock_mcp_server.server
+```
+
+### 日志调试
+启用详细日志：
+```bash
+export LOG_LEVEL=DEBUG
+futu-mcp-server
+```
+
+日志文件位置：`./logs/futu_server.log`
+            tools = await session.list_tools()
+
             # Call a tool
             result = await session.call_tool(
                 "get_stock_quote",

{futu_stock_mcp_server-0.1.0 → futu_stock_mcp_server-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "futu-stock-mcp-server"
-version = "0.1.0"
+version = "0.1.1"
 description = "A Model Context Protocol (MCP) server for accessing Futu OpenAPI functionality"
 readme = "README.md"
 license = {text = "MIT"}

{futu_stock_mcp_server-0.1.0 → futu_stock_mcp_server-0.1.1}/src/futu_stock_mcp_server/server.py

@@ -167,15 +167,24 @@ def signal_handler(signum, frame):
     """Handle process signals"""
     global _is_shutting_down
     if _is_shutting_down:
-        return
+        logger.info("Already shutting down, forcing exit...")
+        os._exit(1)
         
     # 只处理 SIGINT 和 SIGTERM
     if signum not in (signal.SIGINT, signal.SIGTERM):
         return
         
     logger.info(f"Received signal {signum}, cleaning up...")
-    cleanup_all()
-    sys.exit(0)
+    _is_shutting_down = True
+
+    try:
+        cleanup_all()
+        logger.info("Cleanup completed, exiting...")
+    except Exception as e:
+        logger.error(f"Error during cleanup: {e}")
+    finally:
+        # 强制退出，确保进程能够终止
+        os._exit(0)
 
 # Register cleanup functions
 atexit.register(cleanup_all)
@@ -1438,7 +1447,8 @@ async def get_current_time() -> Dict[str, Any]:
         'timezone': datetime.now().astimezone().tzname()
     }
 
-if __name__ == "__main__":
+def main():
+    """Main entry point for the futu-mcp-server command."""
     try:
         # 清理旧的进程和文件
         cleanup_stale_processes()
@@ -1457,19 +1467,25 @@ if __name__ == "__main__":
         if init_futu_connection():
             logger.info("Successfully initialized Futu connection")
             logger.info("Starting MCP server in stdio mode...")
+            logger.info("Press Ctrl+C to stop the server")
             try:
                 mcp.run(transport='stdio')
             except KeyboardInterrupt:
                 logger.info("Received keyboard interrupt, shutting down...")
-                sys.exit(0)
+                cleanup_all()
+                os._exit(0)
             except Exception as e:
                 logger.error(f"Error running server: {str(e)}")
-                sys.exit(1)
+                cleanup_all()
+                os._exit(1)
         else:
             logger.error("Failed to initialize Futu connection. Server will not start.")
-            sys.exit(1)
+            os._exit(1)
     except Exception as e:
         logger.error(f"Error starting server: {str(e)}")
         sys.exit(1)
     finally:
-        cleanup_all() 
+        cleanup_all() 
+
+if __name__ == "__main__":
+    main()