@arong8888/tulip-aibot-mcp 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @arong8888/tulip-aibot-mcp
+
+郁金香AIBOT 的离线量化工具 MCP 服务器（Model Context Protocol）。
+
+**57 个纯计算工具**，全部只用 Python 标准库：不连接 MT5、不连券商、不读行情、不下单——你把行情/回测数据喂进来，它负责算。
+
+## 工具清单（五大类）
+
+- **技术指标**：MA/RSI/MACD/布林带/ATR/ADX/随机指标/CCI/OBV/VWAP/威廉%R/ROC/唐奇安/肯特纳/盘整指数/均线交叉/枢轴点/斐波那契
+- **风险与绩效**：夏普/索提诺/卡玛/Omega/溃疡指数/最大回撤及回撤事件表/VaR-CVaR/交易统计/PSR-DSR/Bootstrap 置信区间/蒙特卡洛破产概率
+- **仓位与风控**：风险仓位计算/凯利公式/敞口限额检查/回撤响应阶梯
+- **组合与筛选**：风险平价/最小方差配置/相关性矩阵聚类/多品种打分筛选/贪心组合搜索/分散化比率
+- **策略挖掘**：信号质量评估/因子IC与ICIR/参数高原稳健性/Walk-Forward切分/分状态绩效/优化器防过拟合排名/均值回归半衰期/配对交易扫描/方差比检验/Hurst指数
+- **代理工具**：安全计算器/文件搜索/备忘录；思维辅助：第一性原理/复利/贝叶斯/逆向思维
+
+## 运行要求
+
+- Node.js ≥ 16（仅作启动器）
+- **Python 3.10+**（标准库即可，无任何 pip 依赖）
+
+## 用法
+
+### 直接运行
+
+```bash
+npx @arong8888/tulip-aibot-mcp
+# 若 python 不在 PATH：
+PYTHON=/usr/local/bin/python3 npx @arong8888/tulip-aibot-mcp
+```
+
+### 接入 MCP 客户端（Claude Desktop / 其他）
+
+```json
+{
+  "mcpServers": {
+    "tulip-aibot-mcp": {
+      "command": "npx",
+      "args": ["-y", "@arong8888/tulip-aibot-mcp"]
+    }
+  }
+}
+```
+
+协议：JSON-RPC 2.0 over stdio，支持 `initialize` / `tools/list` / `tools/call` / `ping`。
+
+## 典型工作流
+
+1. 用任意行情源（如 MT5 的 `get_rates`）取收盘价数组
+2. 喂给本服务器的工具，例如：
+   - `rsi` / `macd` / `bollinger_bands` — 看指标
+   - `backtest_report` / `drawdown_episodes` — 评估回测
+   - `symbol_screener` — 多品种打分筛选
+   - `portfolio_allocation` (risk_parity) — 策略组合权重
+   - `param_robustness` — 检查参数是不是"刀锋参数"
+   - `sharpe_psr` (trials=N) — 校正多重试验的幸存者偏差
+
+## 注意
+
+- `note_taking` 工具会在安装目录旁写 `data/agent_notes.jsonl`
+- 所有工具确定性计算：蒙特卡洛/自助法使用显式随机种子，同输入同输出
+- 工具输出是**算术**，不是投资建议；`signal_quality`/`factor_ic` 的结论依赖你提供的前向收益无前视偏差

