OneView MCP（stdio 工具服务器）

这是一个 OneView 的 Model Context Protocol (MCP) 服务器（stdio 模式）。它的目标是让 AI/IDE 能直接拿到“单子快照”的 AI 友好 Markdown（ai.md），用于分析和生成解决方案。

能做什么

支持两条数据路径：

1. 公开分享快照（无需鉴权）

• 先在 OneView 里生成分享页：/share/<token>
• AI/MCP 读取：GET /api/share/<token>/ai.md

2. 从任务引用自动生成快照（需要鉴权）

• 直接给引用：zentao#16915 / redmine#123 / gitlab#456
• MCP 调用：POST /api/share 生成快照，然后读取 ai.md
• 这一步需要 ONEVIEW_API_TOKEN（OneView 登录后的 oneview_token）

工具列表（Tools）

• oneview_ai_md(input, ttl_hours?)
  • input 支持：
    • 任务引用（需要 token）：zentao#16915
    • 分享 token / 链接（不需要 token）：<token>、/share/<token>、/api/share/<token>、或完整 URL
• oneview_get_task_ai_md(ref, ttl_hours?)（需要 token）
• oneview_create_share(ref, ttl_hours?)（需要 token）
• oneview_get_share_ai_md(token)（公开）
• oneview_get_share_snapshot(token)（公开）
• oneview_help()

环境变量

• ONEVIEW_API_ORIGIN：OneView 对外可访问的 origin（默认 http://localhost:8000）
• ONEVIEW_API_BASE_PATH：默认 /api
• ONEVIEW_API_TOKEN：可选；凡是需要“自动创建分享快照”的工具都需要它
• ONEVIEW_API_TOKEN_FILE：可选；二选一（推荐）
  • 把 oneview_token 写到本地文件（纯文本一行），MCP 启动时读取

获取 token（OneView 前端登录后）：

• 浏览器控制台：localStorage.getItem('oneview_token')

本地安装运行（Node）

cd mcp
npm install
npm start

通过 npm 使用（推荐）

无需 clone 仓库：

# stdio MCP（直接跑在本机）
npx -y oneview-mcp

# 或全局安装
npm install -g oneview-mcp@latest
oneview-mcp

说明：仍然通过环境变量传 ONEVIEW_API_ORIGIN / ONEVIEW_API_TOKEN_FILE 等参数（见下文）。

在 Codex（Codex CLI / Codex IDE）里配置 MCP

Codex 会自己启动 MCP 进程（stdio）。推荐直接用 npm 包（npx），也支持本仓库里的脚本（node mcp/oneview-mcp.mjs）。

方式 1：用 codex mcp add（推荐）

用 npm 包（推荐）：

codex mcp add oneview \
  --env ONEVIEW_API_ORIGIN=http://localhost:8080 \
  --env ONEVIEW_API_BASE_PATH=/api \
  -- npx -y oneview-mcp@latest

如果要支持 zentao#16915 自动创建快照，再额外传 token（或改为 token 文件方式）：

codex mcp add oneview \
  --env ONEVIEW_API_ORIGIN=http://localhost:8080 \
  --env ONEVIEW_API_BASE_PATH=/api \
  --env ONEVIEW_API_TOKEN_FILE=/abs/path/to/token.txt \
  -- npx -y oneview-mcp@latest

验证：

codex mcp list
codex mcp get oneview

方式 2：写入 ~/.codex/config.toml（适合固定部署）

示例：

[mcp_servers.oneview]
type = "stdio"
command = "npx"
args = ["-y", "oneview-mcp@latest"]

[mcp_servers.oneview.env]
ONEVIEW_API_ORIGIN = "http://localhost:8080"
ONEVIEW_API_BASE_PATH = "/api"
# 建议用文件方式（不要把 token 提交到仓库）
ONEVIEW_API_TOKEN_FILE = "/abs/path/to/token.txt"

在 Claude Code 里配置 MCP

Claude Code 支持用命令行添加，或直接写 .mcp.json（项目级，适合团队共享）。推荐用 .mcp.json，避免 CLI 参数顺序差异带来的踩坑。

方式 1：CLI 添加（stdio）

claude mcp add --scope project oneview \
  -- npx -y oneview-mcp@latest

如果要启用自动创建快照（任务引用模式），建议用环境变量（或 token 文件）：

claude mcp add --scope project oneview \
  --env ONEVIEW_API_ORIGIN=http://localhost:8080 \
  --env ONEVIEW_API_BASE_PATH=/api \
  --env ONEVIEW_API_TOKEN_FILE=/abs/path/to/token.txt \
  -- npx -y oneview-mcp@latest

方式 2：.mcp.json（团队共享，不提交 token）

在仓库根目录创建/编辑 .mcp.json：

{
  "mcpServers": {
    "oneview": {
      "command": "npx",
      "args": ["-y", "oneview-mcp@latest"],
      "env": {
        "ONEVIEW_API_ORIGIN": "http://localhost:8080",
        "ONEVIEW_API_BASE_PATH": "/api",
        "ONEVIEW_API_TOKEN_FILE": ""
      }
    }
  }
}

说明：

• ONEVIEW_API_TOKEN_FILE 留空时，只能走“公开分享快照（share token/url）”相关工具；要支持 zentao#16915 这类任务引用，请在本机填上 token 文件路径（不要提交到仓库）。