trident-mcp

Trident PM 的 Node.js MCP server，用 stdio 暴露 PM 查询和用户上下文工具。

环境要求

• Node.js >= 20.11
• npm >= 10

快速开始

npm install
npm run build
npm start

启动时程序会自动读取包根目录下的 .env，只填充当前进程尚未传入的环境变量；如果 Claude/Cursor 配置或命令行环境已经传了同名变量，会优先使用用户传入的值。

启动脚本和 npm 包入口会设置 NODE_TLS_REJECT_UNAUTHORIZED=0，让 Node.js 请求内网 HTTPS 接口时忽略证书校验。

通过 npm 包 / npx 启动时，也会自动读取包内 .env：

{
  "mcpServers": {
    "trident-pm": {
      "command": "npx",
      "args": ["-y", "@pwrd/trident-mcp"]
    }
  }
}

如果需要临时覆盖某个配置，仍可在客户端配置里传 env，传入值会覆盖包内 .env 的默认值。

常用脚本

npm run typecheck
npm test
npm run check

npm test 会先构建 dist，再用 Node 内置 test runner 执行现有测试文件。

环境变量

使用 .env 配置运行环境：

• TRIDENT_BASE_URL: PM API 基础地址
• SSO_URL: SSO 授权地址
• SSO_REDIRECT_URL: SSO 回跳地址
• GET_CLIENT_LOGIN_TOKEN_URL: 轮询 client login token 的地址
• CLIENT_ID: SSO client id
• PM_REQUEST_TIMEOUT_MS: PM 请求超时时间，默认 15000
• SSO_LOGIN_TIMEOUT_MS: SSO 登录等待时间，默认 300000
• SSO_TOKEN_POLL_INTERVAL_MS: SSO token 轮询间隔，默认 1000
• MCP_LOG_LEVEL: info、warn、silent/off
• MCP_FILE_PATH: 可选；本地 auth 缓存路径。默认使用当前用户的 %APPDATA%\trident-mcp\auth.json，发布包内 .env 不应写死该值
• PM_AUTH_TOKEN: 可选；设置后跳过 SSO，直接使用该 bearer token
• MCP_RATE_LIMIT_ENABLED: 是否启用 MCP 工具限流，默认 true；设为 false 或 0 关闭
• MCP_RATE_LIMIT_BURST_CAPACITY: MCP 工具允许的短时突发调用次数，默认 8
• MCP_RATE_LIMIT_MAX_PER_MINUTE: 令牌桶每分钟补充的调用额度，默认 30

MCP 工具

pm_mcp_ping

确认 MCP server 已启动，返回 pong。

me

返回当前登录用户摘要，以及可访问项目列表。项目列表会从 PM 刷新，auth.json 只作为回退缓存。

pm_tasks

查询项目任务。projectId / projectName 均可选：

• 用户只有 1 个项目 且未指定项目 → 自动选用该项目
• 用户有 多个项目 且未指定项目 → 返回项目列表，需用户选择后再查
• 禁止在未指定项目时遍历所有项目做汇总

支持筛选：

• mineOnly / userIds
• unfinishedOnly、finishedOnly、overdueOnly、dueTodayOnly、finishedTodayOnly
• statusIds 或 statusNames
• nodeIds 或 nodeNames
• priorities 或 priorityNames
• severities 或 severityNames
• creatorIds 或 creatorNames
• userIds 或 assigneeNames 或 mineOnly
• summaryContains、summaryEquals
• versionGroupId、tagId（单版本，可先用 pm_versions 查询）
• tagIds（多版本/路径 ID 合并查询）
• versionNames（按版本名称或完整路径解析后合并查询）
• filterId 不能与 tagIds / versionNames 同时使用
• preStartTimeStart、preStartTimeEnd
• preEndTimeStart、preEndTimeEnd
• createTimeStart、createTimeEnd
• requirementUnfinishedOnly
• orderByField、orderByDirection

JoSQL 由服务内部构建，不向 MCP 调用者暴露原始 JoSQL 字符串。

pm_versions

按项目列出版本分组和任务路径。任务路径包含版本及其下级文件夹/审核点，每一项都会返回可直接传给 pm_tasks 的 taskFilter.tagId；版本分组会返回可直接传给 pm_tasks 的 taskFilter.versionGroupId。

入参：

• projectId / projectName：项目范围，规则同 pm_tasks
• includeFolders：是否返回版本下的文件夹/审核点，默认 true

pm_users

按项目列出成员（id、username、nickname），用于发现可选负责人/创建人。查询任务时优先使用 pm_tasks.assigneeNames / pm_tasks.creatorNames。

pm_project_members

按项目返回全部成员、成员组及双向归属关系。members 包含每位成员的 groupIds / groupNames / ungrouped，memberGroups 包含每组的 memberIds，并补充 id=0 的“未分组”虚拟组；适合查询 pm_tasks 后按成员组分类或继续处理。

pm_workflow_states

按项目列出工作流状态，用于发现状态 ID、名称、颜色等信息。查询任务时优先使用 pm_tasks.statusNames。

pm_task_nodes

按项目列出任务类型（nodeId、name）。查询任务时优先使用 pm_tasks.nodeNames。

pm_priorities / pm_severities

按项目列出优先级/严重程度选项（id、label）。查询任务时优先使用 pm_tasks.priorityNames / pm_tasks.severityNames。

目录结构

src/
  auth/              # SSO、token 缓存、用户/项目上下文
  config/            # 环境变量和 URL 构造
  domain/            # PM 领域逻辑
    josql/           # JoSQL DSL fragments/builders
    task/            # 任务查询 use case
    version/         # 版本分组、任务路径查询和路径组装
    task-node/       # 任务类型查询、缓存、名称解析
    field-option/    # 优先级/严重程度选项查询、名称解析
    workflow-state/  # 工作流状态查询、缓存、名称解析
    project/         # 项目成员查询、名称解析
  infra/
    http/            # 通用 HTTP/JSON helper
    pm-api/          # PM API client
  mcp/               # MCP tool 注册
  shared/            # logger、类型守卫等共享基础设施
  tools/             # 薄 MCP adapter