Imported from zhangjianyong66/z-mcp (
AGENTS.md). Install upstream withnpx skills add zhangjianyong66/z-mcp. Copyright stays with the author.
项目协作说明
- 默认使用中文沟通、制定计划和记录方案;除非用户明确要求英文。
- git commit message 使用中文描述。
- 大型任务通过设计文档、计划文件、checkbox、测试结果和 git commit 保持连续性,不依赖聊天历史。
- 执行大型计划时,默认只执行用户指定的 milestone 或任务范围;不要在未确认的情况下连续推进整个大型计划。
stock-data-mcp
- 目录:
stock-data-mcp/ - 技术栈:Node.js ESM + TypeScript,MCP SDK,
mysql2/promise,Playwright,Python AkShare。 - 常用命令:
npm run check:TypeScript 类型检查。npm run build:构建到dist/。npm test:运行 Node 测试。npm run dev:以tsx src/index.ts启动开发服务。
- MySQL 配置环境变量:
DB_HOST默认mysql.zhangjianyong.topDB_PORT默认3306- 初始化脚本使用
DB_NAME=stock_data - 初始化脚本使用
DB_USER=stock_data_app DB_PASS必填
- 数据库初始化脚本:
stock-data-mcp/docs/mysql-init.sql。 - 当前代码依赖的数据表:
etf_universe:ETF 标的池,供etf_universe和etf_batch_decide读取symbol/name/theme。etf_portfolios:最新持仓快照主表。etf_positions:持仓明细,关联etf_portfolios.id。etf_orders:交易单/挂单,支持pending/filled/cancelled/expired状态。sector_hot_latest:sector_list每次调用后刷新的热门行业快照;代码会自动创建该表,但初始化脚本也包含完整定义。
sector_list依赖本机python3和akshare包,可通过AKSHARE_PYTHON_BIN指定虚拟环境解释器。xueqiu数据源优先使用XUEQIU_COOKIE;未配置时会尝试 Playwright 自动获取 Cookie。
etf-alert-mcp
- 目录:
etf-alert-mcp/ - 来源:从 Z-Tools 迁入并统一为
etf-alert-mcp命名;仍通过 Z-Tools 后端/mcp/etfTradeAlert/...接口管理 ETF 交易提醒。 - 技术栈:Node.js ESM + TypeScript,MCP SDK,
fetch调后端 API。 - 常用命令:
npm install:安装依赖。npm test:运行 Node 测试。npm run build:构建到dist/。node dist/index.js:启动 stdio MCP Server。
- 环境变量:
ETF_ALERT_MCP_BACKEND_BASE_URL默认http://localhost:8082ETF_ALERT_MCP_API_KEY必填,对应后端GO_API_MCP_API_KEY
- MCP 客户端配置时应指向
/home/zhangjianyong/project/z-mcp/etf-alert-mcp/dist/index.js。 - 该模块不直连 MySQL,只通过后端 MCP API 读写数据,用户归属由后端
GO_API_MCP_USER_ID决定;Agent 创建提醒时如未传notifyType,MCP 默认使用feishu。 update_etf_trade_alert如未传enabled,MCP 会先读取当前提醒并沿用现有启停状态,避免后端布尔零值把提醒误置为停用;后端更新成功但返回空数据时,MCP 会自动重新查询详情并返回确认结果。delete_etf_trade_alert删除成功但后端返回空数据时,MCP 会返回包含success、operation和id的确认对象,而不是直接暴露null。- 到价检查和通知触发由 Z-Tools Go 后端定时任务负责:后端每分钟检查 active/enabled 的 ETF 交易提醒,读取东方财富行情,按
price_lte/price_gte判断后发送邮箱或飞书通知,并维护最新价、检查时间、触发时间、触发次数和错误信息。
mysql-mcp
- 目录:
mysql-mcp/ - 技术栈:Node.js ESM + TypeScript,MCP SDK,
mysql2/promise,Node built-in test runner。 - 常用命令:
npm run check:TypeScript 类型检查。npm test:运行 Node 测试。npm run build:构建到dist/。npm run dev:以tsx src/index.ts启动开发服务。
- 当前
tsconfig的实际构建入口为mysql-mcp/dist/src/index.js。 - Codex 全局配置中已添加
mysql_littlebaoMCP server,指向/home/zhangjianyong/project/z-mcp/mysql-mcp/dist/src/index.js;连接凭据保存在/home/zhangjianyong/.codex/config.toml,不要写入项目文档。 - 一个
mysql-mcpserver 实例只连接一个 MySQL 数据源;不支持MYSQL_DATASOURCES多数据源 JSON 配置。 - 如需同时使用多个 MySQL 数据源,应在 MCP 客户端配置多个
mysql-mcpserver 条目,并分别设置不同环境变量。 - MySQL 配置环境变量:
MYSQL_HOST必填MYSQL_PORT默认3306MYSQL_USER必填MYSQL_PASSWORD默认空字符串MYSQL_DATABASE必填MYSQL_SSL默认falseMYSQL_QUERY_TIMEOUT_MS默认30000MYSQL_MAX_ROWS默认500,最大5000
- 当前工具使用当前 server 实例绑定的数据源,不接收
datasource参数;工具包括mysql_query、list_databases、list_tables、describe_table。 list_datasources工具已移除。- Codex CLI 已在
~/.codex/config.toml配置独立 servermysql-littlebao,连接远程库littlebao,账号littlebao_readonly仅授予littlebao.*的SELECT权限;密码只保存在 Codex 本机配置中,不写入项目说明。 - Codex CLI 的 MySQL MCP server 应使用单数据源环境变量配置,例如
MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE、MYSQL_SSL;不要再使用MYSQL_DATASOURCES。 - Codex CLI 当前配置中
mysql连接integra_serve,mysql-z-blog连接blog,mysql-littlebao连接littlebao,三个 server 均指向mysql-mcp/dist/src/index.js。
image-mcp
- 目录:
image-mcp/ - 技术栈:Node.js ESM + TypeScript,MCP SDK,DashScope 百炼多模态同步接口。
- 常用命令:
npm run check:TypeScript 类型检查。npm test:运行 Node 测试。npm run build:构建到dist/。npm run dev:以tsx src/index.ts启动开发服务。
- 工具包括
generate_image、edit_image、analyze_image。 - 生图/图生图使用
DASHSCOPE_API_KEY、DASHSCOPE_BASE_URL、DASHSCOPE_MODEL或IMAGE_MODEL_CHAIN配置。 - 图片理解
analyze_image使用独立视觉配置:VISION_API_KEY、VISION_BASE_URL、VISION_MODEL或VISION_MODEL_CHAIN;未配置VISION_API_KEY时会回退到DASHSCOPE_API_KEY/LLM_API_KEY。 VISION_MODEL必须选择支持图片输入的百炼多模态模型;纯文本模型即使可调用,也不能完成视觉理解。- 当前实现调用
POST /api/v1/services/aigc/multimodal-generation/generation,请求内容按图片在前、文本提示词在后的顺序发送。
image-view-mcp
- 目录:
image-view-mcp/ - 技术栈:Node.js ESM + TypeScript,MCP SDK,DashScope 百炼多模态同步接口。
- 常用命令:
npm ci:首次检出、缺少node_modules/或本地找不到tsc时,按package-lock.json安装依赖。npm run check:TypeScript 类型检查。npm test:运行 Node 测试。npm run build:构建到dist/。npm run dev:以tsx src/index.ts启动开发服务。
- 工具包括
analyze_image,专门用于图片描述、元素识别、截图理解和多图对比等只读视觉理解场景。 - 配置环境变量:
DASHSCOPE_API_KEY必填。DASHSCOPE_BASE_URL默认https://dashscope.aliyuncs.com。VISION_MODEL必填,建议使用qwen3.7-plus这类支持图片输入的多模态模型。VISION_MODEL_CHAIN可选,支持内联 JSON 或file:路径,用于多模型回退。
- 当前实现调用
POST /api/v1/services/aigc/multimodal-generation/generation,请求内容按图片在前、文本提示词在后的顺序发送。 - 该模块不提供生图或图生图能力;生成类工具仍归属
image-mcp。
search-mcp
- 目录:
search-mcp/ - 技术栈:Node.js ESM + TypeScript,MCP SDK,
undici,dotenv。 - 常用命令:
npm ci:安装锁定依赖。npm run check:TypeScript 类型检查。npm test:运行 Node 测试。npm run build:构建到dist/。npm run dev:以tsx src/index.ts启动开发服务。
- 当前
tsconfig使用rootDir = ".",实际构建入口为search-mcp/dist/src/index.js。 - Codex 全局配置中的
searchMCP server 在 Linux 环境应指向/usr/bin/node和/home/zhangjianyong/project/z-mcp/search-mcp/dist/src/index.js;搜索服务密钥保存在/home/zhangjianyong/.codex/config.toml,不要写入项目文档。
cdp-browser-mcp
- 目录:
cdp-browser-mcp/ - 技术栈:Node.js ESM + TypeScript,MCP SDK,Playwright
chromium.connectOverCDP。 - 常用命令:
npm ci:安装锁定依赖。npm run check:TypeScript 类型检查。npm run build:构建到dist/。npm test:运行 Chrome CDP 启动脚本测试。npm run dev:以tsx src/index.ts启动开发服务。
- 当前
tsconfig使用rootDir = ".",实际构建入口为cdp-browser-mcp/dist/src/index.js。 - Codex 全局配置中的
cdp_browserMCP server 在 Linux 环境应指向/usr/bin/node和/home/zhangjianyong/project/z-mcp/cdp-browser-mcp/dist/src/index.js。 - 单个 MCP server 进程启动时读取一次
CDP_ENDPOINT,默认http://127.0.0.1:9222;当前所有浏览器操作工具都连接这个进程级 endpoint,不支持单次工具调用动态切换 Chrome 实例。 - 如需同时控制系统 Chrome 和微信开发工具内置 Chrome,推荐在 MCP 客户端配置两个 server 条目,分别设置不同
CDP_ENDPOINT,例如系统 Chrome 用9222,微信开发工具用另一个远程调试端口。 start_chrome_cdp工具支持传入cdp_port、chrome_bin、user_data_dir、profile_directory、log_file启动指定 Chrome;但启动后当前 MCP 进程不会自动切换到该端口,后续操作仍取决于该进程的CDP_ENDPOINT。scripts/start-chrome-cdp.sh会保守检测已有 Chrome/Chromium 进程;如果浏览器已运行但目标 CDP 端口不可访问,脚本会退出并提示手动用--remote-debugging-port重启。
Trellis Instructions
These instructions are for AI assistants working in this project.
This project is managed by Trellis. The working knowledge you need lives under .trellis/:
.trellis/workflow.md— development phases, when to create tasks, skill routing.trellis/spec/— package- and layer-scoped coding guidelines (read before writing code in a given layer).trellis/workspace/— per-developer journals and session traces.trellis/tasks/— active and archived tasks (PRDs, research, jsonl context)
If a Trellis command is available on your platform (e.g. /trellis:finish-work, /trellis:continue), prefer it over manual steps. Not every platform exposes every command.
If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
.agents/skills/— reusable Trellis skills.codex/agents/— optional custom subagents
Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future trellis update.
