pingan-securities-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ping An Securities Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# pingan-securities-mcp
+
+平安证券 MCP Server。当前提供热股风向标（用户关注榜单），后续持续扩展行情、资讯、筛选等能力。
+
+> 数据仅供参考，不构成投资建议。
+
+## 前置：申请 API Key
+
+登录 [平安证券 AI Skill 开放平台](https://stock.pingan.com/huodong/aiskill/skillPage/index.html) 申请 API Key。
+
+## 配置
+
+在支持 MCP 的客户端（Claude Desktop、Cherry Studio 等）中加入：
+
+```json
+{
+  "mcpServers": {
+    "pingan-securities": {
+      "command": "npx",
+      "args": ["-y", "pingan-securities-mcp"],
+      "env": {
+        "PINGAN_SKILL_APIKEY": "你的 API Key"
+      }
+    }
+  }
+}
+```
+
+需要 Node.js 18 或以上。
+
+## 工具
+
+### `pa_hot_ranking` — 热股风向标
+
+平安证券用户群体的实时关注榜单，反映"大家都在关注什么"。
+
+| 参数 | 取值 | 默认 | 说明 |
+|---|---|---|---|
+| `board` | `search` / `watchlist` / `browse` / `surge` | 必填 | 热搜榜 / 加自选榜 / 浏览榜 / 飙升榜 |
+| `category` | `a_stock` / `etf` / `sector` / `hk_stock` / `convertible_bond` | `a_stock` | A股 / ETF / 板块概念 / 港股 / 可转债 |
+| `time_range` | `1h` / `24h` | `24h` | 统计时间窗 |
+| `size` | 1~100 | 10 | 返回条数 |
+
+四类榜单的含义：
+
+- **热搜榜 / 浏览榜 / 加自选榜**衡量绝对关注量，关注深度依次递增：看一眼 → 主动找 → 持续跟踪
+- **飙升榜**衡量关注度的增速，上榜标的绝对热度未必高
+
+榜单按热度排序，不是涨幅排序；反映平安证券用户行为，不代表全市场。
+
+**使用示例**
+
+- 「今天什么股票最热」→ `board=search`
+- 「大家都在加什么自选」→ `board=watchlist`
+- 「哪些板块关注度飙升」→ `board=surge, category=sector`
+- 「港股这一小时大家在看什么」→ `board=browse, category=hk_stock, time_range=1h`
+
+## 环境变量
+
+| 变量 | 必填 | 默认值 | 说明 |
+|---|---|---|---|
+| `PINGAN_SKILL_APIKEY` | 是 | — | API Key |
+| `PA_GATEWAY_BASE_URL` | 否 | `https://ai.stock.pingan.com` | 服务地址 |
+| `PA_GATEWAY_TIMEOUT` | 否 | `20` | 请求超时（秒） |
+| `PA_CHANNEL_ID` | 否 | — | 渠道标识 |
+
+## 许可
+
+MIT

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * 平安证券 MCP Server —— STDIO 传输。
+ *
+ * 本文件只做两件事：创建 server、逐个注册工具。业务逻辑全在 tools/ 下，每个工具一个文件。
+ * 新增工具：在 tools/ 下建文件导出 registerXxx(server)，然后在下面加一行。
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerHotStock } from "./tools/hot-stock.js";
+export const SERVER_NAME = "pingan-securities";
+export const SERVER_VERSION = "1.0.0";
+const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    instructions: "平安证券数据服务。涉及市场热度、榜单、行情等问题时，必须调用工具获取实时数据，" +
+        "不要凭记忆回答具体排名、数字或涨跌幅。所有数据仅供参考，不构成投资建议。",
+});
+// ---- 工具注册（按上线顺序追加）----
+registerHotStock(server);
+async function main() {
+    // STDIO 下 stdout 是协议通道，任何 console.log 都会破坏 JSON-RPC 消息流。日志只能走 stderr。
+    await server.connect(new StdioServerTransport());
+    console.error(`[${SERVER_NAME}] MCP server started (stdio) v${SERVER_VERSION}`);
+}
+main().catch((e) => {
+    console.error(`[${SERVER_NAME}] fatal:`, e);
+    process.exit(1);
+});

package/dist/shared/core.js

