linker-position-mcp 0.1.0

package/README.md

@@ -0,0 +1,264 @@
+# linker-position-mcp
+
+Linker 持仓 + 盈亏 + VAR 风险查询 MCP Server。
+
+面向 AI Agent / 大模型，提供公司级和个人级的持仓、盈亏、VAR 风险查询能力。所有工具只认人名不认 ID，对大模型友好。
+
+## 快速开始
+
+### 环境变量
+
+```
+TRADING_API_BASE=http://hub.linker.net/trading-api
+TRADING_API_KEY=trading-prod-20260323
+```
+
+### 配置方式
+
+**npx（发布后）：**
+
+```json
+{
+  "mcpServers": {
+    "linker-position": {
+      "command": "npx",
+      "args": ["-y", "linker-position-mcp@latest"],
+      "env": {
+        "TRADING_API_BASE": "http://hub.linker.net/trading-api",
+        "TRADING_API_KEY": "trading-prod-20260323"
+      }
+    }
+  }
+}
+```
+
+**本地开发（直接用编译产物）：**
+
+```json
+{
+  "mcpServers": {
+    "linker-position": {
+      "command": "node",
+      "args": ["C:/Users/94503/Documents/GitHub/linker_mcp/packages/linker-position-mcp/dist/index.js"],
+      "env": {
+        "TRADING_API_BASE": "http://hub.linker.net/trading-api",
+        "TRADING_API_KEY": "trading-prod-20260323"
+      }
+    }
+  }
+}
+```
+
+## 工具列表
+
+| Tool | 说明 | 参数 |
+|------|------|------|
+| `get_pnl_overview` | 公司整体盈亏+持仓+VAR 快照 | 无 |
+| `get_owner_detail` | 某人持仓+盈亏+VAR 明细 | `owner: string` |
+| `get_risk_status` | VAR 风险状态 | `owner?: string` |
+| `list_owners` | 列出所有持仓人姓名 | 无 |
+
+## 覆盖维度
+
+| 维度 | 全局 | 某人 |
+|------|------|------|
+| 持仓+盈亏 | `get_pnl_overview()` — 各人一行汇总排名 | `get_owner_detail(owner)` — 策略→legs 明细 |
+| VAR 风险 | `get_risk_status()` — 全员概览+超限告警 | `get_risk_status(owner)` — 某人 30 日趋势 |
+| 辅助 | `list_owners()` — 确认人名 | — |
+
+## 场景对照表
+
+| 用户问 | 调哪个工具 |
+|--------|-----------|
+| "公司现在整体什么情况" | `get_pnl_overview` |
+| "各人盈亏排名" | `get_pnl_overview` |
+| "谁在赚谁在亏" | `get_pnl_overview` |
+| "任志华持仓什么" | `get_owner_detail(owner:"任志华")` |
+| "任志华赚了多少" | `get_owner_detail(owner:"任志华")` |
+| "某人各策略盈亏明细" | `get_owner_detail(owner:"某人")` |
+| "某人浮盈多少" | `get_owner_detail(owner:"某人")` |
+| "谁的 VAR 超限了" | `get_risk_status()` |
+| "全员风险概览" | `get_risk_status()` |
+| "某人 VAR 趋势" | `get_risk_status(owner:"某人")` |
+| "有哪些交易员" | `list_owners` |
+
+## 各工具返回结构
+
+### get_pnl_overview
+
+```json
+{
+  "company": {
+    "realized_pnl": 89555573.88,
+    "floating_pnl": -37185340.99,
+    "total_pnl": 52370232.89,
+    "var_used": 52398632.93,
+    "var_remain": 23451367.07,
+    "var_limit": "7585万",
+    "var_usage": "69%"
+  },
+  "owners": [
+    {
+      "owner": "任志华",
+      "active_strategies": 15,
+      "total_strategies": 83,
+      "total_pnl": 101024976.04,
+      "floating_pnl": 13381939.35,
+      "var": 12942379.87,
+      "var_usage": 0.43,
+      "alert": "normal"
+    }
+  ]
+}
+```
+
+### get_owner_detail
+
+```json
+{
+  "owner": "任志华",
+  "realized_pnl": 190948992.89,
+  "floating_pnl": 13381939.35,
+  "total_pnl": 204330932.24,
+  "var": {
+    "total": 12942379.87,
+    "hedge": null,
+    "arbitrage": null,
+    "outright": 12942379.87
+  },
+  "var_limit": 30000000,
+  "var_usage_rate": 0.43,
+  "var_alert": "normal",
+  "active_strategies": 15,
+  "total_strategies": 83,
+  "strategies": [
+    {
+      "strategy": "AU_单边策略_趋势跟踪_AU2606",
+      "category": "单边策略",
+      "product": "AU",
+      "total_pnl": -6368497,
+      "floating_pnl": -4397171,
+      "var": 3200000,
+      "legs": [
+        {
+          "contract": "AU2608",
+          "direction": "BUY",
+          "remaining_qty": 36,
+          "avg_price": 996.38,
+          "market_price": 874.24,
+          "unrealized_pnl": -4397171,
+          "realized_pnl": 0
+        }
+      ]
+    }
+  ]
+}
+```
+
+### get_risk_status（全员）
+
+```json
+{
+  "owners": [
+    {
+      "owner": "汪浩",
+      "department": "交易三部",
+      "var_value": 1318.1,
+      "var_limit": 150,
+      "usage_rate": 8.79,
+      "alert_level": "overlimit"
+    }
+  ],
+  "alerts": [
+    {
+      "owner": "汪浩",
+      "var_value": 1318.1,
+      "var_limit": 150,
+      "usage_rate": 8.79,
+      "alert_level": "overlimit"
+    }
+  ]
+}
+```
+
+### get_risk_status（某人趋势）
+
+```json
+{
+  "owner": "黄皓生",
+  "days": 30,
+  "trend": [
+    { "date": "2026-06-20", "var_value": 52.3, "var_limit": 300, "usage_rate": 0.17, "alert_level": "normal" },
+    { "date": "2026-07-19", "var_value": 64.29, "var_limit": 300, "usage_rate": 0.21, "alert_level": "normal" }
+  ]
+}
+```
+
+### list_owners
+
+```json
+["任志华", "于熙", "何佳驹", "吴培", "周菲", "..."]
+```
+
+## 技术细节
+
+- **数据来源**：所有数据走服务端聚合接口，不拉明细（无 60 万行查询）
+  - `/api/v1/pnl/report` — 持仓 + 盈亏 + VAR（服务端聚合 owner→strategies→legs）
+  - `/api/v1/risk/dashboard/overview` — VAR 概览
+  - `/api/v1/risk/dashboard/alerts` — 超限告警
+  - `/api/v1/risk/dashboard/history` — VAR 趋势
+  - `/api/v1/owners` — 持仓人列表
+- **认证**：`X-API-Key` header
+- **只读**：所有工具 readOnly，不做任何写操作
+- **owner 解析**：内部缓存 ownerMap（name↔id），用户只需传姓名
+
+## 与 trading-mcp-v2 的关系
+
+本 MCP 专注**持仓/盈亏/风险**查询，可独立运行，也可与 trading-mcp-v2 并行使用。
+
+| 能力 | trading-mcp-v2 | position-mcp |
+|------|---------------|--------------|
+| 持仓+盈亏快照 | ✅ get_owner_pnl/get_pnl_summary | ✅ get_pnl_overview/get_owner_detail |
+| VAR 风险仪表盘 | 部分（嵌在盈亏报告里） | ✅ 独立维度 get_risk_status |
+| 策略详情/公式/评分 | ✅ | ❌ |
+| 行情/历史价格 | ✅ | ❌ |
+| 经济数据库 | ✅ | ❌ |
+| 外盘实时行情 | ✅ | ❌ |
+
+## 开发
+
+```bash
+cd packages/linker-position-mcp
+npm install
+npm run build     # tsc 编译
+npm run watch     # 开发热编译
+node test_tool.mjs  # 运行工具测试
+```
+
+## 测试
+
+```bash
+node test_tool.mjs
+```
+
+输出示例：
+```
+=== linker-position-mcp Tool Tests ===
+═══ Test 1: list_owners ═══
+✓ 39 owners found
+
+═══ Test 2: get_pnl_overview ═══
+✓ grand_total: realized=89555573, floating=-37185340, total=52370232
+✓ 37 owners summarized
+
+═══ Test 3: get_owner_detail(任志华) ═══
+✓ 任志华: 15 active strategies, total_pnl=204330932
+
+═══ Test 4: get_risk_status (全员) ═══
+✓ 25 owners, 5 alerts (overlimit)
+
+═══ Test 5: get_risk_status(任志华) — VAR趋势 ═══
+✓ 任志华 近30日无VAR记录
+
+✅ All tests passed
+```

