dsh-tool-grafana

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-tool-grafana

English | [简体中文](./README.zh.md)

Grafana capability for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh).

This plugin owns **no Grafana tool logic**. It composes the community
[`mcp-grafana`](https://github.com/grafana/mcp-grafana) server as a child
[`@deepseek-ai/dsh-mcp-client`](https://www.npmjs.com/package/@deepseek-ai/dsh-mcp-client)
plugin — the model sees `mcp__grafana__*` tools exactly as in any MCP-aware
agent — and layers on what a plain MCP bridge cannot provide:

1. **One config owner** for connection material (URL, service-account token,
   tool-category selection, read-only mode) instead of raw env passthrough.
2. **A standing system-prompt section** (`grafana:workflow`, order 115)
   encoding the upstream context-window discipline: summary before full JSON,
   JSONPath for partial reads, datasource discovery before querying.
3. **An embedded runtime skill** (`grafana-troubleshooting`) teaching a
   systematic alert → dashboard → metrics → logs → incident workflow,
   invocable on both model and user surfaces.

```
┌─ dsh-tool-grafana (this plugin) ─────────────┐
│  config validation · prompt section · skill       │
└──────────────┬─────────────────────────────────────┘
               │ ctx.plugin(dsh-mcp-client, plan)
               ▼
┌─ mcp-grafana (community Go binary, stdio) ────────┐
│  mcp__grafana__search_dashboards                  │
│  mcp__grafana__query_prometheus / loki / ...      │
└───────────────────────────────────────────────────┘
```

The same `mcp-grafana` binary remains directly usable by Cursor, Claude Code,
OpenClaw, etc. — one core, both ecosystems.

## Install into a profile

```sh
dsh plugin --profile web add /path/to/dsh-grafana   # or a published name
```

Then wire it in `~/.dsh/profiles/web/cordis.patch.yml`:

```yaml
- insert:
    - id: grafana
      name: 'dsh-tool-grafana'
      config:
        url: https://myinstance.grafana.net   # default; the settings card can override
        # The token is resolved through the DSH credential store under this
        # reference — never inline in this file:
        tokenCredentialRef: GRAFANA_SERVICE_ACCOUNT_TOKEN
        readOnly: true
        categories: [search, datasource, dashboard, prometheus, loki, alerting]
        launcher:
          kind: uvx
          version: '0.7.9'   # pin the upstream release; omit to track latest
        # kind: binary
        # path: /usr/local/bin/mcp-grafana   # go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@vX.Y.Z
```

Under the **web** profile you can skip the YAML entirely except for the
insert row: open **Settings → Plugins → Grafana observability** and enter
the URL and service-account token in the card. Card values are stored in
the DSH settings document / credential store and **override the patch
config per field**; the patch `url` remains the fallback default.

## Config

| Field | Default | Meaning |
|---|---|---|
| `url` | `''` | Default Grafana base URL; the settings card value (web) overrides it. Both empty fails activation with guidance |
| `tokenCredentialRef` | `GRAFANA_SERVICE_ACCOUNT_TOKEN` | Credential reference resolved through `ctx.credentials` (see below). No inline token field exists, by design |
| `categories` | upstream default set* | mcp-grafana `--enabled-tools` categories |
| `readOnly` | `true` | Default for `--disable-write`; the settings card toggle overrides it (web) |
| `launcher` | `{kind: 'uvx', version: ''}` | How to start the server process; pin `version` (uvx) or use a versioned binary/docker tag to avoid upstream drift |
| `env` | `{}` | Extra env merged into the server process |
| `toolCallTimeoutMs` | `60000` | Per-tool-call timeout (dsh-mcp-client) |

\* `search, datasource, dashboard, folder, prometheus, loki, alerting,
incident, oncall, sift, navigation, annotations`. Heavy backends
(`clickhouse`, `cloudwatch`, `snowflake`, `athena`, `elasticsearch`,
`quickwit`, `graphite`, `influxdb`) and the `runpanelquery`/`examples`/
`agento11y`/`assistant` groups stay opt-in.

## Credentials

The token is resolved through the DSH credential seam (`ctx.credentials`),
not read from a plugin-owned env var. With the default local provider
(`dsh-credentials-local`), the first configured source wins:

1. **Launching environment** — `GRAFANA_SERVICE_ACCOUNT_TOKEN=… dsh web`
2. **Managed store** — `$DSH_HOME/.credentials.yaml` (what the Web Models
   page writes; writable from inside DSH)
3. **Project `.env`** in the invocation directory
4. **User `.env`** at `$DSH_HOME/.env`

There is no inline token config field, so the token can never be committed
into `cordis.patch.yml` or leak through `--dump-config` output.

**Connection changes take effect on profile restart.** The token and URL
are resolved once at activation and handed to the mcp-grafana process
environment; stdio MCP servers cannot receive env updates after spawn.
(Native-tool plugins like the `dsh-grafana` dashboard editor resolve per
tool call and pick up changes live — that is the trade-off of composition
over re-implementation.)

## Web settings card

The package ships a `dsh.client` entry (`client.js`) that mounts a card
under **Settings → Plugins → Grafana observability**:

- **Service Account Token** — written to the credential store (write-only;
  the card shows a mask, never the value)
- **Grafana URL** — stored in the `grafana` settings namespace, shown
  verbatim after saving
- **Read-only toggle** — stored in the same namespace

Precedence is **card value > patch config > activation error**, per field.

## Development

```sh
npm install
npm run build   # tsc → lib/
npm test        # node --test (unit + real-Cordis integration)
```

The integration test boots the plugin under a real Cordis context with the
real `dsh-system-prompt` and `dsh-skill` services, stubbing only the child
mcp-client mount so no Grafana is needed.

## Design notes

- **Why not re-implement the tools natively?** The community server ships 60+
  tools with per-category flags, auth handling, and active upstream
  maintenance. Re-implementing buys nothing and forks the maintenance burden.
- **Why not just `dsh-mcp-client` directly?** You can — one YAML row works.
  This plugin exists for the delta MCP can't express: validated config,
  prompt-level usage discipline, and bundled workflow knowledge.
- **Token hygiene**: the token only ever travels into the child process env,
  never into prompts, tool output, or logs (declared as this package's
  invariant in `./invariant`).

## License

MIT