@caidazi/mcp 0.2.0

package/caidazi-stock-screener/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: caidazi-stock-screener
+description: 当用户用自然语言描述股票、ETF 或市场筛选条件，并希望得到候选标的时使用。
+---
+
+# 财搭子智能筛选
+
+用这个 skill 处理自然语言选股。公开 skill 必须调用服务端筛选 wrapper，不要在本地构造原始数据查询。
+
+## 适用场景
+
+- "帮我筛选低估值高股息股票"
+- "找最近资金流入强的半导体"
+- "选一些港股科技 ETF"
+- "A股里找盈利改善的中盘股"
+- "我的自选里筛一下最近比较强的"
+
+不要用于单个已命名标的、完整市场摘要、私有组合诊断或精确回测。
+
+## 可用工具
+
+- `screen_stocks`
+- `get_caidazi_user_watchlist` 或 `get_caidazi_positions_summary`，仅当用户明确限定在财搭子自选或持仓中筛选时使用。
+- `extract_assets`，仅当用户问题里包含需要规范化的具体标的名称时使用。
+
+## 流程
+
+1. 把用户请求作为一个完整的自然语言筛选 query。
+2. 推断 `market`：
+   - A股、沪深、CN、默认中文股票请求：`CN`
+   - 港股：`HK`
+   - 美股：`US`
+   - ETF 或基金限定：`ETF`
+3. 推断 `limit`；默认 10，最多 30。
+4. 如果用户说"我的自选"，先调用 `get_caidazi_user_watchlist`；如果说"我的持仓"，先调用 `get_caidazi_positions_summary(mask_sensitive=true)`；再把这个范围写进传给 `screen_stocks` 的自然语言 query。
+5. 对同一个用户请求只调用一次 `screen_stocks(query, market, limit)`。
+6. 展示工具返回的候选标的和筛选解释。
+
+## 澄清策略
+
+筛选条件过于空泛时最多问一个问题。
+
+需要提问的例子：
+
+- "帮我选点股票"，且没有风格、市场或条件。
+- "选新能源"，但用户明显需要精确子方向。
+
+不需要提问的例子：
+
+- "低 PE 高股息"
+- "A股半导体最近放量"
+- "我的自选里找资金强的"
+
+## 输出结构
+
+1. 筛选条件理解。
+2. 候选表格：名称、代码、市场、入选原因。
+3. 重要限制或风险提示。
+4. 数据时间。
+5. 下一步建议：比较候选，或深入研究某个标的。
+
+把结果表述为候选，不要表述为推荐。
+
+## 空结果
+
+如果没有候选：
+
+- 说明条件可能过严；
+- 给出一两个更宽松的改写方向；
+- 不要编造标的。
+
+## 错误处理
+
+- API Key 无效：引导用户到 财搭子 App -> 大发 agent -> 左上角 skill icon -> Skills 页面重新领取。
+- 工具调用失败：按工具返回的 `message` 说明，不自行推断后台策略。
+- 请求过于频繁：提示稍后重试。
+- 账户资产不可用：说明需要账户关联 key，可到 财搭子 App -> 大发 agent -> 左上角 skill icon -> Skills 页面领取或绑定；如果可以，继续做公开市场筛选。
+
+## 边界
+
+- 不要构造原始数据查询。
+- 不要暴露筛选字段、候选生成、排序或数据映射细节。
+- 不要承诺未来收益。
+- 除非用户明确要求调整条件，同一请求不要多次调用筛选 wrapper。

