dsh-tool-grafana

English | 简体中文

面向 DeepSeek Harness（dsh）的 Grafana 能力插件。

本插件不拥有任何 Grafana 工具逻辑。它把社区版 mcp-grafana 服务器作为子插件，挂载在 @deepseek-ai/dsh-mcp-client 之上——模型看到的 mcp__grafana__* 工具与任何 MCP 客户端（Cursor、Claude Code 等）完全一致——并在此之上叠加纯 MCP 桥接无法提供的三层增量：

1. 统一的连接配置Owner：URL、服务账号令牌、工具类别选择、只读模式，替代裸环境变量透传。
2. 常驻系统提示段落（grafana:workflow，order 115）：把上游的上下文窗口纪律固化为指令——先看摘要再拉全量 JSON、用 JSONPath 读局部、查询前先发现数据源。
3. 内嵌运行时 skill（grafana-troubleshooting）：系统化的"告警 → 仪表盘 → 指标 → 日志 → incident"排障流程，模型和用户两个入口都可调用。

┌─ dsh-tool-grafana（本插件）──────────────────────┐
│  配置校验 · 提示段落 · skill                      │
└──────────────┬─────────────────────────────────────┘
               │ ctx.plugin(dsh-mcp-client, plan)
               ▼
┌─ mcp-grafana（社区 Go 二进制，stdio）─────────────┐
│  mcp__grafana__search_dashboards                  │
│  mcp__grafana__query_prometheus / loki / ...      │
└───────────────────────────────────────────────────┘

同一个 mcp-grafana 二进制仍可直接被 Cursor、Claude Code、OpenClaw 等使用——一份核心，两个生态。

安装到 profile

dsh plugin --profile web add dsh-tool-grafana

这就是安装的全部：包内置 bundle patch（cordis.patch.yml + dsh.bundle 声明），插件以 schema 默认值自动挂载——无需手写 YAML。随后打开 Settings → Plugins → Grafana observability 完成设置：填写 Grafana URL 和服务账号令牌，重启 profile 即可。

自定义配置（可选）

如需钉住工具类别、launcher 或不用卡片的默认值，在 ~/.dsh/profiles/web/cordis.patch.yml 中加一条同 id 行——profile 层会覆盖包内 bundle 层（后写生效）：

- insert:
    - id: grafana
      name: 'dsh-tool-grafana'
      config:
        url: https://myinstance.grafana.net   # 默认值；设置卡片可覆盖
        # 令牌通过 DSH 凭证库按此引用解析——永不内联到本文件：
        tokenCredentialRef: GRAFANA_SERVICE_ACCOUNT_TOKEN
        readOnly: true
        categories: [search, datasource, dashboard, prometheus, loki, alerting]
        launcher:
          kind: uvx
          version: '0.7.9'   # 钉住上游版本；留空则跟踪最新
        # kind: binary
        # path: /usr/local/bin/mcp-grafana   # go install github.com/grafana/mcp-grafana/cmd/[email protected]

卡片值存储在 DSH 设置文档 / 凭证库中，并按字段覆盖 patch 配置；patch 里的 url 作为兜底默认值保留。

配置项

| 字段 | 默认值 | 含义 | |---|---|---| | url | '' | 默认 Grafana 地址；设置卡片的值（web）会覆盖它。两者皆空则激活失败并给出指引 | | tokenCredentialRef | GRAFANA_SERVICE_ACCOUNT_TOKEN | 通过 ctx.credentials 解析的凭证引用（见下文）。设计上不存在内联令牌字段 | | categories | 上游默认集* | mcp-grafana 的 --enabled-tools 类别 | | readOnly | true | --disable-write 的默认值；设置卡片开关可覆盖（web） | | launcher | {kind: 'uvx', version: ''} | 服务器进程启动方式；钉住 version（uvx）或使用带版本的 binary/docker 镜像，避免上游漂移 | | env | {} | 合并进服务器进程的额外环境变量 | | toolCallTimeoutMs | 60000 | 单次工具调用超时（dsh-mcp-client） |

* search, datasource, dashboard, folder, prometheus, loki, alerting, incident, oncall, sift, navigation, annotations。重量级后端 （clickhouse、cloudwatch、snowflake、athena、elasticsearch、 quickwit、graphite、influxdb）以及 runpanelquery/examples/ agento11y/assistant 组保持按需开启。

凭证

令牌通过 DSH 凭证接缝（ctx.credentials）解析，而非读取插件自己的环境变量。使用默认本地提供者（dsh-credentials-local）时，第一个已配置的来源生效：

1. 启动环境 — GRAFANA_SERVICE_ACCOUNT_TOKEN=… dsh web
2. 托管存储 — $DSH_HOME/.credentials.yaml（Web Models 页写入的位置；可在 DSH 内写）
3. 项目 .env（调用目录下）
4. 用户 .env（$DSH_HOME/.env）

不存在内联令牌配置项，因此令牌不可能被提交进 cordis.patch.yml，也不会通过 --dump-config 输出泄露。

连接变更在 profile 重启后生效。 令牌和 URL 在激活时解析一次并注入 mcp-grafana 进程环境；stdio MCP 服务器启动后无法接收环境更新。（像 dsh-grafana 仪表盘编辑器那样的原生工具插件在每次工具调用时解析、可以实时生效——这是"组合优于重写"的取舍。）

Web 设置卡片

包内置 dsh.client 入口（client.js），在 Settings → Plugins → Grafana observability 下挂载卡片：

• Service Account Token — 写入凭证库（仅写不读；卡片显示掩码，永不显示明文）
• Grafana URL — 存于 grafana settings namespace，保存后明文回显核对
• 只读开关 — 存于同一 namespace

优先级按字段独立生效：卡片值 > patch 配置 > 激活报错。

开发

npm install
npm run build   # tsc → lib/
npm test        # node --test（单元 + 真实 Cordis 集成）

集成测试在真实 Cordis 上下文、真实 dsh-system-prompt 与 dsh-skill 服务下启动本插件，仅对子插件 mcp-client 的挂载打桩，因此不需要真实 Grafana。

设计说明

• 为什么不原生重写这些工具？ 社区服务器提供 60+ 工具、按类别的开关、认证处理和活跃的上游维护。重写买不到任何东西，只会分叉维护负担。
• 为什么不直接用 dsh-mcp-client？ 可以——一行 YAML 就能跑。本插件存在的意义是 MCP 表达不了的增量：受校验的配置、提示词层面的使用纪律、打包的工作流知识。
• 令牌卫生：令牌只会进入子进程环境，永不进入提示词、工具输出或日志（在本包的 ./invariant 中声明）。

License

MIT