package/bin/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+const { spawn } = require("child_process");
+const path = require("path");
+
+const python = process.env.PYTHON || "python";
+const server = path.join(__dirname, "..", "python", "server.py");
+
+const child = spawn(python, [server], { stdio: "inherit" });
+child.on("error", () => {
+  console.error("[tulip-aibot-mcp] 启动失败：需要 Python 3.10+。");
+  console.error("[tulip-aibot-mcp] 可用环境变量 PYTHON 指定解释器，例如：");
+  console.error('[tulip-aibot-mcp]   set PYTHON=C:\\Python312\\python.exe && npx @arong8888/tulip-aibot-mcp');
+  process.exit(1);
+});
+child.on("exit", (code) => process.exit(code ?? 1));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@arong8888/tulip-aibot-mcp",
+  "version": "0.1.0",
+  "description": "郁金香AIBOT 离线量化工具 MCP 服务器：57个量化交易工具（技术指标/风险绩效/仓位管理/组合优化/回测报告/策略挖掘），纯标准库、不连接交易账户",
+  "license": "UNLICENSED",
+  "private": false,
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "quant",
+    "trading",
+    "technical-analysis",
+    "risk-management",
+    "backtest",
+    "mt5"
+  ],
+  "bin": {
+    "tulip-aibot-mcp": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "python/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/python/agent_tools.py

@@ -0,0 +1,230 @@
+"""AGENT 工具注册表：给 LLM 代理使用的安全离线工具。
+
+纯标准库；不连接 MT5、不下单。通过 call_tool 统一分发，
+list_tools 输出与 MCP tools/list 兼容的定义。
+"""
+import ast
+import fnmatch
+import json
+import math
+import os
+import re
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+BASE_PATH = Path(__file__).resolve().parent
+NOTES_FILE = BASE_PATH / "data" / "agent_notes.jsonl"
+MAX_NOTE_CHARS = 2000
+MAX_SEARCH_RESULTS = 200
+MAX_FILE_BYTES = 2_000_000
+MAX_EXPRESSION_CHARS = 200
+SKIP_DIRS = {".git", "__pycache__", "node_modules", ".venv", "venv", "logs"}
+
+
+class ToolError(ValueError):
+    """工具参数或执行失败；call_tool 转成 ok=False 的错误响应。"""
+
+
+_TOOLS: dict = {}
+
+
+def tool(name: str, description: str, properties: dict = None, required: list = None):
+    """把函数注册为带 JSON Schema 的工具。"""
+    def decorator(func):
+        _TOOLS[name] = {
+            "name": name,
+            "description": description,
+            "inputSchema": {
+                "type": "object",
+                "properties": properties or {},
+                "required": required or [],
+            },
+            "func": func,
+        }
+        return func
+    return decorator
+
+
+def has_tool(name: str) -> bool:
+    return name in _TOOLS
+
+
+def list_tools() -> List[dict]:
+    return [{k: spec[k] for k in ("name", "description", "inputSchema")}
+            for spec in _TOOLS.values()]
+
+
+def call_tool(name: str, arguments: Optional[dict]) -> dict:
+    """统一分发入口。永不抛异常：失败返回 {"ok": False, "error": ...}。"""
+    spec = _TOOLS.get(name)
+    if spec is None:
+        return {"ok": False, "error": f"未知工具: {name}"}
+    if arguments is None:
+        arguments = {}
+    if not isinstance(arguments, dict):
+        return {"ok": False, "error": "arguments 必须是对象"}
+    try:
+        return {"ok": True, "result": spec["func"](**arguments)}
+    except ToolError as exc:
+        return {"ok": False, "error": str(exc)}
+    except TypeError as exc:
+        return {"ok": False, "error": f"参数不匹配: {exc}"}
+
+
+# ---------- calculator ----------
+_ALLOWED_BINOPS = (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.FloorDiv, ast.Mod, ast.Pow)
+_ALLOWED_UNARY = (ast.USub, ast.UAdd)
+
+
+def _eval_node(node) -> float:
+    if isinstance(node, ast.Expression):
+        return _eval_node(node.body)
+    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) \
+            and not isinstance(node.value, bool):
+        return float(node.value)
+    if isinstance(node, ast.BinOp) and isinstance(node.op, _ALLOWED_BINOPS):
+        left, right = _eval_node(node.left), _eval_node(node.right)
+        if isinstance(node.op, ast.Pow) and abs(right) > 1000:
+            raise ToolError("幂指数过大")
+        try:
+            value = {
+                ast.Add: lambda: left + right,
+                ast.Sub: lambda: left - right,
+                ast.Mult: lambda: left * right,
+                ast.Div: lambda: left / right,
+                ast.FloorDiv: lambda: left // right,
+                ast.Mod: lambda: left % right,
+                ast.Pow: lambda: left ** right,
+            }[type(node.op)]()
+        except ZeroDivisionError:
+            raise ToolError("除数为零") from None
+        except OverflowError:
+            raise ToolError("计算结果溢出") from None
+        if not math.isfinite(value) or abs(value) > 1e100:
+            raise ToolError("结果超出安全范围")
+        return float(value)
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, _ALLOWED_UNARY):
+        value = _eval_node(node.operand)
+        return -value if isinstance(node.op, ast.USub) else value
+    raise ToolError("只允许数字与 + - * / // % ** 和括号")
+
+
+@tool(
+    "calculator",
+    "安全计算四则与幂运算，例如 (2+3)*4 或 2**10。只支持数字和运算符，不支持函数与变量。",
+    properties={"expression": {"type": "string", "description": "算术表达式"}},
+    required=["expression"],
+)
+def tool_calculator(expression: str) -> dict:
+    if not isinstance(expression, str) or not expression.strip():
+        raise ToolError("表达式不能为空")
+    if len(expression) > MAX_EXPRESSION_CHARS:
+        raise ToolError(f"表达式过长（上限{MAX_EXPRESSION_CHARS}字符）")
+    try:
+        tree = ast.parse(expression, mode="eval")
+    except SyntaxError:
+        raise ToolError("表达式语法错误") from None
+    value = _eval_node(tree)
+    return {"expression": expression, "value": value}
+
+
+# ---------- file_search ----------
+@tool(
+    "file_search",
+    "在项目内按正则搜索文本文件内容，返回文件路径、行号与行内容。仅限项目目录。",
+    properties={
+        "pattern": {"type": "string", "description": "正则表达式"},
+        "path": {"type": "string", "description": "项目内相对目录，默认项目根"},
+        "include": {"type": "string", "description": "文件名通配过滤，如 *.py"},
+        "max_results": {"type": "integer", "description": "最多返回条数，默认50，上限200"},
+    },
+    required=["pattern"],
+)
+def tool_file_search(pattern: str, path: str = ".", include: str = None,
+                     max_results: int = 50) -> dict:
+    if not isinstance(pattern, str) or not pattern:
+        raise ToolError("pattern 不能为空")
+    if not isinstance(max_results, int) or max_results < 1:
+        raise ToolError("max_results 必须是正整数")
+    max_results = min(max_results, MAX_SEARCH_RESULTS)
+    try:
+        regex = re.compile(pattern)
+    except re.error:
+        raise ToolError("正则表达式无效") from None
+    root = (BASE_PATH / str(path)).resolve()
+    if root != BASE_PATH and BASE_PATH not in root.parents:
+        raise ToolError("path 必须位于项目目录内")
+    matches: List[dict] = []
+    scanned = 0
+    truncated = False
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS)
+        for filename in sorted(filenames):
+            if include and not fnmatch.fnmatch(filename, include):
+                continue
+            file_path = Path(dirpath) / filename
+            try:
+                if file_path.stat().st_size > MAX_FILE_BYTES:
+                    continue
+                text = file_path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue  # 跳过二进制或不可读文件
+            scanned += 1
+            for line_number, line in enumerate(text.splitlines(), 1):
+                if regex.search(line):
+                    if len(matches) >= max_results:
+                        truncated = True
+                        break
+                    matches.append({
+                        "path": str(file_path.relative_to(BASE_PATH)),
+                        "line_number": line_number,
+                        "line": line[:300],
+                    })
+            if truncated:
+                break
+        if truncated:
+            break
+    return {"matches": matches, "scanned_files": scanned,
+            "total_returned": len(matches), "truncated": truncated}
+
+
+# ---------- note_taking ----------
+@tool(
+    "note_taking",
+    "给代理的持久备忘录：add 追加一条笔记，list 按时间倒序读取最近的笔记。",
+    properties={
+        "action": {"type": "string", "enum": ["add", "list"]},
+        "text": {"type": "string", "description": "add 时必填，最长2000字符"},
+        "limit": {"type": "integer", "description": "list 返回条数，默认20，上限200"},
+    },
+    required=["action"],
+)
+def tool_note(action: str, text: str = "", limit: int = 20) -> dict:
+    if action == "add":
+        if not isinstance(text, str) or not text.strip():
+            raise ToolError("笔记内容不能为空")
+        if len(text) > MAX_NOTE_CHARS:
+            raise ToolError(f"笔记过长（上限{MAX_NOTE_CHARS}字符）")
+        NOTES_FILE.parent.mkdir(parents=True, exist_ok=True)
+        entry = {
+            "id": str(time.time_ns()),
+            "text": text,
+            "created_at": datetime.now().isoformat(timespec="seconds"),
+        }
+        with open(NOTES_FILE, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        return {"action": "add", "note": entry}
+    if action == "list":
+        if not NOTES_FILE.exists():
+            return {"action": "list", "notes": [], "count": 0}
+        try:
+            entries = [json.loads(line) for line in
+                       NOTES_FILE.read_text(encoding="utf-8").splitlines() if line.strip()]
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ToolError(f"笔记文件损坏: {exc}") from None
+        limit = min(int(limit), 200) if isinstance(limit, int) and limit > 0 else 20
+        return {"action": "list", "notes": list(reversed(entries[-limit:])),
+                "count": len(entries)}
+    raise ToolError("action 必须是 add 或 list")