package/caidazi-user-assets/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: caidazi-user-assets
+description: 当用户想查看或使用自己在财搭子的自选、持仓、账户关联资产或个人资产上下文时使用。
+---
+
+# 财搭子用户资产
+
+用这个 skill 通过账户关联 API Key 访问用户在财搭子里的数据资产。它是外部 Agent 回到财搭子主端的桥，不是组合诊断引擎。
+
+## 适用场景
+
+- "查看我的自选"
+- "我的持仓有哪些"
+- "用我的自选做对比"
+- "看一下我的持仓受这个消息影响吗"
+- "从我的资产里筛一下"
+
+不要用于交易、账户修改、订阅设置或深度组合诊断。
+
+## 可用工具
+
+- `get_caidazi_user_watchlist`
+- `get_caidazi_positions_summary`
+- `get_caidazi_portfolio_snapshot`
+
+## 流程
+
+1. 判断 `asset_type`：
+   - watchlist：用户说自选、watchlist、关注资产。
+   - holdings：用户说持仓、托管、positions。
+   - all：用户说我的资产、个人上下文，或同时需要自选和持仓。
+2. 自选调用 `get_caidazi_user_watchlist`，持仓调用 `get_caidazi_positions_summary(mask_sensitive=true)`，全部资产调用 `get_caidazi_portfolio_snapshot(mask_sensitive=true)`。
+3. 如果工具返回 `requires_login`、`account_not_linked` 或 `ASSET_PERMISSION_REQUIRED`，提示用户到 财搭子 App -> 大发 agent -> 左上角 skill icon -> Skills 页面领取或绑定 API Key。
+4. 如果返回数据，只总结工具返回的资产和安全公开字段。
+5. 如果下一步是研究，把返回代码交给 `caidazi-asset-research`、`caidazi-stock-screener`、`caidazi-market-pulse` 或 `caidazi-finance-search`。
+
+## 输出结构
+
+自选：
+
+- 总数量；
+- 可见的重点资产；
+- 数据缺失或延迟提醒；
+- 下一步可做什么。
+
+持仓：
+
+- 总数量；
+- 资产名称和代码；
+- 如果工具返回了高层持仓信息，可以概括；
+- 避免给具体交易指令。
+
+全部资产：
+
+- 清楚区分自选和持仓。
+
+## 数据边界
+
+严格使用工具返回的数据。不要推断未返回的成本、数量、盈亏或风险偏好。字段未返回就说明不可用。
+
+## 示例
+
+用户：
+
+> 看下我的自选
+
+动作：
+
+- 调用 `get_caidazi_user_watchlist()`；
+- 总结数量和可见资产。
+
+用户：
+
+> 我的持仓受今天热点影响吗？
+
+动作：
+
+- 调用 `get_caidazi_positions_summary(mask_sensitive=true)`；
+- 把返回代码交给市场脉搏或事件影响 skill。
+
+用户：
+
+> 从我的自选里选几个强一点的
+
+动作：
+
+- 调用 `get_caidazi_user_watchlist()`；
+- 把资产范围传给智能筛选。
+
+## 交接
+
+- 研究某个返回资产：使用 `caidazi-asset-research`。
+- 比较多个返回资产：使用 `compare_assets`。
+- 在返回资产中筛选：使用 `caidazi-stock-screener`。
+- 分析新闻或政策影响：使用 `caidazi-finance-search`，必要时再结合 `caidazi-market-pulse`。
+
+## 错误处理
+
+- API Key 无效：引导用户到 财搭子 App -> 大发 agent -> 左上角 skill icon -> Skills 页面重新领取。
+- API Key 未关联财搭子账户：解释同一路径可以领取或绑定。
+- 工具调用失败：按工具返回的 `message` 总结，不自行推断后台策略。
+- 工具未开放：说明账户资产访问暂未对外部 Agent 开放。
+
+## 边界
+
+- 不要暴露 API Key。
+- 不要声称拥有完整券商账户访问权。
+- 不要修改自选或持仓。
+- 用户没有要求时，不要主动使用私有资产。
+- 不要仅基于账户上下文给买卖指令。

package/manifest.yaml

