oneview-mcp

v0.1.4

Published

23 days ago

OneView MCP server (stdio) for fetching AI-friendly task snapshots (ai.md) from OneView.

0High
0Medium
0Low

sugarbliss

mcp model-context-protocol oneview

OneView MCP（stdio 工具服务器）

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

能做什么

支持两条数据路径：

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

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

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

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

创建真实 Redmine 单据（需要鉴权）

AI 先调用 oneview_get_redmine_create_options 查询项目、跟踪、优先级、指派人等合法选项。
AI 再调用 oneview_create_redmine_issue，默认 dry_run=true，只返回预览和校验结果。
只有显式传 dry_run=false 时，OneView 后端才会使用当前用户的 Redmine API Key 创建真实单据。

为什么有时不会自动触发：

很多 Agent / IDE 在选择 MCP 工具时，更依赖“工具名 + 工具描述”。
如果工具名都带 oneview_ 前缀，模型有时只有在用户显式提到 oneview 时才更容易联想到它。
因此这里额外提供了一个通用别名工具 get_issue_info，专门覆盖 zentao#17338 这类自然输入。

如果你需要“硬保证”自动触发：

仅靠 MCP 服务端无法 100% 强制模型调用工具，因为最终是否调用由宿主 Agent / IDE 的工具选择逻辑决定。
要做到稳定自动触发，最好在客户端侧增加一条路由规则：
- 当用户输入匹配 (zentao|redmine|gitlab)#\\d+ 时，直接优先调用 get_issue_info
- 或者把原始请求改写成显式工具意图，例如：使用 get_issue_info 读取 zentao#17338

工具列表（Tools）

oneview_search(query, sources?, limit_each?, time_budget_ms?)（需要 token）
- 搜索 OneView 聚合任务，适合用户问：
  - 搜索 virusos 相关单子
  - 找一下 zentao#18000
  - 查 18000 这个编号
- 支持关键字、zentao#123 / redmine#123 / gitlab#123 精确引用、纯数字 ID。
- sources 可选：zentao、redmine、gitlab。
get_issue_info(input, ttl_hours?)
- 推荐的通用入口
- 适合用户直接说：
  - 拉一下 zentao#17338 单子信息
  - 看下 redmine#123
  - 分析 gitlab#456
- input 支持：
  - 任务引用（需要 token）：zentao#16915
  - 分享 token / 链接（不需要 token）：<token>、/share/<token>、/api/share/<token>、或完整 URL
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_redmine_create_options(project?, tracker?)（需要 token）
- 查询 Redmine 建单字段、默认值、选项和 AI 填写策略。
- 适合 AI 在创建单据前先确认合法项目、跟踪、优先级、指派人和版本。
oneview_create_redmine_issue(...)（需要 token）
- 创建 Redmine 单据，默认 dry_run=true。
- 支持项目、跟踪、状态、优先级、指派人、关注者和版本传 ID、名称或后端配置的别名。
- watchers 对应 Redmine 关注者列表，传成员 ID 或姓名数组，后端会解析成 watcher_user_ids。
- 显式传 dry_run=false 才会真实创建。
oneview_get_share_ai_md(token)（公开）
oneview_get_share_snapshot(token)（公开）
oneview_help()

AI 创建 Redmine 单据的推荐流程：

1. 调 oneview_get_redmine_create_options(project?, tracker?)
2. 按返回的 defaults 和 fields 组装建单参数
3. 调 oneview_create_redmine_issue(..., dry_run=true)
4. 如果返回 ready，再由用户确认或显式调用 dry_run=false 创建真实单据
5. 如果返回 missing_fields / ambiguous_fields / invalid_fields，先补充或澄清字段

示例 dry run：

{
  "project": "USPS",
  "tracker": "错误",
  "subject": "VPN监控 - 过滤规则异常",
  "description": "# 重现条件\n...\n\n# 影响功能\n...",
  "priority": "普通",
  "assigned_to": "me",
  "watchers": ["xxx", 52],
  "dry_run": true
}

环境变量

ONEVIEW_API_ORIGIN：OneView 对外可访问的 origin（默认 http://localhost:8000）
ONEVIEW_API_BASE_PATH：默认 /api
ONEVIEW_API_TOKEN：可选；凡是需要“自动创建分享快照”或“创建 Redmine 单据”的工具都需要它
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 文件路径（不要提交到仓库）。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme