linker-luobo-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# linker-luobo-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+萝卜投研（DataYes!Pro, `r.datayes.com`）券商研报检索 MCP server。
+
+> 📘 并入 linker-szh hub / 多渠道聚合（萝卜 + 自研 + 其他渠道合成一个研报 MCP）的开发蓝图见 [`INTEGRATION.md`](./INTEGRATION.md)。
+
+定位：**纯抓取逻辑层**（登录 / 搜索 / 下载 / 结构化取数）。多用户编排、排队、日志、监控由上游服务器负责；本 MCP 内置限流退避作「第二道防线」。纯 HTTP 实现，无需浏览器。
+
+## 工具
+
+| 工具 | 说明 |
+|---|---|
+| `search_reports` | 研报检索：关键词 + 报告类型/特色标签/机构/内外资/行业/市场/页数/新财富/日期/排序/分页 |
+| `get_report_detail` | 单篇详情：作者、页数、完整摘要、核心指标 |
+| `download_report` | 获取单篇下载信息（受会话保护的 OSS 外链 + 有效期）；传 save_path 则落盘（调试用） |
+| `download_reports` | **批量**获取下载信息，内置限流+退避；传 save_dir 则落盘 |
+| `get_report_qa` | 平台 AI 生成的研报问答对（带页码） |
+| `get_report_indicators` | 核心指标（数值+日期+页码+是否预测） |
+| `get_report_charts` | 图表（标题+图片链+底层数据 xlsx 链） |
+| `list_report_orgs` | 机构词表（供 `org_name` 填准，支持关键字过滤） |
+
+> 分析提炼走 datayes 自带的 AI 结构化结果（qa/指标/图表/摘要），不解析 PDF。注意：并非每篇研报都有结构化数据，无则返回空数组。
+
+## 环境变量
+
+| 变量 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `DATAYES_ACCOUNT` | 是 | — | 登录账号（手机号/邮箱/账号） |
+| `DATAYES_PASSWORD` | 是 | — | 登录密码 |
+| `DATAYES_GW` | 否 | `https://gw.datayes.com` | 网关地址 |
+| `DATAYES_QPS` | 否 | `3` | 全局每秒最大请求数（令牌桶） |
+| `DATAYES_MIN_GAP_MS` | 否 | `0` | 请求间最小间隔毫秒（更保守可设 200+） |
+| `DATAYES_MAX_RETRY` | 否 | `3` | 403/429/网络错误的退避重试次数 |
+| `MCP_TRANSPORT` | 否 | `stdio` | `stdio` 或 `http` |
+| `MCP_PORT` | 否 | `8080` | HTTP 模式端口 |
+| `MCP_PATH` | 否 | `/mcp` | HTTP 模式路径 |
+
+登录内置：首次调用自动登录并内存缓存 `cloud-sso-token`，失效自动重登；并发登录去重。
+
+## 运行
+
+```bash
+npm install && npm run build
+
+# stdio（本地/客户端子进程）
+DATAYES_ACCOUNT=xxx DATAYES_PASSWORD=yyy node dist/index.js
+
+# HTTP 常驻（服务器托管，供你的调度层调用）
+MCP_TRANSPORT=http MCP_PORT=8080 DATAYES_ACCOUNT=xxx DATAYES_PASSWORD=yyy node dist/index.js
+```
+
+## 自测
+
+```bash
+# PowerShell
+$env:DATAYES_ACCOUNT="你的账号"; $env:DATAYES_PASSWORD="你的密码"; node selftest.mjs
+```
+
+跑完看到 `🎉 工具全部可用`，并在包目录生成下载的 PDF（可直接打开确认内容）。
+
+场景检验（模拟 agent 真实提问的端到端精准度 + 边界）：
+
+```bash
+$env:DATAYES_ACCOUNT="..."; $env:DATAYES_PASSWORD="..."; node scenarios.mjs
+```
+
+覆盖：期货日报精准、机构+品种周期词剖除、机构核实流程、外资港股、页数筛选收窄、结构化闭环、下载闭环、空查与非法 ID 边界（共 18 项）。
+
+## 客户端配置（Claude Code `.mcp.json`，stdio 模式）
+
+```json
+{
+  "mcpServers": {
+    "luobo-report": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "linker-luobo-mcp@latest"],
+      "env": {
+        "DATAYES_ACCOUNT": "your-account",
+        "DATAYES_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## 典型 agent 闭环
+
+检索 → 看摘要/问答/指标判断 → 单篇或批量下载到本地：
+
+1. `search_reports(query, report_types, org_name, start_date...)` 拿候选
+2. `get_report_detail` / `get_report_qa` / `get_report_indicators` 判断价值
+3. `download_report` 或 `download_reports(ids[], save_dir)` 落盘
+
+## 使用要点
+
+- `query` **只放主体词**（品种/公司/主题），如 `甲醇`/`LPG`/`宁德时代`。**勿放周期词**（日报/周报/月报）：`titleSeg` 分词会把它切出来匹配所有品种的同类报告，噪声爆增。（工具已内置剖除，即使误传也能兑正。）
+- 时间词（今天/本周）→ `start_date`/`end_date`；大宗商品/化工品种的日报/周报 → `report_types=['期货研究']`。
+  例：“查甲醇今天的日报” → `query='甲醇'` + `report_types=['期货研究']` + `start_date=end_date=今天`。
+- `org_name` 必须是机构词表里的精确名（如 `永安期货`/`华泰证券`）。不确定先调 `list_report_orgs`。
+- `report_types` 支持中文或英文 code，可多选。`search_reports` 的 `total` 服务端封顶 9999，深分页无意义，用日期/筛选收窄。
+- OSS 外链是会话绑定的（须带 cloud-sso-token），`download_report`/`download_reports` 默认返回外链元信息（对齐下载代理模式）；独立调试需真正落盘时传 `save_path`/`save_dir`。生产嵌入时走服务端下载代理（见 INTEGRATION.md）。
+
+接入 linker-szh 网关与通用研报类 MCP 规范见 [`INTEGRATION.md`](./INTEGRATION.md)。
+
+接口逆向细节见 [`RESEARCH.md`](./RESEARCH.md)。

package/dist/index.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * linker-luobo-mcp — 萝卜投研(DataYes!Pro) 研报 MCP · 网关客户端
+ *
+ * 本包是「瘦客户端」：不直连 datayes，不持有萝卜账号密码。
+ * 所有调用经链接者统一网关转发：
+ *   LUOBO_API_BASE = 网关入口，正式 https://hub.linker.net/api/v1/mcp/luobo
+ *   LUOBO_API_KEY  = IAM 签发的 lk_mcp_* 凭证，经 X-MCP-Key 出示
+ * 网关校验凭证、注入身份后转发到服务端 luobo 域；萝卜账号仅存在于服务端。
+ *
+ * 工具（对外契约，与直连版同名，保证切换无感）：
+ *   search_reports / get_report_detail / get_report_qa /
+ *   get_report_indicators / get_report_charts /
+ *   download_report / download_reports / list_report_orgs
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { z } from "zod";
+import http from "node:http";
+import { randomUUID } from "node:crypto";
+// ── 配置：网关入口 + 凭证 ────────────────────────────────────────────
+const BASE = (process.env.LUOBO_API_BASE ?? "").replace(/\/$/, "");
+const KEY = process.env.LUOBO_API_KEY ?? "";
+if (!BASE || !KEY) {
+    console.error("[error] LUOBO_API_BASE 和 LUOBO_API_KEY 必须设置");
+    console.error('  在 MCP 配置里填: "env": { "LUOBO_API_BASE": "https://hub.linker.net/api/v1/mcp/luobo", "LUOBO_API_KEY": "lk_mcp_..." }');
+    process.exit(1);
+}
+try {
+    new URL(BASE);
+}
+catch {
+    console.error(`[error] LUOBO_API_BASE 格式无效: "${BASE}"，必须是合法 http/https URL`);
+    process.exit(1);
+}
+const TIMEOUT_MS = Number(process.env.LUOBO_TIMEOUT_MS ?? "30000");
+// ── HTTP 封装：带 X-MCP-Key 打网关，返回 body.data ?? body ──────────────
+async function call(method, path, opts = {}) {
+    const url = new URL(BASE + path);
+    if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+            if (v !== undefined && v !== null && v !== "")
+                url.searchParams.set(k, String(v));
+        }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const headers = { "X-MCP-Key": KEY };
+        const init = { method, headers, signal: controller.signal };
+        if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(opts.body);
+        }
+        const res = await fetch(url.toString(), init);
+        if (res.status === 401)
+            throw new Error("鉴权失败（X-MCP-Key 无效或缺失）");
+        if (res.status === 403)
+            throw new Error("凭证无 luobo 域权限（需 mcp:luobo）");
+        if (!res.ok) {
+            const txt = await res.text().catch(() => "");
+            throw new Error(`网关 ${path} 返回 ${res.status}${txt ? ": " + txt.slice(0, 200) : ""}`);
+        }
+        const json = (await res.json());
+        // 后端统一 ApiResponse：{code,message,data}。code 非 0 视为业务失败。
+        if (typeof json.code === "number" && json.code !== 0 && json.code !== 200) {
+            throw new Error(String(json.message ?? `业务错误 code=${json.code}`));
+        }
+        return json.data ?? json;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(e) {
+    return { content: [{ type: "text", text: `错误: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+}
+// ── MCP Server ──────────────────────────────────────────────────────
+const server = new McpServer({ name: "linker-luobo-mcp", version: "0.2.0" });
+// 1) 检索
+server.registerTool("search_reports", {
+    title: "检索研报",
+    description: "按关键词/类型/机构/行业/市场/页数/日期检索萝卜投研(DataYes)券商研报。" +
+        "query 只放主体词(如'甲醇')，周期词(日报/周报/月报)不要进 query，改用 report_types + 日期范围，否则标题分词会污染召回。" +
+        "返回 report_id 可用于后续详情/问答/指标/图表/下载。total 上限 9999。",
+    inputSchema: {
+        query: z.string().optional().describe("主体关键词，如'甲醇'、'宁德时代'；勿放周期词"),
+        report_types: z.array(z.string()).optional().describe("报告类型，中文或 code：宏观研究/投资策略/行业研究/公司研究/晨会早报/债券研究/基金研究/期货研究/期权研究/外汇研究/新三板研究/金融工程/其他研究"),
+        report_sub_types: z.array(z.string()).optional().describe("特色标签/子类，如 公司深度/商品期货"),
+        org_name: z.string().optional().describe("机构精确名，先用 list_report_orgs 核实（如'华泰证券'）"),
+        org_type: z.string().optional().describe("内资 或 外资"),
+        industry: z.string().optional().describe("行业精确名，如'基础化工'"),
+        market: z.string().optional().describe("A股 / 港股 / 美股"),
+        min_pages: z.number().int().optional().describe("最少页数，用于过滤短报告"),
+        new_fortune_only: z.boolean().optional().describe("只看新财富分析师"),
+        start_date: z.string().optional().describe("发布起始 YYYY-MM-DD"),
+        end_date: z.string().optional().describe("发布结束 YYYY-MM-DD"),
+        sort_order: z.enum(["desc", "asc"]).optional().describe("按发布时间排序，默认 desc"),
+        page: z.number().int().min(1).optional().describe("页码，默认 1"),
+        page_size: z.number().int().min(1).max(50).optional().describe("每页条数，默认 20，上限 50"),
+    },
+}, async (a) => {
+    try {
+        return ok(await call("POST", "/search", { body: a }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// 2) 详情
+server.registerTool("get_report_detail", {
+    title: "研报详情",
+    description: "按 report_id 取研报详情：作者、页数、摘要、核心指标。",
+    inputSchema: { report_id: z.number().int().describe("研报 ID，来自 search_reports") },
+}, async ({ report_id }) => {
+    try {
+        return ok(await call("GET", "/report/detail", { query: { report_id } }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// 3) 问答
+server.registerTool("get_report_qa", {
+    title: "研报问答",
+    description: "取平台为该研报生成的结构化问答(QA)。返回空数组表示该报告无 QA，不代表接口异常。",
+    inputSchema: { report_id: z.number().int().describe("研报 ID") },
+}, async ({ report_id }) => {
+    try {
+        return ok(await call("GET", "/report/qa", { query: { report_id } }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// 4) 核心指标
+server.registerTool("get_report_indicators", {
+    title: "研报核心指标",
+    description: "取平台提取的核心指标(指标名/值/日期/页码/是否预测)。返回空数组表示该报告无结构化指标。",
+    inputSchema: { report_id: z.number().int().describe("研报 ID") },
+}, async ({ report_id }) => {
+    try {
+        return ok(await call("GET", "/report/indicators", { query: { report_id } }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// 5) 图表
+server.registerTool("get_report_charts", {
+    title: "研报图表",
+    description: "取研报内图表清单(标题/页码/图片URL/数据xlsx URL)。返回空数组表示该报告无结构化图表。",
+    inputSchema: { report_id: z.number().int().describe("研报 ID") },
+}, async ({ report_id }) => {
+    try {
+        return ok(await call("GET", "/report/charts", { query: { report_id } }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// 6) 下载（返回网关签名的下载代理 URL）
+server.registerTool("download_report", {
+    title: "获取研报下载链接",
+    description: "取该研报的下载代理 URL(由网关签名，默认 15 分钟有效)。" +
+        "返回的是可直接 GET 的代理链接(浏览器/agent 皆可)，不是萝卜裸 OSS 链。" +
+        "PDF 为可解析电子版(中文 CID 字体，取全文用 PyMuPDF/pdfplumber)。",
+    inputSchema: { report_id: z.number().int().describe("研报 ID") },
+}, async ({ report_id }) => {
+    try {
+        return ok(await call("POST", "/report/download", { body: { report_id } }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// 7) 批量下载（客户端聚合：逐个调 /report/download，串行带轻微间隔防风控）
+server.registerTool("download_reports", {
+    title: "批量获取下载链接",
+    description: "批量取多篇研报的下载代理 URL。客户端串行请求(带间隔防风控)，逐条返回 {report_id,url,expires_at} 或错误。",
+    inputSchema: {
+        report_ids: z.array(z.number().int()).min(1).max(50).describe("研报 ID 列表，上限 50"),
+        gap_ms: z.number().int().min(0).optional().describe("每次请求间隔毫秒，默认 300"),
+    },
+}, async ({ report_ids, gap_ms }) => {
+    const gap = gap_ms ?? 300;
+    const results = [];
+    for (let i = 0; i < report_ids.length; i++) {
+        const id = report_ids[i];
+        try {
+            results.push(await call("POST", "/report/download", { body: { report_id: id } }));
+        }
+        catch (e) {
+            results.push({ report_id: id, error: e instanceof Error ? e.message : String(e) });
+        }
+        if (gap > 0 && i < report_ids.length - 1)
+            await new Promise((r) => setTimeout(r, gap));
+    }
+    return ok({ count: results.length, results });
+});
+// 8) 机构词表
+server.registerTool("list_report_orgs", {
+    title: "机构名词表",
+    description: "查研报机构名词表(用于 search_reports 的 org_name 精确匹配)。" +
+        "建议传 prefix 过滤(如'华泰')，否则最多返回 100 条。机构名需与词表完全一致才能命中。",
+    inputSchema: { prefix: z.string().optional().describe("机构名关键字，如'华泰'") },
+}, async ({ prefix }) => {
+    try {
+        return ok(await call("GET", "/orgs", { query: { prefix } }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+// ── 传输：stdio(默认) / streamable-http ──────────────────────────────
+async function main() {
+    const transport = (process.env.MCP_TRANSPORT ?? "stdio").toLowerCase();
+    if (transport === "http") {
+        const port = Number(process.env.MCP_PORT ?? "8080");
+        const path = process.env.MCP_PATH ?? "/mcp";
+        const httpTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+        await server.connect(httpTransport);
+        const srv = http.createServer((req, res) => {
+            if (!req.url || new URL(req.url, "http://x").pathname !== path) {
+                res.writeHead(404).end();
+                return;
+            }
+            httpTransport.handleRequest(req, res).catch((e) => {
+                console.error("[http] handleRequest error", e);
+                if (!res.headersSent)
+                    res.writeHead(500).end();
+            });
+        });
+        srv.listen(port, () => console.error(`linker-luobo-mcp started (http) on :${port}${path}`));
+    }
+    else {
+        const stdio = new StdioServerTransport();
+        await server.connect(stdio);
+        console.error("linker-luobo-mcp started (stdio)");
+    }
+}
+main().catch((e) => {
+    console.error("[fatal]", e);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "linker-luobo-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP gateway client for 萝卜投研 (DataYes!Pro) research reports — search / detail / qa / indicators / charts / download via linker hub",
+  "author": "陈定钢",
+  "type": "module",
+  "bin": {
+    "linker-luobo-mcp": "dist/index.js"
+  },
+  "files": ["dist"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/linker/linker_mcp.git",
+    "directory": "packages/linker-luobo-mcp"
+  },
+  "homepage": "https://github.com/linker/linker_mcp/tree/main/packages/linker-luobo-mcp#readme",
+  "keywords": ["mcp", "datayes", "萝卜投研", "research-report", "研报"],
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2"
+  },
+  "engines": { "node": ">=18" },
+  "license": "MIT"
+}