@@ -0,0 +1,162 @@
+schema_version: 1
+bundle: caidazi-skills
+version: 0.2.0
+env:
+  primary_api_key: CAIDAZI_API_KEY
+mcp:
+  server_name: caidazi
+  transport: stdio
+  npm_package: "@caidazi/mcp"
+  github_package: "github:caidazi/dafa-skills"
+  command: npx
+  args:
+    - -y
+    - "@caidazi/mcp"
+  unpublished_fallback:
+    command: npx
+    args:
+      - -y
+      - "github:caidazi/dafa-skills"
+    use_when: "The npm package is not published or the registry returns package-not-found."
+  hosted_endpoint: "https://<caidazi-https-mcp-endpoint>/mcp"
+  hosted_endpoint_kind: production-placeholder
+  security:
+    tls_required_for_bearer: true
+    allow_bearer_over_plain_http: false
+    local_bridge_instruction: "Default install uses the npm stdio MCP bridge. The bridge exposes standard MCP tools to the Agent and calls the Caidazi backend internally."
+    hosted_endpoint_instruction: "Use the hosted HTTPS MCP endpoint only after it passes MCP initialize/list-tools health checks."
+  auth:
+    type: bearer
+    header: Authorization
+    env_ref: CAIDAZI_API_KEY
+    format: "Bearer {value}"
+    secret: true
+    redact: true
+installation:
+  default_mode: stdio-mcp-bridge
+  supported_modes:
+    - stdio-mcp-bridge
+    - hosted-mcp
+    - skills-only
+  stdio_mcp_bridge:
+    config_instruction: "Use the current Agent's documented MCP configuration flow. Do not guess legacy config paths."
+    server_name_ref: mcp.server_name
+    transport_ref: mcp.transport
+    command_ref: mcp.command
+    args_ref: mcp.args
+    unpublished_fallback_ref: mcp.unpublished_fallback
+    auth_env_ref: CAIDAZI_API_KEY
+    package_ref: mcp.npm_package
+    success_condition: "The current Agent discovers the tools listed in required_mcp.public_tools through MCP."
+  hosted_mcp:
+    enabled: false
+    endpoint_ref: mcp.hosted_endpoint
+    enable_when: "An official HTTPS MCP transport endpoint is deployed and passes health checks."
+  skills_only:
+    report_as: "Skills-only mode"
+    limitation: "No Caidazi tools are available; the Agent can only follow the skill output structure."
+backend_api:
+  test_base_url: "http://101.126.22.17:5011"
+  endpoint_kind: temporary-plain-http
+  tool_registry_path: "/api/tools/registered"
+  tool_call_path: "/api/tools/call"
+  used_by: "@caidazi/mcp stdio bridge"
+  auth:
+    type: bearer
+    header: Authorization
+    env_ref: CAIDAZI_API_KEY
+    format: "Bearer {value}"
+    secret: true
+    redact: true
+  safety:
+    requires_allow_http_env: CAIDAZI_ALLOW_HTTP
+    use_only_when_user_confirms_temporary_test_env: true
+    do_not_expose_as_agent_mcp_endpoint: true
+    do_not_store_api_key_in_repo_or_shared_config: true
+publication:
+  npm_registry: "https://registry.npmjs.org/"
+  package: "@caidazi/mcp"
+  publish_required_for_default_npx_install: true
+  initial_publish_command: "npm publish"
+  publish_requires:
+    - "npm account logged in on this machine"
+    - "permission to publish packages under the @caidazi scope"
+    - "confirmed repository license policy"
+skills:
+  included:
+    - caidazi-market-pulse
+    - caidazi-asset-research
+    - caidazi-stock-screener
+    - caidazi-user-assets
+    - caidazi-finance-search
+    - caidazi-fund-etf-research
+    - caidazi-macro-research
+    - caidazi-portfolio-review
+required_mcp:
+  public_tools:
+    - extract_assets
+    - get_hot_report
+    - get_real_time_market_summary
+    - get_market_analysis
+    - get_macro_analysis
+    - get_asset_overview
+    - investment_search_pro
+    - compare_assets
+    - screen_stocks
+    - get_etf_constituents
+    - get_index_related_etfs
+    - get_stock_belongings
+  account_tools:
+    - get_caidazi_user_watchlist
+    - get_caidazi_positions_summary
+    - get_caidazi_portfolio_snapshot
+  smoke_safe_tools:
+    - extract_assets
+    - get_hot_report
+    - get_real_time_market_summary
+    - get_market_analysis
+    - get_macro_analysis
+  smoke_forbidden_tools:
+    - get_caidazi_user_watchlist
+    - get_caidazi_positions_summary
+    - get_caidazi_portfolio_snapshot
+blocked_surface:
+  - raw database access
+  - internal account tools
+  - internal monitor or subscription tools
+  - local file or UI-only tools
+verification:
+  skill_indexing:
+    required_when_supported: true
+    fallback_mode: MCP-only
+  mcp_connection:
+    server_name_ref: mcp.server_name
+    must_connect_when_secure_transport_available: true
+    health_check_required: true
+    agent_health_check_required: true
+    tools_discovery_required: true
+  backend_bridge:
+    test_registry_ref: backend_api.tool_registry_path
+    tool_call_ref: backend_api.tool_call_path
+    plain_http_requires_explicit_opt_in: true
+  api_key:
+    never_print_full_key: true
+    never_read_with_printenv: true
+    never_store_in_repo: true
+    missing_key_instruction: "Ask the user to open 财搭子 App -> 大发 agent 页面 -> 左上角 skill icon -> Skills 页面, then set CAIDAZI_API_KEY through the current Agent's secure configuration path."
+  network_smoke_test:
+    require_tls_for_authenticated_calls: true
+    allowed_tools_ref: required_mcp.smoke_safe_tools
+    forbidden_tools_ref: required_mcp.smoke_forbidden_tools
+post_install:
+  intro_public: "财搭子已接入。你可以让我做市场脉搏、单标的研究、多标的比较、自然语言选股、基金/ETF 研究、宏观分析和资讯检索。"
+  intro_account: "如果你的 API Key 已绑定财搭子账户，还可以查看自选、持仓和组合快照，并做轻量复盘。"
+  ask: "你想先做哪类任务？"
+  sample_queries:
+    public:
+      - 今天 A 股市场热点是什么？
+      - 帮我看下宁德时代最近的核心矛盾。
+      - 比亚迪和宁德时代谁更值得跟踪？
+      - 找出最近资金强、估值不贵的新能源股票。
+    account:
+      - 我的自选里今天哪些最值得关注？

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@caidazi/mcp",
+  "version": "0.2.0",
+  "description": "Caidazi MCP stdio bridge for generic AI agents.",
+  "type": "module",
+  "keywords": [
+    "caidazi",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "finance"
+  ],
+  "homepage": "https://github.com/caidazi/dafa-skills#readme",
+  "bugs": {
+    "url": "https://github.com/caidazi/dafa-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caidazi/dafa-skills.git"
+  },
+  "bin": {
+    "caidazi-mcp": "bin/caidazi-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "manifest.yaml",
+    "caidazi-*/SKILL.md"
+  ],
+  "scripts": {
+    "prepack": "npm test",
+    "test": "node --test",
+    "validate": "node ./bin/caidazi-mcp.js validate"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {}
+}

