福彩3D 分析 MCP Server · 一个生产级 Agent 工具协议实践

把「福彩3D 开奖分析」做成一套 干净、可验证、可复盘 的 MCP（Model Context Protocol）工具服务器。 它不是「预测神器」，而是一个用来展示 Agent 工具协议工程能力 的真实项目：长任务闭环执行、状态/记忆管理、评测与安全边界。

⚠️ 诚实声明（请先读）

• 福彩3D 是独立均匀随机序列。在足够样本下，任何数字、和值、形态的出现频率都收敛到理论均匀分布；没有任何选号方法能提高中奖概率。

• 本系统的全部工具都不预测开奖号码。它们做的是：数据导入、统计检验、覆盖效率优化、资金风控、以及把结构化信号用你自己的大模型「翻译」成自然语言。

• 单注期望回报恒约为 −48%（返奖率约 52%）。长期参与的数学期望为负。理性投注，量力而行，切勿把它当作投资。

• 项目价值在于 工程实践，不在于「中奖」。下面的「三大工程支柱」才是它被设计出来的真正理由。

Related MCP server: Qwen3 MCP Server

为什么做这个项目（以及为什么适合作为 Agent 基础设施样本）

2026-08-04 DeepSeek 发布 Harness 内测招募，一场招募帖演变成 Agent 开源生态大摸底：769 位开发者、712 个开源仓库、合计 120 万 Stars，评论区秒变「开源 Agent 路演」。文章点名了 Agent 走向工程化需要持续升级的三张能力版图：

1. 长任务执行能力 —— Agent 能否稳定、持续地完成多步骤、多工具协作的真实任务；

2. 上下文与记忆管理 —— 长周期任务中如何保存状态、理解历史、正确调用已有信息；

3. 评测与安全 —— 工具调用是否可验证、是否有边界、能否被放心部署。

本项目恰好是这三张版图的具体落地样本：

把「预测」从系统里拿掉，反而让它能通过工程审查——这正是成熟 Agent 工具该有的样子。

架构

flowchart LR
  LLM[你的 LLM 客户端<br/>Cherry Studio / Claude Desktop / 任意 MCP 客户端] -- MCP stdio --> S[3dcaipiao-mcp]
  subgraph 阳核[阳核 · 纯本地数学引擎（零网络）]
    S --> B[base-tools · 3D 查询/统计/回测]
    S --> P[pascal · Pascal 数论特征]
    S --> Q[qcrm · 量子混沌 / RMT 信号]
    S --> SP[spin_drive · 自旋驱动层]
    S --> SE[sum_engine · 和值函数方程]
    S --> C[combination · 胆拖/覆盖优化/风控台账]
  end
  S --> L[ai_interpret_signal · 可选 LLM 叙述层]
  C --> D[(data/ 开奖数据 + 台账 JSON)]

• 阳核 6 大引擎全部为确定性本地计算（生成函数、卷积递推、RMT 随机矩阵、KS/卡方检验），不依赖任何外部 API 即可运行。

• 可选 LLM 叙述层 ai_interpret_signal：仅在用户配置了自己的大模型 API 后才联网；未配置时优雅降级为模板化解读，绝不静默造假。

快速开始（三步，无需编译）

本仓库已提供单文件打包产物 dist/3dcaipiao.mjs，只需 Node.js（≥18）即可运行，无需 npm install。

1. 在你的 MCP 客户端里「新建 → 添加 JSON」

以 Cherry Studio / Claude Desktop 为例，把下面这段加入 mcpServers（把路径改成你机器上的绝对路径）：

{
  "mcpServers": {
    "3dcaipiao": {
      "command": "node",
      "args": ["D:/Agent/3Dcaipiao/dist/3dcaipiao.mjs"],
      "env": {
        "LLM_BASE_URL": "https://api.deepseek.com/v1",
        "LLM_API_KEY": "sk-你的密钥",
        "LLM_MODEL": "deepseek-chat"
      }
    }
  }
}

• 只想用本地分析引擎？删掉整个 env 段即可，45 个数学工具照常工作。

• 想用你自己的大模型做自然语言解读？二选一：

  • （推荐）在客户端 JSON 里填 env 的 LLM_*；或

  • 复制 config.example.json 为 config.json，填入 llm.api_key，把它放在 dist/ 同级目录。

2. 让它"读懂"开奖数据