@@ -0,0 +1,29 @@
+/**
+ * 认证与错误类型。所有工具共用。
+ */
+export const APIKEY_ENV = "PINGAN_SKILL_APIKEY";
+export const APPLY_URL = "https://stock.pingan.com/huodong/aiskill/skillPage/index.html";
+/** 预期内的业务失败。返回 isError=true 让模型读到并自纠正，而不是抛成协议错误。 */
+export class ToolError extends Error {
+}
+/** 取用户 Key。STDIO 模式下由宿主注入环境变量。绝不放进工具入参——那会让 Key 进模型上下文。 */
+export function apiKey() {
+    const key = (process.env[APIKEY_ENV] ?? "").trim();
+    if (!key) {
+        throw new ToolError(`未配置平安证券 API Key。请设置环境变量 ${APIKEY_ENV}。申请地址：${APPLY_URL}`);
+    }
+    return key;
+}
+export const ok = (text) => ({ content: [{ type: "text", text }] });
+export const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** 统一包装：所有预期内的失败都走 isError，不让异常冒泡成协议错误。 */
+export async function guard(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        if (e instanceof ToolError)
+            return err(e.message);
+        return err(`查询失败：${e?.message ?? String(e)}`);
+    }
+}

package/dist/shared/format.js

@@ -0,0 +1,56 @@
+/**
+ * 格式化工具。所有工具共用。
+ *
+ * 工具返回的每个字符都进模型上下文，所以统一走窄表、带单位、大数折算、null 省略。
+ */
+export const DISCLAIMER = "数据来源：平安证券。仅供参考，不构成投资建议。";
+const toNum = (v) => {
+    if (v === null || v === undefined || v === "")
+        return null;
+    const f = Number(v);
+    return Number.isFinite(f) ? f : null;
+};
+const group = (f, digits) => f.toLocaleString("en-US", { minimumFractionDigits: digits, maximumFractionDigits: digits });
+/** digits 不传时按量级自适应：ETF/低价股 3 位小数，个股 2 位。 */
+export function num(v, digits) {
+    const f = toNum(v);
+    if (f === null)
+        return typeof v === "string" && v ? v : "—";
+    return group(f, digits ?? (Math.abs(f) < 10 ? 3 : 2));
+}
+/** 输入已是百分数（1.48 表示 1.48%）。 */
+export function pct(v) {
+    const f = toNum(v);
+    if (f === null)
+        return "—";
+    return `${f >= 0 ? "+" : ""}${f.toFixed(2)}%`;
+}
+/** 输入是小数比例（0.0148 表示 1.48%）。网关不同接口两种都有，调用方按接口文档选。 */
+export function ratioPct(v) {
+    const f = toNum(v);
+    if (f === null)
+        return "—";
+    return pct(f * 100);
+}
+/** 元 / 股 折算成亿、万。 */
+export function big(v) {
+    const f = toNum(v);
+    if (f === null)
+        return "—";
+    const a = Math.abs(f);
+    if (a >= 1e8)
+        return `${group(f / 1e8, 2)}亿`;
+    if (a >= 1e4)
+        return `${group(f / 1e4, 2)}万`;
+    return group(f, 0);
+}
+export function table(headers, rows) {
+    const out = [`| ${headers.join(" | ")} |`, `|${headers.map(() => "---").join("|")}|`];
+    for (const r of rows)
+        out.push(`| ${r.join(" | ")} |`);
+    return out.join("\n");
+}
+/** 免责声明在服务端强制注入，不依赖宿主平台的 system prompt。 */
+export function withDisclaimer(text) {
+    return `${text}\n\n_${DISCLAIMER}_`;
+}

package/dist/shared/gateway.js