package/src/allowed-tools.js

@@ -0,0 +1,23 @@
+export const ALLOWED_TOOL_NAMES = Object.freeze([
+  "extract_assets",
+  "get_hot_report",
+  "get_real_time_market_summary",
+  "get_market_analysis",
+  "get_macro_analysis",
+  "get_asset_overview",
+  "investment_search_pro",
+  "compare_assets",
+  "screen_stocks",
+  "get_etf_constituents",
+  "get_index_related_etfs",
+  "get_stock_belongings",
+  "get_caidazi_user_watchlist",
+  "get_caidazi_positions_summary",
+  "get_caidazi_portfolio_snapshot",
+]);
+
+export const ALLOWED_TOOL_SET = new Set(ALLOWED_TOOL_NAMES);
+
+export function isAllowedTool(toolName) {
+  return ALLOWED_TOOL_SET.has(toolName);
+}

package/src/cli.js

@@ -0,0 +1,60 @@
+import { loadConfig } from "./config.js";
+import { runStdioServer } from "./mcp-server.js";
+import { CaidaziRestClient } from "./rest-client.js";
+
+const HELP = `Caidazi MCP bridge
+
+Usage:
+  caidazi-mcp                    Start the stdio MCP server
+  caidazi-mcp validate [--probe] Validate backend reachability
+
+Environment:
+  CAIDAZI_API_KEY       Required bearer token
+  CAIDAZI_BASE_URL      Optional backend base URL (default: http://101.126.22.17:5011)
+  CAIDAZI_ALLOW_HTTP    Required as "true" when CAIDAZI_BASE_URL uses http://
+  CAIDAZI_TIMEOUT_MS    Optional request timeout in milliseconds (default: 30000)
+`;
+
+export async function main({ argv = process.argv.slice(2), env = process.env } = {}) {
+  const [command, ...rest] = argv;
+
+  if (command === "--help" || command === "-h" || command === "help") {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (command === "validate") {
+    await validate({ argv: rest, env });
+    return;
+  }
+
+  await runStdioServer({ argv, env });
+}
+
+async function validate({ argv, env }) {
+  const config = loadConfig({ argv: argv.filter((arg) => arg !== "--probe"), env });
+  const client = new CaidaziRestClient(config);
+  const tools = await client.listTools();
+
+  process.stdout.write(`Caidazi backend reachable: ${tools.length} public tools exposed\n`);
+  for (const tool of tools.slice(0, 12)) {
+    process.stdout.write(`- ${tool.name}\n`);
+  }
+
+  if (argv.includes("--probe")) {
+    const result = await client.callTool("extract_assets", { text: "贵州茅台" });
+    process.stdout.write(`Probe extract_assets succeeded: ${summarizeProbe(result)}\n`);
+  }
+}
+
+function summarizeProbe(result) {
+  if (typeof result === "string") {
+    return result.slice(0, 120);
+  }
+
+  if (result && typeof result === "object") {
+    return JSON.stringify(result).slice(0, 120);
+  }
+
+  return String(result);
+}

package/src/config.js

@@ -0,0 +1,82 @@
+const DEFAULT_BASE_URL = "http://101.126.22.17:5011";
+const DEFAULT_TIMEOUT_MS = 30000;
+
+export function loadConfig({ env = process.env, argv = process.argv.slice(2) } = {}) {
+  const options = parseArgs(argv);
+  const apiKeyEnv = options.apiKeyEnv || "CAIDAZI_API_KEY";
+  const apiKey = options.apiKey || env[apiKeyEnv];
+
+  if (!apiKey) {
+    throw new Error(`${apiKeyEnv} is required. Set it in your Agent's secret or environment configuration.`);
+  }
+
+  const baseUrl = normalizeBaseUrl(
+    options.baseUrl ||
+      env.CAIDAZI_BASE_URL ||
+      env.CAIDAZI_API_BASE_URL ||
+      DEFAULT_BASE_URL,
+  );
+  const allowHttp = options.allowHttp === "true" || env.CAIDAZI_ALLOW_HTTP === "true";
+  const timeoutMs = parsePositiveInteger(
+    options.timeoutMs || env.CAIDAZI_TIMEOUT_MS,
+    DEFAULT_TIMEOUT_MS,
+  );
+
+  if (baseUrl.startsWith("http://") && !allowHttp) {
+    throw new Error(
+      "Plain HTTP backend requires explicit CAIDAZI_ALLOW_HTTP=true because bearer tokens are sent to the backend.",
+    );
+  }
+
+  return {
+    apiKey,
+    apiKeyEnv,
+    baseUrl,
+    allowHttp,
+    timeoutMs,
+  };
+}
+
+export function parseArgs(argv) {
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+
+    const [rawName, inlineValue] = arg.slice(2).split("=", 2);
+    const name = rawName.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    const value = inlineValue ?? argv[index + 1];
+
+    if (inlineValue === undefined) {
+      index += 1;
+    }
+
+    if (value === undefined) {
+      throw new Error(`Missing value for --${rawName}`);
+    }
+
+    options[name] = value;
+  }
+
+  return options;
+}
+
+function normalizeBaseUrl(value) {
+  return String(value || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+function parsePositiveInteger(value, fallback) {
+  if (value === undefined || value === null || value === "") {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Expected a positive integer timeout, got: ${value}`);
+  }
+
+  return parsed;
+}

package/src/mcp-server.js

@@ -0,0 +1,60 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { loadConfig } from "./config.js";
+import { CaidaziRestClient } from "./rest-client.js";
+import { createMcpTool, resultToContent } from "./tool-schema.js";
+
+export function createServer({ client, version = "0.1.0" }) {
+  const server = new Server(
+    {
+      name: "caidazi",
+      version,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+      instructions:
+        "Caidazi tools provide market pulse, asset research, stock screening, fund/ETF research, macro analysis, finance search, user assets, and portfolio review.",
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = await client.listTools();
+    return {
+      tools: tools.map(createMcpTool),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const parameters = request.params.arguments || {};
+
+    try {
+      const result = await client.callTool(toolName, parameters);
+      return {
+        content: resultToContent(result),
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: resultToContent(error instanceof Error ? error.message : String(error)),
+      };
+    }
+  });
+
+  return server;
+}
+
+export async function runStdioServer({ env = process.env, argv = process.argv.slice(2) } = {}) {
+  const config = loadConfig({ env, argv });
+  const client = new CaidaziRestClient(config);
+  const server = createServer({ client, version: process.env.npm_package_version || "0.1.0" });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}