仓库已附带 100 期样例 data/sample_3d_100期开奖数据.md。直接让 Agent 调用：

import_draws  →  engine_sync_signal(budget=40)

engine_sync_signal 会一次性跑完：数据完整性、随机性（数字卡方）、和值分布（KS 检验）三大健康检查，并给出诚实结论（例如 data_ok / randomness_ok / sum_dist_ok 全 true，说明序列与理论随机分布无显著差异）。

3. 跑一条可追溯的前瞻实验（展示"长任务 + 记忆"）

spin_system_state(target_qihao="2026105")   # 锁定指纹、生成预测
spin_settle(entry_id="last", actual="3|2|1") # 隔期结算（不回测）
spin_experiment_report()                     # Wilson 95% 区间 vs 随机基线

这条链路完整呈现了三类工程能力：闭环执行 / 状态落盘 / 可验证评测。

工具总览（45+，全部 3D）

注：本仓库为纯福彩3D版本（已从上游裁剪掉双色球工具并清除其中的硬编码密钥），保持单一主题、干净可发布。

工程亮点（给评审/同行看）

1. 严格前瞻（Forward-Test）防数据泄露

spin_log / qcrm 台账采用指纹锁 + 隔期结算：预测时只写入 target_qihao 与指纹，结算时严格使用未来真实开奖比对。报告里的 Wilson 95% 置信区间 若包含随机基线，则结论必然是「未发现优于随机」——从源头杜绝「回测神话」。

2. 确定性状态与记忆

所有可变状态（台账、前瞻日志、演化状态）都是人类可读的 JSON，落盘到 data/（可用 FUCAI3D_DATA_DIR 环境变量重定向）。Agent 重启后状态不丢、实验可复现——这正是长周期任务「记忆管理」的最小可行实现。

3. 评测即安全边界

• 随机基线对照：任何「信号」都必须过 KS / 卡方 / SPRT，明确给出 ACCEPT_H0 / REJECT_H0。

• 多重检验校正：Bonferroni（α' = 0.05 / 配置数）防止反复试错碰巧显著。

• 预算护栏：kelly_guard 按凯利上限 + 红线（默认 ≤30 元）强制拒绝超预算/超风险方案。

• 诚实门控：自旋纯度 < 0.5 时 spin_yang_bridge 返回 COOLDOWN，绝不编造买入信号。

4. 可移植的协议实现

• 单个 .mjs 文件打包（esbuild），无依赖、无需联网、无需 npm install 即可被任意 MCP 客户端加载。

• 工具签名全部用 Zod 校验，输出为结构化 JSON，便于 Agent 直接消费与编排。

项目结构

3Dcaipiao/
├── dist/
│   └── 3dcaipiao.mjs          # 单文件打包产物（直接运行，无需编译）
├── src/                        # TypeScript 源码（阳核 6 引擎 + 可选 LLM 层）
│   ├── index.ts                # 入口：注册全部 3D 工具
│   ├── base-tools.ts           # 3D 查询/统计/回测
│   ├── pascal.ts               # Pascal 数论特征
│   ├── qcrm.ts                 # 量子混沌 / RMT
│   ├── spin_drive.ts           # 自旋驱动层 + 3D 前瞻闭环
│   ├── sum_engine.ts           # 和值函数方程
│   ├── combination.ts          # 胆拖/覆盖/风控/数据导入
│   └── llm.ts                  # 可选 LLM 叙述层
├── data/
│   └── sample_3d_100期开奖数据.md   # 100 期样例数据
├── config.example.json         # 大模型配置模板（复制为 config.json 填密钥）
├── mcp-config-example.json     # 客户端「添加 JSON」示例
├── package.json
├── LICENSE
└── README.md

从源码构建（可选）

npm install
npm run bundle     # esbuild → dist/3dcaipiao.mjs
node dist/3dcaipiao.mjs

配置说明

许可与责任

• MIT License。可自由使用、修改、再发布。

• 本项目为技术演示与工程研究用途。彩票有风险，请理性对待；作者不对任何投注结果负责。

关于本项目作为 DeepSeek Harness 内测代表仓库

本项目即作者提交给 DeepSeek Harness 内测招募（2026-08-04）的代表开源仓库。它不炫技、不承诺收益，而是用一个真实可运行的系统，展示 Agent 工具协议在「长任务闭环 / 状态记忆 / 评测安全」三个方向上的落地细节。欢迎同行 review、提 issue、拍砖。