@@ -0,0 +1,83 @@
+/**
+ * 网关调用层。所有工具共用，按 skill 参数化。
+ *
+ * 本进程是纯代理：Key 从环境变量进来，原样透传给网关，不解析、不落地、不写日志。
+ */
+import { ToolError } from "./core.js";
+const BASE_URL = (process.env.PA_GATEWAY_BASE_URL ?? "https://ai.stock.pingan.com").replace(/\/+$/, "");
+const CHANNEL_ID = process.env.PA_CHANNEL_ID;
+/** 宿主平台的工具超时通常 10~30s，这里必须短于它，否则模型只会看到一个没有语义的失败。 */
+const TIMEOUT_MS = Number(process.env.PA_GATEWAY_TIMEOUT ?? 20) * 1000;
+export async function call(ep, path, payload, apiKey) {
+    const requestId = globalThis.crypto.randomUUID();
+    const url = `${BASE_URL}/${ep.prefix}/${path}`;
+    const headers = {
+        "X-API-Key": apiKey,
+        "Content-Type": "application/json",
+        "X-Skill-ID": ep.skillId,
+        "X-Request-ID": requestId,
+        requestId,
+    };
+    if (CHANNEL_ID)
+        headers.channelId = CHANNEL_ID;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+    let resp;
+    try {
+        resp = await fetch(url, { method: "POST", headers, body: JSON.stringify(payload), signal: ac.signal });
+    }
+    catch (e) {
+        if (e?.name === "AbortError")
+            throw new ToolError("服务响应超时，请稍后重试；不要重复发起同一查询。");
+        throw new ToolError(`网络异常：${e?.name ?? "Error"}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (resp.status === 401) {
+        throw new ToolError("未提供 API Key。请设置环境变量 PINGAN_SKILL_APIKEY，" +
+            "申请地址：https://stock.pingan.com/huodong/aiskill/skillPage/index.html");
+    }
+    if (resp.status === 403)
+        throw new ToolError("API Key 无效或无此接口权限。请到平安证券开放平台确认 Key 状态与授权范围。");
+    if (resp.status === 429) {
+        const code = await safeField(resp, "error_code");
+        if (code === "RATE_LIMIT_EXCEEDED")
+            throw new ToolError("调用频率超限，请稍后重试；本轮不要再重复调用。");
+        if (code === "DAILY_QUOTA_EXCEEDED")
+            throw new ToolError("今日调用次数已达上限，请明日再试或联系平安证券提升配额。");
+        throw new ToolError("请求超过限制，请稍后重试。");
+    }
+    if (resp.status === 503)
+        throw new ToolError("服务暂时不可用，请稍后重试。");
+    if (resp.status >= 400)
+        throw new ToolError(`服务返回异常状态 ${resp.status}。`);
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        throw new ToolError("服务返回内容无法解析。");
+    }
+    // 网关层错误码。原文透出——这是模型自纠正参数的主要依据，不做脱敏。
+    if (body?.code !== undefined && body.code !== 0 && body.code !== null) {
+        throw new ToolError(body?.error_message || "接口调用失败。");
+    }
+    let data = body?.data ?? body;
+    // 业务层错误码：部分接口在 data 里再包一层 status/errmsg/results
+    if (data && typeof data === "object" && "status" in data && data.status !== 1) {
+        throw new ToolError(data.errmsg || "接口返回失败。");
+    }
+    if (data && typeof data === "object" && "results" in data) {
+        data = data.results ?? {};
+    }
+    return data;
+}
+async function safeField(resp, field) {
+    try {
+        return (await resp.json())?.[field] ?? "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/tools/hot-stock.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { apiKey, guard, ToolError } from "../shared/core.js";
+import { call } from "../shared/gateway.js";
+import { ratioPct, table, withDisclaimer } from "../shared/format.js";
+const EP = { prefix: "restapi/hotstock", skillId: "hot-stock" };
+const PATH = "isspContentService/hotStock/list";
+// ---- 语义化枚举 → 网关码 ----
+const BOARDS = {
+    search: { code: "hot_stock", label: "热搜榜", note: "用户主动搜索的标的，衡量绝对关注量" },
+    watchlist: { code: "hot_select", label: "加自选榜", note: "用户加入自选持续跟踪的标的，衡量绝对关注量，是关注深度最高的一档" },
+    browse: { code: "hot_watch", label: "浏览榜", note: "用户浏览过的标的，衡量绝对关注量，是关注深度最浅的一档" },
+    surge: { code: "hot_surge", label: "飙升榜", note: "关注度增速最快的标的，衡量的是变化速度而非绝对量，上榜标的绝对热度未必高" },
+};
+const CATEGORIES = {
+    a_stock: { code: "aStock", label: "A股" },
+    etf: { code: "etf", label: "ETF" },
+    sector: { code: "block", label: "板块概念" },
+    hk_stock: { code: "hkStock", label: "港股" },
+    convertible_bond: { code: "bond", label: "可转债" },
+};
+const TIME_RANGES = {
+    "1h": { code: 1, label: "近 1 小时" },
+    "24h": { code: 2, label: "近 24 小时" },
+};
+// ---- 返参裁剪 ----
+function format(data, board, category, timeRange) {
+    const list = data?.list ?? [];
+    const b = BOARDS[board];
+    const c = CATEGORIES[category];
+    const t = TIME_RANGES[timeRange];
+    if (!list.length) {
+        return `${b.label}（${c.label}，${t.label}）暂无数据。`;
+    }
+    // 网关返回 "2026-09-02 09:00:00"，skill 脚本一直只保留日期部分，这里保持一致
+    const date = String(data?.updateTime ?? "—").slice(0, 10);
+    const head = `**${b.label} · ${c.label} · ${t.label}**（数据日期 ${date}）\n` +
+        `${b.note}。按热度排序，不是涨幅排序。\n\n`;
+    const rows = list.map((it, i) => {
+        const code = `${it.marketType ?? ""}${it.stockCode ?? ""}`.trim();
+        const name = code ? `${it.name ?? "—"}(${code})` : (it.name ?? "—");
+        // chg 是小数比例字符串（"-0.0391" = -3.91%），必须乘 100
+        return [String(i + 1), name, ratioPct(it.chg)];
+    });
+    return head + table(["排名", "名称(代码)", "涨跌幅"], rows);
+}
+// ---- 注册 ----
+export function registerHotStock(server) {
+    server.registerTool("pa_hot_ranking", {
+        title: "热股风向标",
+        description: "查询平安证券用户群体的实时关注榜单，回答「今天什么最热」「大家都在搜/看/加自选什么」「哪些标的关注度飙升」这类问题。" +
+            "四类榜单：search 热搜榜（用户在搜）、watchlist 加自选榜（用户在持续跟踪）、browse 浏览榜（用户在看）、" +
+            "surge 飙升榜（关注度增速最快，不代表绝对热度高）。前三个按绝对关注量排，surge 按增速排，含义不同。" +
+            "支持 A股/ETF/板块概念/港股/可转债，用户没说品种默认 A股；说「刚刚/现在/这一小时」用 1h，否则 24h。" +
+            "榜单反映平安证券用户行为，不代表全市场，也不是涨幅排名。需要某只标的的行情/K线/资金流向请用行情工具。",
+        inputSchema: {
+            board: z
+                .enum(["search", "watchlist", "browse", "surge"])
+                .describe("榜单类型：search 热搜榜、watchlist 加自选榜、browse 浏览榜、surge 飙升榜（关注度增速）"),
+            category: z
+                .enum(["a_stock", "etf", "sector", "hk_stock", "convertible_bond"])
+                .default("a_stock")
+                .describe("品种：a_stock A股（默认）、etf、sector 板块概念、hk_stock 港股、convertible_bond 可转债"),
+            time_range: z
+                .enum(["1h", "24h"])
+                .default("24h")
+                .describe("统计时间窗：24h（默认）或 1h。用户说「刚刚/现在/这一小时」时用 1h"),
+            size: z.number().int().min(1).max(100).default(10).describe("返回条数，1~100，默认 10"),
+        },
+    }, async ({ board, category, time_range, size }) => guard(async () => {
+        const b = BOARDS[board];
+        const c = CATEGORIES[(category ?? "a_stock")];
+        const t = TIME_RANGES[(time_range ?? "24h")];
+        if (!b || !c || !t)
+            throw new ToolError("参数取值不在允许范围内，请按 schema 中的枚举值传参。");
+        const data = await call(EP, PATH, { moduleCode: b.code, typeCode: c.code, timeRange: t.code, page: 1, size: size ?? 10 }, apiKey());
+        return withDisclaimer(format(data, board, category, time_range));
+    }));
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pingan-securities-mcp",
+  "version": "1.0.0",
+  "description": "平安证券 MCP Server — 热股风向标（热搜/加自选/浏览/飙升榜），持续扩展中",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "model-context-protocol",
+    "stock",
+    "a-share",
+    "hk-stock",
+    "etf",
+    "market-data",
+    "finance",
+    "pingan",
+    "平安证券",
+    "热股",
+    "热搜榜"
+  ],
+  "license": "MIT",
+  "author": "Ping An Securities",
+  "type": "module",
+  "bin": {
+    "pingan-securities-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build && npm run smoke",
+    "start": "node dist/index.js",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.6.0"
+  }
+}