package/dist/index.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * Linker Position & PnL MCP Server
+ *
+ * 4 tools covering: portfolio overview, owner detail, risk status, owner listing.
+ * All read-only. Uses server-side aggregated endpoints only (no 600k+ row pulls).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const BASE = (process.env.TRADING_API_BASE ?? "").replace(/\/$/, "");
+const KEY = process.env.TRADING_API_KEY ?? "";
+if (!BASE || !KEY) {
+    process.stderr.write("TRADING_API_BASE and TRADING_API_KEY are required\n");
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+async function api(path, params) {
+    const url = new URL(BASE + path);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v)
+                url.searchParams.set(k, v);
+        }
+    }
+    const res = await fetch(url.toString(), { headers: { "X-API-Key": KEY } });
+    if (!res.ok)
+        throw new Error(`API ${path} returned ${res.status}`);
+    const body = (await res.json());
+    return body.data ?? body;
+}
+let ownerCache = null;
+async function getOwnerMap() {
+    if (ownerCache)
+        return ownerCache;
+    const items = (await api("/api/v1/owners", { page_size: "100" }));
+    const list = Array.isArray(items)
+        ? items
+        : (items.items ?? []);
+    const idToName = new Map();
+    const nameToId = new Map();
+    for (const o of list) {
+        const id = Number(o.id ?? o.owner_id);
+        const name = String(o.user_name ?? o.name ?? o.owner_name ?? "");
+        if (id && name) {
+            idToName.set(id, name);
+            nameToId.set(name, id);
+        }
+    }
+    ownerCache = { idToName, nameToId };
+    return ownerCache;
+}
+async function resolveOwnerId(name) {
+    const om = await getOwnerMap();
+    return om.nameToId.get(name) ?? null;
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function fmt(v) {
+    if (v == null)
+        return null;
+    const n = Number(v);
+    if (isNaN(n))
+        return null;
+    return Number.isInteger(n) ? n : parseFloat(n.toFixed(2));
+}
+function text(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({ name: "linker-position-mcp", version: "0.1.0" });
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool 1: get_pnl_overview — 全局盈亏+持仓+VAR 快照
+// ═══════════════════════════════════════════════════════════════════════════════
+server.tool("get_pnl_overview", "查询公司整体盈亏+持仓+VAR快照：公司总已平盈亏、浮动盈亏、总盈亏、VAR总额/剩余/使用率，以及各持仓人的汇总一行（策略数、总盈亏、VAR、预警级别）。适合查询'公司整体什么情况'、'各人盈亏排名'、'谁在赚谁在亏'等场景。", {}, async () => {
+    const raw = (await api("/api/v1/pnl/report"));
+    const ownerDataList = raw.owner_data ?? [];
+    const gt = raw.grand_total;
+    // 每人汇总为一行
+    const owners = ownerDataList.map((o) => {
+        const strategies = o.strategies ?? [];
+        const activeStrategies = strategies.filter((s) => {
+            const legs = s.legs ?? [];
+            return legs.some((l) => Number(l.remaining_quantity ?? 0) > 0);
+        });
+        const totalPnl = strategies.reduce((sum, s) => sum + Number(s.total_strategy_pnl ?? 0), 0);
+        const floatingPnl = strategies.reduce((sum, s) => sum + Number(s.monitoring_pnl ?? 0), 0);
+        return {
+            owner: o.owner_name,
+            active_strategies: activeStrategies.length,
+            total_strategies: strategies.length,
+            total_pnl: fmt(totalPnl),
+            floating_pnl: fmt(floatingPnl),
+            var: fmt(o.owner_var),
+            var_usage: fmt(o.var_usage_rate),
+            alert: o.var_alert_level ?? "normal",
+        };
+    });
+    // 按 total_pnl 降序排
+    owners.sort((a, b) => (b.total_pnl ?? 0) - (a.total_pnl ?? 0));
+    const result = { owners };
+    if (gt) {
+        result.company = {
+            realized_pnl: fmt(gt.realized_pnl),
+            floating_pnl: fmt(gt.floating_pnl),
+            total_pnl: fmt(gt.total_pnl),
+            var_used: fmt(gt.total_var_used),
+            var_remain: fmt(gt.total_var_remain),
+            var_limit: gt.total_var_limit_str,
+            var_usage: gt.total_usage_rate_str,
+        };
+    }
+    return text(result);
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool 2: get_owner_detail — 某人持仓+盈亏+VAR 明细
+// ═══════════════════════════════════════════════════════════════════════════════
+server.tool("get_owner_detail", "查询某持仓人的完整持仓+盈亏+VAR明细：该人总盈亏、VAR分项（套保/套利/盘面）、各活跃策略的盈亏和每条持仓腿的合约/方向/数量/均价/市价/浮盈。适合查询'某人持仓什么'、'某人浮盈多少'、'某人各策略盈亏'等场景。", { owner: z.string().describe("持仓人姓名，如 任志华") }, async ({ owner }) => {
+    const raw = (await api("/api/v1/pnl/report", {
+        owners: owner,
+    }));
+    const ownerDataList = raw.owner_data ?? [];
+    const ownerData = ownerDataList.find((o) => o.owner_name === owner);
+    if (!ownerData)
+        return text(`未找到持仓人: ${owner}`);
+    const strategies = ownerData.strategies ?? [];
+    // 只展示有活跃持仓的策略
+    const activeStrategies = strategies.filter((s) => {
+        const legs = s.legs ?? [];
+        return legs.some((l) => Number(l.remaining_quantity ?? 0) > 0);
+    });
+    const floatingPnl = strategies.reduce((sum, s) => sum + Number(s.monitoring_pnl ?? 0), 0);
+    const realizedPart = strategies.reduce((sum, s) => sum + (Number(s.total_strategy_pnl ?? 0) - Number(s.monitoring_pnl ?? 0)), 0);
+    const fullyClosedPnl = Number(ownerData.fully_closed_pnl ?? 0);
+    const realizedPnl = fullyClosedPnl + realizedPart;
+    const totalPnl = realizedPnl + floatingPnl;
+    const result = {
+        owner,
+        realized_pnl: fmt(realizedPnl),
+        floating_pnl: fmt(floatingPnl),
+        total_pnl: fmt(totalPnl),
+        var: {
+            total: fmt(ownerData.owner_var),
+            hedge: fmt(ownerData.hedge_var),
+            arbitrage: fmt(ownerData.arbitrage_var),
+            outright: fmt(ownerData.outright_var),
+        },
+        var_limit: fmt(ownerData.var_limit),
+        var_usage_rate: fmt(ownerData.var_usage_rate),
+        var_alert: ownerData.var_alert_level,
+        active_strategies: activeStrategies.length,
+        total_strategies: strategies.length,
+        strategies: activeStrategies.map((s) => {
+            const legs = (s.legs ?? []).filter((l) => Number(l.remaining_quantity ?? 0) > 0);
+            return {
+                strategy: s.strategy_name,
+                category: s.category,
+                product: s.product,
+                total_pnl: fmt(s.total_strategy_pnl),
+                floating_pnl: fmt(s.monitoring_pnl),
+                var: fmt(s.strategy_var),
+                legs: legs.map((l) => ({
+                    contract: l.contract_name,
+                    direction: l.open_buy_sell,
+                    remaining_qty: fmt(l.remaining_quantity),
+                    avg_price: fmt(l.avg_open_price_all),
+                    market_price: fmt(l.market_price),
+                    unrealized_pnl: fmt(l.leg_unrealized_pnl),
+                    realized_pnl: fmt(l.leg_realized_pnl),
+                })),
+            };
+        }),
+    };
+    return text(result);
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool 3: get_risk_status — 风险 VAR 维度
+// ═══════════════════════════════════════════════════════════════════════════════
+server.tool("get_risk_status", "查询VAR风险状态。不传owner返回全员VAR概览（各人用量/额度/预警级别+当前超限告警）；传owner返回该人近30日VAR历史趋势。适合查询'谁VAR超限了'、'全员风险概览'、'某人VAR趋势'等场景。", { owner: z.string().optional().describe("持仓人姓名（可选）。不传=全员概览，传=某人VAR趋势") }, async ({ owner }) => {
+    if (!owner) {
+        // 全员 VAR 概览 + 告警
+        const [overview, alerts] = await Promise.all([
+            api("/api/v1/risk/dashboard/overview"),
+            api("/api/v1/risk/dashboard/alerts"),
+        ]);
+        const overviewList = (Array.isArray(overview) ? overview : []);
+        const alertList = (Array.isArray(alerts) ? alerts : []);
+        const owners = overviewList.map((o) => ({
+            owner: o.owner_name,
+            department: o.department,
+            var_value: fmt(o.var_value),
+            var_limit: fmt(o.var_limit),
+            usage_rate: fmt(o.usage_rate),
+            alert_level: o.alert_level,
+        }));
+        // 按 usage_rate 降序
+        owners.sort((a, b) => (b.usage_rate ?? 0) - (a.usage_rate ?? 0));
+        const result = { owners };
+        if (alertList.length > 0) {
+            result.alerts = alertList.map((a) => ({
+                owner: a.owner_name,
+                var_value: fmt(a.var_value),
+                var_limit: fmt(a.var_limit),
+                usage_rate: fmt(a.usage_rate),
+                alert_level: a.alert_level,
+            }));
+        }
+        else {
+            result.alerts = "当前无超限告警";
+        }
+        return text(result);
+    }
+    else {
+        // 某人 VAR 趋势
+        const ownerId = await resolveOwnerId(owner);
+        if (ownerId == null)
+            return text(`未找到持仓人: ${owner}`);
+        const history = (await api("/api/v1/risk/dashboard/history", {
+            owner_id: String(ownerId),
+            days: "30",
+        }));
+        const points = (Array.isArray(history) ? history : []);
+        if (!points.length)
+            return text(`${owner} 近30日无VAR记录`);
+        return text({
+            owner,
+            days: 30,
+            trend: points.map((p) => ({
+                date: p.calc_date,
+                var_value: fmt(p.var_value),
+                var_limit: fmt(p.var_limit),
+                usage_rate: fmt(p.usage_rate),
+                alert_level: p.alert_level,
+            })),
+        });
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool 4: list_owners — 持仓人列表（辅助）
+// ═══════════════════════════════════════════════════════════════════════════════
+server.tool("list_owners", "列出系统中所有持仓人姓名。适合在查询某人持仓/盈亏/VAR前先确认姓名是否存在，或用户问'有哪些交易员'时使用。", {}, async () => {
+    const om = await getOwnerMap();
+    const names = Array.from(om.nameToId.keys()).sort();
+    return text(names);
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write("[linker-position-mcp] running on stdio\n");

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "linker-position-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Linker Position & PnL queries - portfolio overview, owner detail, risk status",
+  "type": "module",
+  "bin": {
+    "linker-position-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "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"
+}