From 442f0f22e8095f321eedd6b0ef1a232ad16988f9 Mon Sep 17 00:00:00 2001 From: congtt2 Date: Thu, 10 Sep 2026 18:46:05 +0700 Subject: [PATCH] =?UTF-8?q?[docs]=20vMonitor=20=E2=80=94=20vMonitor=20MCP?= =?UTF-8?q?=20Server=20docs=20+=20Aug=20release=20note=20=E2=80=94=20VI=20?= =?UTF-8?q?+=20EN?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New doc set English/vmonitor/vmonitor-mcp-server + Vietnamese mirror (README, Configure Local MCP, Configure Remote MCP, vMonitor MCP Tools), registered in both SUMMARY files; release-note entry under August 2026 in Product Updates (All) — VI + EN. Co-Authored-By: Claude --- English/SUMMARY.md | 4 + English/overview/product-updates-all/2026.md | 10 + .../vmonitor/vmonitor-mcp-server/README.md | 51 +++ .../configure-local-mcp.md | 96 ++++++ .../configure-remote-mcp.md | 130 +++++++ .../vmonitor-mcp-server/vmonitor-mcp-tools.md | 326 ++++++++++++++++++ Vietnamese/SUMMARY.md | 4 + .../thong-bao-va-cap-nhat/2026.md | 10 + .../vmonitor/vmonitor-mcp-server/README.md | 53 +++ .../configure-local-mcp.md | 96 ++++++ .../configure-remote-mcp.md | 130 +++++++ .../vmonitor-mcp-server/vmonitor-mcp-tools.md | 326 ++++++++++++++++++ 12 files changed, 1236 insertions(+) create mode 100644 English/vmonitor/vmonitor-mcp-server/README.md create mode 100644 English/vmonitor/vmonitor-mcp-server/configure-local-mcp.md create mode 100644 English/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md create mode 100644 English/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md create mode 100644 Vietnamese/vmonitor/vmonitor-mcp-server/README.md create mode 100644 Vietnamese/vmonitor/vmonitor-mcp-server/configure-local-mcp.md create mode 100644 Vietnamese/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md create mode 100644 Vietnamese/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md diff --git a/English/SUMMARY.md b/English/SUMMARY.md index bc7160ab..a45c3e12 100644 --- a/English/SUMMARY.md +++ b/English/SUMMARY.md @@ -539,6 +539,10 @@ * [Getting Start with Logs](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-logs.md) * [Getting Start with Synthetic](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-synthetic.md) * [Install and use the vMonitor Datasource plugin for Grafana](vmonitor/install-vmonitor-grafana-plugin.md) + * [vMonitor MCP Server](vmonitor/vmonitor-mcp-server/README.md) + * [Configure Local MCP](vmonitor/vmonitor-mcp-server/configure-local-mcp.md) + * [Configure Remote MCP](vmonitor/vmonitor-mcp-server/configure-remote-mcp.md) + * [vMonitor MCP Tools](vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md) * [Features of vMonitor Platform](vmonitor/dashboards.md) * [Dashboard](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/README.md) * [Widget](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/widget/README.md) diff --git a/English/overview/product-updates-all/2026.md b/English/overview/product-updates-all/2026.md index 2d90d709..cf484d85 100644 --- a/English/overview/product-updates-all/2026.md +++ b/English/overview/product-updates-all/2026.md @@ -4,6 +4,16 @@ {% tab title="Updates" %} **August 2026** +**vMonitor – vMonitor MCP Server** + +The vMonitor MCP Server connects AI assistants (Claude, Cursor, VS Code…) to the vMonitor Platform over the [Model Context Protocol](https://modelcontextprotocol.io) — manage **Dashboards & Widgets**, **Metric queries**, **Alarms**, **Infrastructure hosts**, **Logs**, **Notifications**, **Quota & usage** and **Synthetic uptime monitors** in plain language. + +* **213 tools** covering all five vMonitor APIs (metric/dashboard, Log, notification, quota-usage, synthetic/uptime) behind a single IAM authentication — plus **11 feature-guide prompts** (Vietnamese). +* **Read-only by default** (110 tools); add `--allow-write` to register the create / update / delete tools. Every tool declares read-only / destructive hints so clients auto-approve reads and warn before destructive calls. +* vMonitor is a **global service** — no region selection needed. +* Run it locally over **stdio** (sharing the `~/.greennode` credentials with the GreenNode CLI), or host it over **HTTP** (the server ships a Docker image) and connect remotely. +* Learn more at [vMonitor MCP Server](../../vmonitor/vmonitor-mcp-server/). + **vDB – PostgreSQL Cluster in HAN region** PostgreSQL Cluster (RDS) is now available in the **HAN-01** region, bringing High Availability PostgreSQL to Hanoi with availability zones HAN01-1A and HAN01-1B. diff --git a/English/vmonitor/vmonitor-mcp-server/README.md b/English/vmonitor/vmonitor-mcp-server/README.md new file mode 100644 index 00000000..9d184b80 --- /dev/null +++ b/English/vmonitor/vmonitor-mcp-server/README.md @@ -0,0 +1,51 @@ +# vMonitor MCP Server + +**vMonitor MCP Server** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants (Claude, Cursor, Gemini, …) a set of tools to manage the **vMonitor Platform** — GreenNode's observability service: dashboards, metric queries, alarms, infrastructure hosts, logs, notifications, quota & usage, and synthetic uptime monitors. + +MCP is an open standard for supplying structured context to LLMs. Instead of clicking through the vMonitor console or calling five different vMonitor APIs, the AI assistant selects and invokes the tools that vMonitor MCP Server exposes — driven by a natural-language request. + +The server covers **all five vMonitor APIs** (metric/dashboard, Log, notification, quota-usage, and synthetic/uptime) behind a **single IAM authentication** — requests are routed to the right API automatically. + +Once connected, ask the AI assistant in plain language to: + +* **Manage dashboards & widgets**: list, inspect, create, clone, update, delete dashboards; add / move / resize widgets; manage variables and saved views. +* **Query metrics**: explore the metric catalogue, run time-series queries, read a resource's metrics straight off its default dashboard. +* **Manage alarms**: create / update / delete metric, log and change-detection alarms; review histories and current status. +* **Monitor infrastructure hosts**: list hosts across GreenNode products (vServer, vStorage, vDB, vLB, vBackup, …), check their current metrics, pause / resume monitoring. +* **Work with logs**: search and export logs; manage log projects, pipelines, processors, archives, refills and resource log mappings. +* **Manage notifications**: create OTP-verified channels — Email, SMS, Slack, Webhook, Telegram, Teams. +* **Track quota & usage**: read usage and prices, then buy / resize quotas (quote first, order after). +* **Run synthetic tests**: manage uptime monitors and probing locations. + +**Safe by default:** the server runs **read-only** — inspect only, nothing is changed. Mutating operations (create/update/delete) register only when the server starts with `--allow-write` (see Configure Local MCP). Quota-order tools spend money — every order offers a zero-cost price quote first. + +### Getting started + +This documentation set covers: + +| Page | Contents | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| Configure Remote MCP | **Host the server over HTTP** (uv or Docker, e.g. behind the AgentBase Gateway) and connect MCP clients with just a URL. | +| Configure Local MCP | Run the server locally over **stdio** — suits Claude Desktop, Cursor, Claude Code, VS Code. Setup, client config, and run flags. | +| vMonitor MCP Tools | All 213 tools by feature area, with access level (read / write / destructive), plus the 11 feature-guide prompts and key workflows. | + +#### Which mode? + +* **Local (stdio)** — run the server on your own machine, authenticating with the credentials in `~/.greennode`. The access level is yours to choose via flags (`--allow-write`). See Configure Local MCP. +* **Remote (HTTP)** — host the server yourself (or let your platform team host it) and connect with only a URL — nothing to install on the client machine. See Configure Remote MCP. + +### Requirements + +* An **MCP client**: Claude Desktop, Claude Code, Cursor, VS Code (Copilot MCP), or any client that speaks MCP. +* **Local (stdio)**: **Python ≥ 3.11**, [`uv`](https://docs.astral.sh/uv/), and **GreenNode credentials** — a service account's `client_id` / `client_secret` from the GreenNode IAM Portal, in `~/.greennode/credentials` (shared with greennode-cli; run `grn configure` once if you haven't). +* **Remote (HTTP)**: the host needs credentials (env vars or mounted `~/.greennode`) — or none at all when every caller brings their own token behind the AgentBase Gateway. + +### Region + +vMonitor is a **global service** — there is no region selection: `GRN_DEFAULT_REGION` is ignored, and every tool talks to the same vMonitor endpoints. (The VKS / vServer MCP servers, by contrast, are region-scoped.) + +### Resources + +* **GreenNode MCP on GitHub** — [https://github.com/GreenNodeHub/greennode-mcp](https://github.com/GreenNodeHub/greennode-mcp) (this server's source: `src/vmonitor-mcp-server`) +* **vMonitor Platform docs** — see the vMonitor Platform section of this documentation +* **Model Context Protocol** — the MCP specification: [modelcontextprotocol.io](https://modelcontextprotocol.io) diff --git a/English/vmonitor/vmonitor-mcp-server/configure-local-mcp.md b/English/vmonitor/vmonitor-mcp-server/configure-local-mcp.md new file mode 100644 index 00000000..056e7918 --- /dev/null +++ b/English/vmonitor/vmonitor-mcp-server/configure-local-mcp.md @@ -0,0 +1,96 @@ +# Configure Local MCP + +**Local MCP** runs **vMonitor MCP Server** as a process on your own machine, connecting the MCP client to vMonitor over **stdio**. The server authenticates with the credentials in `~/.greennode` (shared with greennode-cli) to reach the vMonitor APIs. + +Choose local when you need to set the access level yourself via flags (`--allow-write`) or to run under service-account credentials. If the server is already hosted over HTTP for you, see Configure Remote MCP. + +### Requirements + +* **Python ≥ 3.11**. +* [`uv`](https://docs.astral.sh/uv/) — environment management and Python execution. +* The [`greennode-mcp`](https://github.com/GreenNodeHub/greennode-mcp) repo cloned locally (the client points `--directory` at it; `uv run` installs dependencies on first run). +* An **MCP client**: Claude Desktop, Claude Code, Cursor, or VS Code (Copilot MCP). +* **GreenNode credentials** — two ways to provide them: + * Files `~/.greennode/credentials` + `~/.greennode/config`: install greennode-cli, then run `grn configure`. A service account's `client_id` / `client_secret` from the GreenNode IAM Portal is all that is required. + * Environment variables `GRN_CLIENT_ID` / `GRN_CLIENT_SECRET` (+ `GRN_PROJECT_ID`) — no files needed, and they always override files when both exist. + +> ⚠️ **Security**: never commit `client_secret` to Git. The server keeps tokens in memory only — never written to disk, never logged. + +### Configuration + +Credentials are read from `~/.greennode/credentials` + `~/.greennode/config` (INI format, shared with greennode-cli). Environment variables override the files (highest priority): + +| Variable | Effect | +| ------------------- | --------------------------------------------------------------- | +| `GRN_CLIENT_ID` | Override `client_id` | +| `GRN_CLIENT_SECRET` | Override `client_secret` | +| `GRN_PROFILE` | Select a profile (default: `default`) | +| `GRN_PROJECT_ID` | Override `project_id` | + +vMonitor is a **global service** — this server takes no region setting: `GRN_DEFAULT_REGION` is ignored even when set. + +### Add to MCP client + +With **stdio** the MCP client spawns the server itself from the `command` / `args` in its config — there is no server to start by hand. **Read-only** is the default; add flags to `args` to widen access: + +| Flag | Effect | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| _(no flag)_ | Read-only: read / query / guide tools only — **110 tools**. | +| `--allow-write` | Registers all create / update / delete tools → **213 tools**, including quota orders (money-spending). | + +#### Claude Desktop / Cursor + +Add an entry under `mcpServers`, pointing `--directory` at the `greennode-mcp` repo root: + +```json +{ + "mcpServers": { + "vmonitor": { + "command": "uv", + "args": [ + "run", + "--directory", "/path/to/greennode-mcp", + "vmonitor-mcp-server", + "--allow-write" + ] + } + } +} +``` + +Drop `--allow-write` if read-only is enough for your use case. + +#### Claude Code + +```bash +claude mcp add vmonitor -- \ + uv run --directory /path/to/greennode-mcp vmonitor-mcp-server --allow-write + +# Verify +claude mcp list +``` + +#### Visual Studio Code (Copilot MCP) + +Add a similar entry to `.vscode/mcp.json` or `settings.json`, with the same `command` / `args` as the Claude Desktop section. + +### Test the server + +To try the tools before wiring a client, run the **MCP Inspector** from the repo root: + +```bash +npx @modelcontextprotocol/inspector uv run vmonitor-mcp-server # read-only, 110 tools +npx @modelcontextprotocol/inspector uv run vmonitor-mcp-server --allow-write # all 213 tools +``` + +In the UI: Transport Type = `STDIO` → **Connect** → **Tools** → **List Tools**. A good first call is `list_dashboards` — if it returns your dashboards, authentication works. + +### Troubleshooting + +**Authentication fails (401):** Check `client_id` / `client_secret` in `~/.greennode/credentials` (run `grn configure`), or the `GRN_CLIENT_ID` / `GRN_CLIENT_SECRET` env vars. Call `list_dashboards` to confirm the IAM token can be obtained and vMonitor answers. + +**Wrong project / resources missing:** Check `GRN_PROJECT_ID` and `GRN_PROFILE`. vMonitor is global — there is no region to double-check on this server. + +**The agent reports a tool as unavailable:** The server is running read-only. Add `--allow-write`, then restart the client — write tools are not registered at all without the flag, so the agent cannot see them. + +**Cannot connect:** Verify `--directory` points at the repo root and that `uv sync` has finished. Check the client log for startup errors. diff --git a/English/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md b/English/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md new file mode 100644 index 00000000..ab3aa34c --- /dev/null +++ b/English/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md @@ -0,0 +1,130 @@ +# Configure Remote MCP + +Remote MCP is **vMonitor MCP Server hosted over HTTP** (**streamable-http**): the MCP client connects with nothing but a URL — no Python/`uv` install, no repo clone, and no `~/.greennode` on the client machine. + +You host the server yourself (or your platform team does) — either directly, or behind the **AgentBase Gateway**. Behind the gateway, authentication is centralized: the gateway handles the sign-in and forwards the caller's identity to the server, so every vMonitor call runs under the signed-in user's account, project and permissions. Many users can share one endpoint and each still sees only their own resources. + +### Host the server + +Two ways, both from the [`greennode-mcp`](https://github.com/GreenNodeHub/greennode-mcp) repo: + +**Option 1 — run with uv (HTTP transport):** + +```bash +uv run vmonitor-mcp-server --transport streamable-http --host 0.0.0.0 --port 8080 +``` + +The default bind is `127.0.0.1:8000` — set `--host 0.0.0.0` (and a port) when clients connect from other machines. + +**Option 2 — Docker:** + +```bash +# Build (from the repo root) +docker build -f src/vmonitor-mcp-server/Dockerfile -t vmonitor-mcp-server . + +# Run (streamable-http on :8080); pass credentials via env or mounted ~/.greennode +docker run --rm -p 8080:8080 \ + -e GRN_CLIENT_ID= -e GRN_CLIENT_SECRET= \ + vmonitor-mcp-server +``` + +Notes for either option: + +* `GET /health` is always unauthenticated — use it for liveness / readiness checks. +* **Access level is set at server start**: read-only by default (**110 tools**); add `--allow-write` to register all **213 tools**. Decide deliberately — the quota-order tools spend money. +* The HTTP transport can boot with **no credentials at all** when running behind the AgentBase Gateway in passthrough mode — every request then requires a caller token. + +### Authentication (HTTP transport) + +Identity is resolved **per request**, with no flags: + +1. The request carries an IAM bearer token in `Authorization` (the AgentBase Gateway forwards the caller's token) → **every vMonitor call runs as that caller**. A rejected user token errors out — it is never silently retried as the service account. +2. No token, but service-account credentials configured on the host (env vars or `~/.greennode`) → the shared service account is used. +3. Neither → **401** + `WWW-Authenticate: Bearer`. + +Additional notes: + +* **stdio (local) always requires service-account credentials**; only the HTTP transport supports the no-credentials passthrough mode. +* The server does not verify tokens itself — the vMonitor APIs are the verifier. A stale token surfaces as `500 IAM_VALIDATION_ERROR`, is treated as an auth failure, and is refreshed once. +* `--auth-debug` (or `GRN_MCP_AUTH_DEBUG=1`) enables opt-in, redacted, HTTP-only diagnostic logging of inbound auth summaries and exposes an unauthenticated `GET /whoami`. It never verifies signatures and never logs full tokens — **do not enable it in production**. + +### Remote MCP endpoint + +| Service | Remote MCP Server URL | Service key | +| ------------------------------------------------ | --------------------------------- | ----------- | +| **vMonitor — GreenNode observability platform** | `` | `vmonitor` | + +Replace `` with the endpoint your deployment exposes — e.g. `https://:8080` for a direct deployment, or your AgentBase Gateway endpoint (such as `https://gw-vmonitor-mcp-server-.agentbase-gateway.aiplatform.vngcloud.vn/vmonitor_mcp_server`) when fronted by the gateway. + +This endpoint exposes the same tool set as local mode — see vMonitor MCP Tools. The access level (read-only / write) is fixed by whoever deployed it. + +### Add to MCP client + +#### Claude Code + +```bash +claude mcp add --transport http vmonitor + +# Verify + sign in +claude mcp list +``` + +When the endpoint sits behind the AgentBase Gateway, run `/mcp` in Claude Code → select `vmonitor` → **Authenticate** to open the browser sign-in flow (OAuth 2.1, the client refreshes the token on its own). + +#### Claude Desktop / claude.ai + +Settings → **Connectors** → **Add custom connector** → paste the endpoint URL. Behind the AgentBase Gateway, Claude opens the GreenNode sign-in page on first use. + +Remote MCP does **not** use `command` / `args` / environment variables the way stdio does. + +#### Cursor + +Add a remote-style entry to `mcp.json` — only `url` is needed: + +```json +{ + "mcpServers": { + "vmonitor": { + "url": "" + } + } +} +``` + +See [Cursor — Model Context Protocol](https://docs.cursor.com/context/model-context-protocol). + +#### Visual Studio Code + +Add the same kind of entry to `.vscode/mcp.json`. See [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). + +#### Direct HTTP without the gateway + +For a deployment without the AgentBase Gateway, clients that do not drive an OAuth flow can send a bearer token explicitly: + +```json +{ + "mcpServers": { + "vmonitor": { + "type": "http", + "url": "", + "headers": { + "Authorization": "Bearer ${GREENNODE_MCP_TOKEN}" + } + } + } +} +``` + +The token is an IAM bearer token — every call then runs as that identity. + +### Troubleshooting + +**401 (unauthenticated):** The caller did not bring a valid token and the host has no service-account credentials. Behind the gateway, re-run the client's authenticate flow (`/mcp` → `vmonitor` → Authenticate in Claude Code); on a direct deployment, check the `Authorization: Bearer` header. + +**403 `Access denied`:** The token is valid but the principal is not authorized on the gateway. Sign in with an **IAM user** of an authorized account. + +**500 `IAM_VALIDATION_ERROR`:** A stale token — the server refreshes it once; if the error persists, sign in again. + +**The agent reports a tool as unavailable:** The hosted endpoint's access level is fixed at deployment (read-only / write) — the client cannot add flags. If you need a write operation the endpoint does not allow, use Configure Local MCP. + +**Is the server up?** `GET /health` on the endpoint — always open, no token needed. diff --git a/English/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md b/English/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md new file mode 100644 index 00000000..a38e72b3 --- /dev/null +++ b/English/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md @@ -0,0 +1,326 @@ +# vMonitor MCP Tools + +vMonitor MCP Server provides tools to manage and automate the **vMonitor Platform** — GreenNode's observability service: dashboards & widgets, metric queries, alarms, infrastructure hosts, logs, notifications, quota & usage, and synthetic uptime monitors. The server fronts **five vMonitor APIs** (metric/dashboard, Log, notification, quota-usage, synthetic/uptime) behind a single IAM authentication — requests are routed to the right API automatically. Every operation is exposed as a **tool with argument-based input** — no resource URIs are used. + +### Tool groups + +| Group | Purpose | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| Dashboards | List / inspect / create / clone / update / delete dashboards. | +| Widgets, variables & views | Add / edit / move / resize widgets; manage shared variables and saved views. | +| Metric query | Time-series and single-value statistics — the data behind every chart. | +| Metric catalogue & units | Metric names, dimensions, values, units and per-user unit overrides. | +| Infrastructure hosts | Agent-based hosts and product hosts (vServer, vStorage, vDB, vLB, vBackup, vBandwidth, vAS) + their metric snapshots. | +| Alarms | Metric / log / change-detection alarms: create / update / delete, histories and statuses. | +| Integrations & metric API keys | Install / uninstall metric-source integrations; issue / revoke metric API keys. | +| Logs — projects & search | Log projects, certificates, field mappings, log search and export. | +| Logs — archives & refills | Export destinations (archives) and re-ingest jobs (refills). | +| Logs — pipelines & processors | Processing pipelines, processor groups, processors and libraries. | +| Logs — resource mappings | Resource → project log mappings (vCDN, vDB, vLB, vStorage, vStorage bucket). | +| Notifications | OTP-verified channels: Email, SMS, Slack, Webhook, Telegram, Teams. | +| Quota & usage | Usage reads, tier / package catalog, price quotes. | +| Quota orders | Buy / resize / delete quotas — **spends money**; every order has a zero-cost pre-flight quote. | +| Synthetic | Uptime monitors and probing locations. | +| Feature guide | Step-by-step guide for each composite feature. | + +### Conventions + +* **`verb_noun` naming**, one handler per feature area. +* **Access** is noted per tool: + * `read` — always available. The default read-only mode registers **110 tools**. + * `write` — requires the `--allow-write` flag. These tools are **not registered** without it, so the agent cannot see them. + * `destructive` — also requires `--allow-write`; the tool deletes data irreversibly or spends money. Clients warn before the call. +* **Global service**: vMonitor has no regions — no tool takes a `region` parameter, and `GRN_DEFAULT_REGION` is ignored. +* **Annotations**: every tool declares `readOnlyHint` / `destructiveHint` so clients can auto-approve reads and warn before destructive calls. +* **Structured JSON output** with `outputSchema` + `structuredContent` — clients parse it directly. +* **Paging**: list tools take 1-based `page` / `size` (omit `page` to fetch everything where noted); log list endpoints use a `content`-based paging envelope. +* **Money-spending**: quota-order tools (`create_log_project`, `resize_*`) spend money — always call `get_creation_price` / `get_resize_price` first (free, and it validates the payload). + +*** + +### Supported Tools + +#### Dashboards + +| Tool | Access | Description | +| -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | +| `list_dashboards` | read | List dashboards; optional `searching_text` / `searching_field` filter, 1-based `page` / `size` paging (omit `page` for all). | +| `get_dashboard` | read | Single dashboard by ID (includes widget count). | +| `get_dashboard_by_name` | read | Single dashboard by exact name. | +| `create_dashboard` | write | Create an empty dashboard (only `name` required). | +| `create_dashboard_clone` | write | Clone a dashboard into a new one. | +| `update_dashboard` | write | Update general settings (dark mode, refresh, time range, selected view). | +| `update_dashboard_name` | write | Rename a dashboard. | +| `update_dashboard_favorite`| write | Mark / unmark favorite. | +| `delete_dashboard` | destructive | Delete a dashboard (irreversible). | + +#### Widgets, variables & views + +| Tool | Access | Description | +| --------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | +| `list_dashboard_variables` | read | Shared query variables of a dashboard. | +| `get_dashboard_variable` | read | One shared variable. | +| `update_dashboard_variables`| write | Replace a dashboard's variable list (whole-list replace). | +| `list_dashboard_views` | read | Saved query / filter / time-range presets. | +| `get_dashboard_view` | read | One saved view. | +| `create_dashboard_view` | write | Save the current dashboard state as a named view. | +| `update_dashboard_view` | write | Update a saved view's stored state. | +| `delete_dashboard_view` | destructive | Delete a saved view (irreversible). | +| `list_widgets` | read | Dashboard widgets **plus the metric query behind each** — replay via `get_statistics_v2` with no dimension discovery. | +| `get_widget` | read | One widget (chart config + graph specs). | +| `create_widget` | write | Add a widget (v2 `graphs` map; omit `layout` to auto-place on the 10-column grid). | +| `update_widget` | write | Edit widget content (v1 `metricGraphs` / `logGraphs` arrays). | +| `update_widget_v2` | write | Edit widget content (v2 `graphs` map). | +| `update_widget_layout` | write | Move / resize a widget and adjust its time window. | +| `delete_widget` | destructive | Delete a widget (irreversible). | + +#### Metric query + +| Tool | Access | Description | +| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------- | +| `get_statistics` | read | Time-series data (filter by dimensions, `group_by`, window) — the data behind a chart. | +| `get_statistics_synthetic` | read | Single aggregated value (number / single-stat charts). | +| `get_statistics_v2` | read | Typed statistic query (`type` = `SIMPLE` / `CUSTOM` + `data` body) — replays a widget's query as-is. | + +#### Metric catalogue & units + +| Tool | Access | Description | +| ----------------------------- | ----------- | ---------------------------------------------------------------------------- | +| `get_metric_names` | read | Metric catalogue — the starting point for picking a metric. | +| `list_metric_dimension_names` | read | Every dimension key known across metrics. | +| `list_metric_dimension_values`| read | Observed values of one dimension (e.g. hosts for `host`). | +| `get_metric_dimensions` | read | A metric's dimensions + each dimension's observed values. | +| `list_metric_units` | read | Units assignable to a metric. | +| `list_metric_unit_mappings` | read | Metric → unit mappings shown in info panels. | +| `create_metric_unit_mapping` | write | Override a metric's display unit for the current user. | +| `delete_metric_unit_mapping` | destructive | Reset the display unit (remove the override). | + +#### Infrastructure hosts + +Agent-based hosts (Metric Agent servers) plus product resources monitored as hosts. The `` families expand to one tool per product type — `vserver`, `vstorage`, `vdb`, `vlb`, `vbackup`, `vbandwidth`, `vas` (vDB Kafka has a list tool only). Host-listing tools always send `page` / `size` and accept an optional `name` filter. + +| Tool | Access | Description | +| ------------------------------------------------- | ----------- | ------------------------------------------------------- | +| `list_hosts` | read | Agent-based infrastructure hosts. | +| `get_host` | read | One agent-based host by ID. | +| `get_host_metrics` | read | Host's current metric snapshot (status + CPU / load / memory). | +| `update_host_enabled` / `update_host_disabled` | write | Resume / pause monitoring of an agent-based host (agent stays installed). | +| `delete_host` | destructive | Remove an agent-based host from the Infrastructure list (irreversible). | +| `list_vserver_hosts` / `list_vstorage_hosts` / `list_vdb_hosts` / `list_vdb_kafka_hosts` / `list_vlb_hosts` / `list_vbackup_hosts` / `list_vbandwidth_hosts` / `list_vas_hosts` | read | List product resources monitored as hosts. | +| `get__host_metrics` | read | Metric snapshot for a product host. | +| `update__host` | write | Enable / disable monitoring for a product host (body `{enabled}`). | +| `delete__host` | destructive | Remove a product host (irreversible). | + +#### Alarms + +Metric, synthetic, log and change-detection alarms. Create / update bodies are flat, fully-typed DTOs — `name` is the only strictly required field. + +| Tool | Access | Description | +| -------------------------------- | ----------- | ------------------------------------------------------------------------------ | +| `list_alarms` | read | List alarms (filter by name / severity / status / type). | +| `get_alarm` | read | One alarm by ID (with type-specific config). | +| `get_metric_alarm_definition` | read | Metric alarm's upstream evaluator definition. | +| `list_metric_alarm_histories` | read | Metric alarm history (id = a sub-alarm `alarms[].id` from the definition). | +| `get_synthetic_alarm_definition` | read | Synthetic metric alarm's definition. | +| `list_synthetic_alarm_histories` | read | Synthetic alarm history (id = sub-alarm from the definition). | +| `list_log_alarm_histories` | read | Log alarm history. | +| `get_log_alarm_status` | read | Log alarm's current status. | +| `get_change_alarm` | read | Change-detection alarm's definition (requires a time window). | +| `list_change_alarm_histories` | read | Change alarm history (requires a time window). | +| `create_metric_alarm` / `update_metric_alarm` | write | Create / edit a metric alarm (severity / condition case-insensitive). | +| `delete_metric_alarm` | destructive | Delete a metric alarm (irreversible). | +| `delete_metric_sub_alarm` | destructive | Delete a composite metric alarm's sub-alarm. | +| `create_log_alarm` / `update_log_alarm` | write | Create / edit a log alarm. | +| `delete_log_alarm` | destructive | Delete a log alarm (irreversible). | +| `create_change_alarm` / `update_change_alarm` | write | Create / edit a change-detection alarm. | +| `delete_change_alarm` | destructive | Delete a change alarm (irreversible). | +| `delete_change_alarm_history` | destructive | Clear change alarm history (irreversible). | + +#### Integrations & metric API keys + +| Tool | Access | Description | +| ----------------------------- | ----------- | ------------------------------------------------- | +| `list_integrations` | read | Installable metric-source apps. | +| `get_integration` | read | One integration. | +| `update_integration_installed` / `update_integration_uninstalled` | write | Install / uninstall an integration. | +| `delete_integration` | destructive | Delete an integration (irreversible). | +| `list_metric_api_keys` | read | List metric API keys. | +| `create_metric_api_key` | write | Issue a new metric API key. | +| `delete_metric_api_key` | destructive | Revoke a metric API key (irreversible). | + +#### Logs — projects, search & export + +`search_logs` / `search_logs_default` take a structured `{type,value}` DSL (match / range / exists / bool; Elasticsearch shorthands are translated). + +| Tool | Access | Description | +| --------------------------------- | ----------- | ---------------------------------------------------------------------------- | +| `list_projects` | read | Log projects (Log API). | +| `get_project` | read | One log project. | +| `get_project_mappings` | read | A project's field mappings. | +| `get_project_log_data_exists` | read | Whether a log project has ingested data. | +| `search_logs` / `search_logs_default` | read | Query a project's data with the structured DSL. | +| `get_log_export` | read | Track an asynchronous log export. | +| `get_project_certificate_download`| read | Download a project certificate (base64 ZIP; `cert_id` from `list_projects` → `certInfos[]`). | +| `update_project` / `update_project_mappings` | write | Edit a project's settings / field mappings. | +| `create_project_certificate` | write | Issue a project client certificate. | +| `delete_project_certificate` | destructive | Revoke a project client certificate. | +| `create_log_export` | write | Prepare an asynchronous log export. | + +#### Logs — archives & refills + +| Tool | Access | Description | +| ----------------------------- | ----------- | ------------------------------------------ | +| `list_archives` / `get_archive` | read | Log archives (export destinations). | +| `validate_archive_connection` | read | Test archive storage connectivity. | +| `create_archive` / `update_archive` | write | Create / edit a log archive. | +| `delete_archive` | destructive | Delete a log archive. | +| `list_refills` / `get_refill` | read | Log refill (re-ingest) jobs. | +| `validate_refill_connection` | read | Test refill storage connectivity. | +| `create_refill` / `create_refill_from_archive` | write | Create a refill job. | +| `delete_refill` | destructive | Delete a refill job. | + +#### Logs — pipelines & processors + +| Tool | Access | Description | +| -------------------------------------- | ----------- | ---------------------------------------------------- | +| `list_pipelines` / `get_pipeline` | read | Log processing pipelines. | +| `create_pipeline` / `update_pipeline` | write | Create / edit a pipeline. | +| `delete_pipeline` | destructive | Delete a pipeline. | +| `get_processor_group` | read | One processor group. | +| `list_processor_group_libraries` | read | Processor group libraries. | +| `list_date_formats` | read | Date-format helpers. | +| `validate_grok_parser` | read | Validate a grok parser. | +| `create_processor_group` / `update_processor_group` / `update_processor_order` / `create_processor_group_library` | write | Manage processor groups and their order. | +| `delete_processor_group` | destructive | Delete a processor group. | +| `create_processor` / `update_processor`| write | Manage processors. | +| `delete_processor` | destructive | Delete a processor. | + +#### Logs — resource mappings + +The `` placeholder expands to `vcdn`, `vdb`, `vlb`, `vstorage` (plus a dedicated vStorage bucket tool). + +| Tool | Access | Description | +| ---------------------------------------------------------------------- | ------ | -------------------------------------------------- | +| `list__log_mappings` (+ `list_vstorage_bucket_log_mappings`) | read | Resource → project log mappings. | +| `list_vcdn_log_mapping_types` / `list_vstorage_log_mapping_regions` | read | Mapping type / region lookups. | +| `update__log_mapping[_enabled\|_disabled]` | write | Edit / enable / disable a resource log mapping. | +| `update_vstorage_bucket_log_mapping` | write | Set a vStorage bucket's log mapping. | + +#### Notifications + +Channel creation is OTP-verified: `create_notification_otp` → `validate_notification_otp` → `create_notification`. Channels cover Email, SMS, Slack, Webhook, Telegram, Teams. + +| Tool | Access | Description | +| --------------------------- | ----------- | -------------------------------------------------- | +| `list_notification_types` | read | Channel types. | +| `list_notifications` | read | Notification channels. | +| `get_notification_otp_info` | read | Pending OTP info. | +| `create_notification_otp` | write | Send an OTP to a channel address. | +| `validate_notification_otp` | write | Validate the OTP. | +| `create_notification` / `update_notification` | write | Create / edit an (OTP-verified) channel. | +| `delete_notification` | destructive | Delete a notification channel (irreversible). | + +#### Quota & usage (reads — free) + +| Tool | Access | Description | +| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------- | +| `get_quota_usage` / `get_log_usage` / `get_composite_usage` | read | Usage per category / per log project / combined. | +| `get_current_quota` / `list_log_quotas` / `get_log_quota` / `get_quota_detail` | read | Current active quota and its detail. | +| `get_billing_settings` / `list_trash_quotas` / `get_convert_result` | read | Billing settings / trashed quotas / conversion result. | +| `list_tiers` / `get_tier` / `get_tier_description` | read | Quota tier catalog (metric / synthetic / log). | +| `list_packages` / `get_package` / `get_package_detail` / `get_package_description` / `get_package_description_detail` | read | Purchasable package catalog. | +| `list_quota_classes` / `list_quota_class_packages` | read | v2 quota classes and their packages. | +| `get_creation_price` / `get_resize_price` / `get_recovery_price` / `get_renewal_price` | read | Price quotes (no order placed). | + +#### Quota orders (money-spending; `--allow-write` only) + +Every order has a zero-cost pre-flight via `get_creation_price` / `get_resize_price`. + +| Tool | Access | Description | +| ---------------------- | ----------- | ----------------------------------------------------------------------------------------------- | +| `create_log_project` | write | Buy a new log project — the log quota order creates the project (**spends money**). | +| `resize_log_project` | destructive | Grow quota / upgrade Basic → Pro (**spends money**, irreversible). | +| `delete_log_project` | destructive | Delete a project, its quota and stored logs (irreversible). | +| `resize_metric_quota` | destructive | Resize the account's single metric quota (**spends money**, irreversible). | +| `resize_sms_quota` / `resize_email_quota` | destructive | Swap SMS / email notification quota to another package (**spends money**, irreversible). | + +Renew and recover-from-trash remain quote-only. Orders respond with `order_id`, `amount` and `payment_url` — a non-empty `payment_url` means **pending** (the quota changes only after the user pays via that link); `pay: true` charges the account directly. + +#### Synthetic (uptime monitors & locations) + +| Tool | Access | Description | +| ----------------------------------------------- | ----------- | ------------------------------------------------- | +| `list_uptimes` / `get_uptime` / `get_uptime_config` / `validate_uptime` | read | Uptime monitors + probe preview. | +| `create_uptime` / `update_uptime` / `update_uptime_status` | write | Create / edit / toggle a monitor. | +| `delete_uptime` | destructive | Delete a monitor (irreversible). | +| `list_locations` / `get_location` | read | Synthetic probing locations. | +| `create_location` / `update_location` | write | Create / edit a private probing location. | +| `delete_location` | destructive | Delete a probing location (irreversible). | + +#### Feature guide + +| Tool | Access | Description | +| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `get_feature_guide`| read | Step-by-step guide for a composite feature: `build_dashboard`, `query_metrics`, `create_metric_alarm`, `monitor_infrastructure`, `edit_metric_unit`, `manage_log_projects`, `manage_integrations`, `create_notification_channel`, `view_quota_usage`, `create_uptime_monitor`. | + +*** + +### Prompts (11) + +The server ships **11 prompts** (Vietnamese) — step-by-step feature guides, always available (no `--allow-write` needed). Load them from the client's prompt list (e.g. the prompt picker in Claude Code), or let the agent call the `get_feature_guide` tool with the same feature key. + +| Prompt | Purpose | +| ----------------------------------- | --------------------------------------------------------------------------------- | +| `vmonitor_getting_started` | Onboarding: concepts, auth setup, no-region model, tool routing, feature map. | +| `vmonitor_build_dashboard` | Dashboards + variables + views + widgets (incl. the `graphs` / auto-layout shape).| +| `vmonitor_query_metrics` | Query metrics / plot data, search & export logs (incl. the log search DSL). | +| `vmonitor_create_metric_alarm` | Create an alarm (metric / log / change-detection): source → threshold → notification → confirm gate. | +| `vmonitor_monitor_infrastructure` | Explore infrastructure hosts and their metrics. | +| `vmonitor_edit_metric_unit` | Override a metric's display unit. | +| `vmonitor_manage_log_projects` | Manage log projects, mappings, certificates. | +| `vmonitor_manage_integrations` | Install / uninstall metric-source integrations. | +| `vmonitor_create_notification_channel` | OTP-verified notification-channel creation. | +| `vmonitor_view_quota_usage` | Read quota usage and prices, then buy / resize / delete a quota. | +| `vmonitor_create_uptime_monitor` | Create a synthetic uptime monitor + probing location. | + +### Key workflows + +#### Read a resource's metrics off its default dashboard + +Every GreenNode resource owns an auto-generated **system dashboard**, and each widget stores the exact query the console plots (metric name, statistic, grouping, full `dimensions` string carrying the `resource_id`). So "how is this server doing?" needs no metric-catalogue walk: + +``` +list_dashboards searching_text="" → dashboard id +list_widgets dashboard_id= → metric_queries per widget +get_statistics_v2 body={"type":"SIMPLE","data":{"graph":{ + "name": , "statistics": , + "dimensions": , # use as-is + "group_by": , "offset":0, "limit":"", "rollup":"", "rate":0}, + "start_time":, "end_time":, + "period":, "alarm":false}} +``` + +Reusing the widget's `period` matches the web chart. Widgets with `log_graph_count > 0` plot log data — query those with `search_logs`. + +#### Buy or resize a quota (money-spending, `--allow-write`) + +`packageId` lives on a quota class's retention entries, along with the bounds the `quantity` must respect. The quote call both prices and validates the payload: + +``` +list_quota_classes category=log → class → config.retentions[]: + { amount: 7, minSize: 20, maxSize: 5000, + step: 10, packageId: "" } +quantity = * # log quota: GB-days +get_creation_price category=log package_id= quantity= # zero cost +create_log_project body={"projectName":"my-logs", + "packageId":"", "quantity":} +``` + +Leave `redirectUrl` alone — each order tool fills in the vMonitor console's quota page automatically. Resizing follows the same shape (`get_resize_price` → `resize_log_project`; `resize_metric_quota` uses host counts and `minResource` / `maxResource` / `step`). SMS / email are fixed bundles from `list_packages category=sms|email` — no `quantity`. + +### Usage notes + +* **Argument-based input, no resource URIs.** Every operation is a tool. +* **Read-only by default** (110 tools). Writes need `--allow-write` — see Configure Local MCP. On a hosted endpoint the access level is fixed by whoever deployed it. +* **Quote before ordering, inspect before deleting.** Quota orders always have a free pre-flight quote; before irreversible deletes, read the resource's detail / history tools first. +* **Every infrastructure host owns an auto-generated, read-only default dashboard** — the fastest path to a resource's metrics. diff --git a/Vietnamese/SUMMARY.md b/Vietnamese/SUMMARY.md index 73487d1b..aad63e35 100644 --- a/Vietnamese/SUMMARY.md +++ b/Vietnamese/SUMMARY.md @@ -620,6 +620,10 @@ * [Bắt đầu với Logs](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-logs.md) * [Bắt đầu với Synthetic](vmonitor-platform/bat-dau-voi-vmonitor-platform/bat-dau-voi-synthetic.md) * [Cài đặt và sử dụng vMonitor Datasource Plugin cho Grafana](vmonitor/cai-dat-vmonitor-grafana-plugin.md) + * [vMonitor MCP Server](vmonitor/vmonitor-mcp-server/README.md) + * [Configure Local MCP](vmonitor/vmonitor-mcp-server/configure-local-mcp.md) + * [Configure Remote MCP](vmonitor/vmonitor-mcp-server/configure-remote-mcp.md) + * [vMonitor MCP Tools](vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md) * [Các tính năng của vMonitor Platform](vmonitor/dashboards.md) * [Dashboard](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/README.md) * [Widget](vmonitor-platform/cach-tinh-nang-cua-vmonitor-platform/dashboard/widget/README.md) diff --git a/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md b/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md index d2867ea8..58df31b9 100644 --- a/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md +++ b/Vietnamese/gioi-thieu-chung/thong-bao-va-cap-nhat/2026.md @@ -4,6 +4,16 @@ {% tab title="Nâng cấp mới" %} **Tháng 8, 2026** +**vMonitor – vMonitor MCP Server** + +vMonitor MCP Server kết nối AI assistant (Claude, Cursor, VS Code…) với vMonitor Platform qua chuẩn [Model Context Protocol](https://modelcontextprotocol.io) — quản lý **Dashboard & Widget**, **Metric query**, **Alarm**, **Infrastructure host**, **Log**, **Notification**, **Quota & usage** và **Synthetic uptime monitor** bằng ngôn ngữ tự nhiên. + +* **213 tool** bao phủ toàn bộ năm API của vMonitor (metric/dashboard, Log, notification, quota-usage, synthetic/uptime) sau một lớp xác thực IAM duy nhất — kèm **11 feature-guide prompt** (tiếng Việt). +* **Read-only mặc định** (110 tool); thêm `--allow-write` để đăng ký các tool create / update / delete. Mỗi tool khai báo read-only / destructive hint để client auto-approve read và cảnh báo trước destructive call. +* vMonitor là dịch vụ **global** — không cần chọn region. +* Chạy local qua **stdio** (dùng chung credentials `~/.greennode` với GreenNode CLI), hoặc tự host qua **HTTP** (server kèm sẵn Docker image) rồi kết nối từ xa. +* Tìm hiểu thêm tại [vMonitor MCP Server](../../vmonitor/vmonitor-mcp-server/). + **vDB – PostgreSQL Cluster tại region HAN** PostgreSQL Cluster (RDS) đã có mặt tại region **HAN-01**, mang PostgreSQL High Availability tới Hà Nội với các availability zone HAN01-1A và HAN01-1B. diff --git a/Vietnamese/vmonitor/vmonitor-mcp-server/README.md b/Vietnamese/vmonitor/vmonitor-mcp-server/README.md new file mode 100644 index 00000000..387cf115 --- /dev/null +++ b/Vietnamese/vmonitor/vmonitor-mcp-server/README.md @@ -0,0 +1,53 @@ +# vMonitor MCP Server + +## vMonitor MCP Server + +**vMonitor MCP Server** là một [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server, cung cấp cho các AI assistant (Claude, Cursor, Gemini, …) một bộ tool để quản lý **vMonitor Platform** — dịch vụ observability của GreenNode: dashboard, metric query, alarm, infrastructure host, log, notification, quota & usage, và synthetic uptime monitor. + +MCP là một chuẩn mở để cung cấp structured context cho các LLM. Thay vì thao tác qua console vMonitor hay gọi trực tiếp năm API vMonitor khác nhau, AI assistant sẽ tự chọn và invoke các tool mà vMonitor MCP Server expose — dựa trên yêu cầu bằng ngôn ngữ tự nhiên của bạn. + +Server bao phủ **toàn bộ năm API của vMonitor** (metric/dashboard, Log, notification, quota-usage, và synthetic/uptime) sau **một lớp xác thực IAM duy nhất** — request được tự động route tới đúng API. + +Sau khi kết nối, bạn có thể yêu cầu AI assistant bằng ngôn ngữ tự nhiên để: + +* **Quản lý dashboard & widget**: liệt kê, xem chi tiết, tạo, clone, cập nhật, xóa dashboard; thêm / di chuyển / resize widget; quản lý variable và saved view. +* **Query metric**: khám phá metric catalogue, chạy time-series query, đọc metric của một resource ngay từ default dashboard của nó. +* **Quản lý alarm**: tạo / cập nhật / xóa alarm metric, log và change-detection; xem lịch sử và trạng thái hiện tại. +* **Giám sát infrastructure host**: liệt kê host trên các sản phẩm GreenNode (vServer, vStorage, vDB, vLB, vBackup, …), xem metric snapshot hiện tại, tạm dừng / mở lại giám sát. +* **Làm việc với log**: search và export log; quản lý log project, pipeline, processor, archive, refill và resource log mapping. +* **Quản lý notification**: tạo channel đã xác thực OTP — Email, SMS, Slack, Webhook, Telegram, Teams. +* **Theo dõi quota & usage**: đọc mức sử dụng và giá, sau đó mua / resize quota (báo giá trước, đặt hàng sau). +* **Chạy synthetic test**: quản lý uptime monitor và probing location. + +**An toàn theo mặc định:** server chạy ở chế độ **read-only** — chỉ xem, không đổi gì. Các thao tác thay đổi (create/update/delete) chỉ được đăng ký khi server khởi động với `--allow-write` (xem Configure Local MCP). Các tool đặt hàng quota tiêu tốn tiền — mọi đơn hàng đều có bước báo giá miễn phí trước đó. + +### Getting started + +Bộ tài liệu này gồm các trang: + +| Trang | Nội dung | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Configure Remote MCP | **Tự host server qua HTTP** (uv hoặc Docker, ví dụ sau AgentBase Gateway) rồi kết nối MCP client chỉ bằng một URL. | +| Configure Local MCP | Chạy server local qua **stdio** — phù hợp Claude Desktop, Cursor, Claude Code, VS Code. Cài đặt, config client, và các run flag. | +| vMonitor MCP Tools | Toàn bộ 213 tool theo từng nhóm tính năng, kèm access level (read / write / destructive), 11 feature-guide prompt và các workflow chính. | + +#### Chọn mode nào? + +* **Local (stdio)** — chạy server ngay trên máy, authenticate bằng credentials trong `~/.greennode`. Chọn được access level qua flag (`--allow-write`). Xem Configure Local MCP. +* **Remote (HTTP)** — tự host server (hoặc để platform team host) rồi kết nối chỉ với một URL — không cần cài đặt gì trên máy client. Xem Configure Remote MCP. + +### Requirements + +* Một **MCP client**: Claude Desktop, Claude Code, Cursor, VS Code (Copilot MCP), hoặc bất kỳ client nào nói được MCP. +* **Local (stdio)**: **Python ≥ 3.11**, [`uv`](https://docs.astral.sh/uv/), và **GreenNode credentials** — `client_id` / `client_secret` của một service account từ GreenNode IAM Portal, nằm trong `~/.greennode/credentials` (dùng chung với greennode-cli; chạy `grn configure` một lần nếu chưa có). +* **Remote (HTTP)**: máy host cần credentials (env var hoặc mount `~/.greennode`) — hoặc không cần gì cả khi mỗi caller tự mang token của họ phía sau AgentBase Gateway. + +### Region + +vMonitor là dịch vụ **global** — không có chọn region: `GRN_DEFAULT_REGION` bị bỏ qua, mọi tool đều nói chuyện với cùng các endpoint vMonitor. (Trong khi đó, các MCP server VKS / vServer là region-scoped.) + +### Resources + +* **GreenNode MCP trên GitHub** — [**https://github.com/GreenNodeHub/greennode-mcp**](https://github.com/GreenNodeHub/greennode-mcp) (source của server này: `src/vmonitor-mcp-server`) +* **Tài liệu vMonitor Platform** — xem mục vMonitor Platform trong bộ tài liệu này +* **Model Context Protocol** — đặc tả chuẩn MCP: [modelcontextprotocol.io](https://modelcontextprotocol.io) diff --git a/Vietnamese/vmonitor/vmonitor-mcp-server/configure-local-mcp.md b/Vietnamese/vmonitor/vmonitor-mcp-server/configure-local-mcp.md new file mode 100644 index 00000000..ac3b5f85 --- /dev/null +++ b/Vietnamese/vmonitor/vmonitor-mcp-server/configure-local-mcp.md @@ -0,0 +1,96 @@ +# Configure Local MCP + +**Local MCP** chạy **vMonitor MCP Server** như một process ngay trên máy của bạn, kết nối MCP client với vMonitor qua **stdio**. Server xác thực bằng credentials trong `~/.greennode` (dùng chung với greennode-cli) để gọi các API của vMonitor. + +Chọn local khi bạn muốn tự đặt access level qua flag (`--allow-write`) hoặc chạy dưới service-account credentials. Nếu server đã được host sẵn qua HTTP, xem Configure Remote MCP. + +### Requirements + +* **Python ≥ 3.11**. +* [`uv`](https://docs.astral.sh/uv/) — quản lý môi trường và chạy **Python**. +* Repo [`greennode-mcp`](https://github.com/GreenNodeHub/greennode-mcp) clone sẵn trên máy (client trỏ `--directory` tới đây; `uv run` tự cài deps ở lần chạy đầu). +* Một **MCP client**: Claude Desktop, Claude Code, Cursor, hoặc VS Code (Copilot MCP). +* **GreenNode credentials** — cung cấp hai cách: + * File `~/.greennode/credentials` + `~/.greennode/config`: cài greennode-cli rồi chạy `grn configure`. Chỉ cần `client_id` / `client_secret` của một service account từ GreenNode IAM Portal là đủ. + * Environment variable `GRN_CLIENT_ID` / `GRN_CLIENT_SECRET` (+ `GRN_PROJECT_ID`) — không cần file, và luôn override file nếu có cả hai. + +> ⚠️ **Security**: không commit `client_secret` vào Git. Server giữ token in-memory, không ghi ra disk, không log token/secret. + +### Configuration + +Credentials đọc từ `~/.greennode/credentials` + `~/.greennode/config` (định dạng INI, dùng chung với greennode-cli). Environment variable override file (ưu tiên cao nhất): + +| Variable | Tác dụng | +| ------------------- | --------------------------------------- | +| `GRN_CLIENT_ID` | Override `client_id` | +| `GRN_CLIENT_SECRET` | Override `client_secret` | +| `GRN_PROFILE` | Chọn profile (mặc định: `default`) | +| `GRN_PROJECT_ID` | Override `project_id` | + +vMonitor là dịch vụ **global** — server này không có setting region: `GRN_DEFAULT_REGION` bị bỏ qua ngay cả khi bạn đặt. + +### Add to MCP client + +Với **stdio**, MCP client tự spawn server bằng `command` / `args` trong config — không cần chạy server thủ công. **Read-only** là mặc định; thêm flag vào `args` để mở rộng quyền: + +| Flag | Tác dụng | +| --------------- | -------------------------------------------------------------------------------------------------------------------- | +| _(không flag)_ | Read-only: chỉ các tool read / query / guide — **110 tool**. | +| `--allow-write` | Đăng ký toàn bộ tool create / update / delete → **213 tool**, gồm cả các tool đặt hàng quota (tốn tiền). | + +#### Claude Desktop / Cursor + +Thêm entry vào config `mcpServers`, trỏ `--directory` tới thư mục gốc `greennode-mcp`: + +```json +{ + "mcpServers": { + "vmonitor": { + "command": "uv", + "args": [ + "run", + "--directory", "/path/to/greennode-mcp", + "vmonitor-mcp-server", + "--allow-write" + ] + } + } +} +``` + +Bỏ `--allow-write` nếu read-only là đủ cho nhu cầu của bạn. + +#### Claude Code + +```bash +claude mcp add vmonitor -- \ + uv run --directory /path/to/greennode-mcp vmonitor-mcp-server --allow-write + +# Verify +claude mcp list +``` + +#### Visual Studio Code (Copilot MCP) + +Thêm entry tương tự vào `.vscode/mcp.json` hoặc `settings.json`, với cùng `command` / `args` như mục Claude Desktop. + +### Test server + +Để thử các tool trước khi gắn vào client, chạy **MCP Inspector** từ thư mục gốc repo: + +```bash +npx @modelcontextprotocol/inspector uv run vmonitor-mcp-server # read-only, 110 tool +npx @modelcontextprotocol/inspector uv run vmonitor-mcp-server --allow-write # đủ 213 tool +``` + +Trên UI: Transport Type = `STDIO` → **Connect** → **Tools** → **List Tools**. Lệnh gọi thử tốt nhất là `list_dashboards` — nếu trả về dashboard của bạn thì authentication đã chạy đúng. + +### Troubleshooting + +**Authentication fails (401):** Kiểm tra `client_id` / `client_secret` trong `~/.greennode/credentials` (chạy `grn configure`), hoặc env var `GRN_CLIENT_ID` / `GRN_CLIENT_SECRET`. Gọi `list_dashboards` để xác nhận lấy được IAM token và vMonitor phản hồi. + +**Sai project / thiếu resource:** Kiểm tra `GRN_PROJECT_ID` và `GRN_PROFILE`. vMonitor là global — không có region nào để kiểm tra lại trên server này. + +**Agent báo tool không khả dụng:** Server đang chạy read-only. Thêm `--allow-write` rồi restart client — write tool không được đăng ký khi thiếu flag nên agent không nhìn thấy chúng. + +**Không kết nối được:** Kiểm tra `--directory` trỏ đúng thư mục gốc repo và `uv sync` đã chạy xong. Xem log của client để tìm lỗi lúc khởi động. diff --git a/Vietnamese/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md b/Vietnamese/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md new file mode 100644 index 00000000..d26e1de7 --- /dev/null +++ b/Vietnamese/vmonitor/vmonitor-mcp-server/configure-remote-mcp.md @@ -0,0 +1,130 @@ +# Configure Remote MCP + +Remote MCP là **vMonitor MCP Server được host qua HTTP** (**streamable-http**): MCP client kết nối chỉ bằng một URL — không cần cài Python/`uv`, không cần clone repo, và không cần `~/.greennode` trên máy client. + +Bạn tự host server (hoặc platform team của bạn host) — hoặc chạy trực tiếp, hoặc đặt sau **AgentBase Gateway**. Khi ở sau gateway, authentication được tập trung hóa: gateway xử lý phần đăng nhập và chuyển tiếp danh tính của caller tới server, nên mọi lời gọi vMonitor đều chạy dưới account, project và quyền của user đã đăng nhập. Nhiều user dùng chung một endpoint mà mỗi người vẫn chỉ thấy resource của chính mình. + +### Host server + +Hai cách, đều từ repo [`greennode-mcp`](https://github.com/GreenNodeHub/greennode-mcp): + +**Cách 1 — chạy bằng uv (HTTP transport):** + +```bash +uv run vmonitor-mcp-server --transport streamable-http --host 0.0.0.0 --port 8080 +``` + +Mặc định bind `127.0.0.1:8000` — đặt `--host 0.0.0.0` (kèm port) khi client kết nối từ máy khác. + +**Cách 2 — Docker:** + +```bash +# Build (từ thư mục gốc repo) +docker build -f src/vmonitor-mcp-server/Dockerfile -t vmonitor-mcp-server . + +# Run (streamable-http trên :8080); truyền credentials qua env hoặc mount ~/.greennode +docker run --rm -p 8080:8080 \ + -e GRN_CLIENT_ID= -e GRN_CLIENT_SECRET= \ + vmonitor-mcp-server +``` + +Lưu ý chung cho cả hai cách: + +* `GET /health` luôn không cần xác thực — dùng để kiểm tra liveness / readiness. +* **Access level đặt lúc server khởi động**: mặc định read-only (**110 tool**); thêm `--allow-write` để đăng ký đủ **213 tool**. Cân nhắc kỹ — các tool đặt hàng quota tiêu tốn tiền. +* HTTP transport có thể khởi động **hoàn toàn không có credentials** khi chạy sau AgentBase Gateway ở chế độ passthrough — khi đó mỗi request đều yêu cầu token của caller. + +### Authentication (HTTP transport) + +Danh tính được resolve **theo từng request**, không cần flag: + +1. Request mang IAM bearer token trong `Authorization` (AgentBase Gateway chuyển tiếp token của caller) → **mọi lời gọi vMonitor chạy dưới danh tính caller đó**. Token user bị từ chối sẽ báo lỗi — không bao giờ tự động retry ngầm dưới service account. +2. Không có token, nhưng host có cấu hình service-account credentials (env var hoặc `~/.greennode`) → dùng service account dùng chung. +3. Không có gì → **401** + `WWW-Authenticate: Bearer`. + +Lưu ý thêm: + +* **stdio (local) luôn yêu cầu service-account credentials**; chỉ HTTP transport mới hỗ trợ chế độ passthrough không credentials. +* Server không tự verify token — các API của vMonitor mới là bên verify. Token hết hạn sẽ hiện lên dưới dạng `500 IAM_VALIDATION_ERROR`, được xem là auth failure và refresh một lần. +* `--auth-debug` (hoặc `GRN_MCP_AUTH_DEBUG=1`) bật diagnostic logging opt-in, đã redact, chỉ dành cho HTTP: log tóm tắt auth của inbound request và expose `GET /whoami` không cần xác thực. Nó không verify signature và không log full token — **không bật trong production**. + +### Remote MCP endpoint + +| Service | Remote MCP Server URL | Service key | +| ---------------------------------------------- | --------------------------------- | ----------- | +| **vMonitor — nền tảng observability GreenNode** | `` | `vmonitor` | + +Thay `` bằng endpoint mà deployment của bạn expose — ví dụ `https://:8080` nếu chạy trực tiếp, hoặc endpoint AgentBase Gateway của bạn (dạng `https://gw-vmonitor-mcp-server-.agentbase-gateway.aiplatform.vngcloud.vn/vmonitor_mcp_server`) khi đặt sau gateway. + +Endpoint này expose cùng bộ tool như local mode — xem vMonitor MCP Tools. Access level (read-only / write) do người deploy cố định. + +### Add to MCP client + +#### Claude Code + +```bash +claude mcp add --transport http vmonitor + +# Verify + đăng nhập +claude mcp list +``` + +Khi endpoint nằm sau AgentBase Gateway, chạy `/mcp` trong Claude Code → chọn `vmonitor` → **Authenticate** để mở luồng đăng nhập trên browser (OAuth 2.1, client tự refresh token). + +#### Claude Desktop / claude.ai + +Settings → **Connectors** → **Add custom connector** → dán endpoint URL. Sau AgentBase Gateway, Claude sẽ mở trang đăng nhập GreenNode ở lần dùng đầu. + +Remote MCP **không** dùng `command` / `args` / environment variable như stdio. + +#### Cursor + +Thêm entry kiểu remote vào `mcp.json` — chỉ cần `url`: + +```json +{ + "mcpServers": { + "vmonitor": { + "url": "" + } + } +} +``` + +Xem [Cursor — Model Context Protocol](https://docs.cursor.com/context/model-context-protocol). + +#### Visual Studio Code + +Thêm entry tương tự vào `.vscode/mcp.json`. Xem [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). + +#### HTTP trực tiếp không qua gateway + +Với deployment không có AgentBase Gateway, các client không tự chạy OAuth flow có thể gửi bearer token tường minh: + +```json +{ + "mcpServers": { + "vmonitor": { + "type": "http", + "url": "", + "headers": { + "Authorization": "Bearer ${GREENNODE_MCP_TOKEN}" + } + } + } +} +``` + +Token là một IAM bearer token — mọi lời gọi khi đó chạy dưới danh tính đó. + +### Troubleshooting + +**401 (unauthenticated):** Caller không mang token hợp lệ và host không có service-account credentials. Sau gateway, chạy lại luồng authenticate của client (`/mcp` → `vmonitor` → Authenticate trong Claude Code); với deployment trực tiếp, kiểm tra header `Authorization: Bearer`. + +**403 `Access denied`:** Token hợp lệ nhưng principal không được cấp quyền trên gateway. Đăng nhập bằng **IAM user** thuộc account được authorize. + +**500 `IAM_VALIDATION_ERROR`:** Token hết hạn — server tự refresh một lần; nếu lỗi vẫn còn thì đăng nhập lại. + +**Agent báo tool không khả dụng:** Access level của endpoint host cố định lúc deploy (read-only / write) — client không thể thêm flag. Nếu cần thao tác write mà endpoint không cho phép, dùng Configure Local MCP. + +**Server có đang chạy không?** `GET /health` trên endpoint — luôn mở, không cần token. diff --git a/Vietnamese/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md b/Vietnamese/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md new file mode 100644 index 00000000..9906f334 --- /dev/null +++ b/Vietnamese/vmonitor/vmonitor-mcp-server/vmonitor-mcp-tools.md @@ -0,0 +1,326 @@ +# vMonitor MCP Tools + +vMonitor MCP Server cung cấp bộ tool để quản lý và tự động hóa **vMonitor Platform** — dịch vụ observability của GreenNode: dashboard & widget, metric query, alarm, infrastructure host, log, notification, quota & usage, và synthetic uptime monitor. Server đứng trước **năm API của vMonitor** (metric/dashboard, Log, notification, quota-usage, synthetic/uptime) sau một lớp xác thực IAM duy nhất — request tự động được route tới đúng API. Mọi thao tác đều expose dưới dạng **tool với input theo parameter** — không dùng resource URI. + +### Tool groups + +| Nhóm | Mục đích | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| Dashboards | List / xem / tạo / clone / cập nhật / xóa dashboard. | +| Widgets, variables & views | Thêm / sửa / di chuyển / resize widget; quản lý variable dùng chung và saved view. | +| Metric query | Time-series và single-value statistic — dữ liệu phía sau mọi chart. | +| Metric catalogue & units | Tên metric, dimension, value, đơn vị và override đơn vị theo từng user. | +| Infrastructure hosts | Host chạy agent và host theo sản phẩm (vServer, vStorage, vDB, vLB, vBackup, vBandwidth, vAS) + metric snapshot của chúng.| +| Alarms | Alarm metric / log / change-detection: tạo / sửa / xóa, lịch sử và trạng thái. | +| Integrations & metric API keys | Cài / gỡ tích hợp metric-source; cấp / thu hồi metric API key. | +| Logs — projects & search | Log project, certificate, field mapping, search và export log. | +| Logs — archives & refills | Đích export (archive) và job nạp lại (refill). | +| Logs — pipelines & processors | Processing pipeline, processor group, processor và library. | +| Logs — resource mappings | Log mapping resource → project (vCDN, vDB, vLB, vStorage, vStorage bucket). | +| Notifications | Channel xác thực qua OTP: Email, SMS, Slack, Webhook, Telegram, Teams. | +| Quota & usage | Đọc usage, catalogue tier / package, báo giá. | +| Quota orders | Mua / resize / xóa quota — **tốn tiền**; mỗi đơn hàng đều có bước báo giá miễn phí. | +| Synthetic | Uptime monitor và probing location. | +| Feature guide | Hướng dẫn từng bước cho mỗi tính năng tổng hợp. | + +### Conventions + +* **Naming `verb_noun`**, mỗi nhóm tính năng một handler. +* **Access** ghi theo từng tool: + * `read` — luôn khả dụng. Read-only mode mặc định đăng ký **110 tool**. + * `write` — cần flag `--allow-write`. Các tool này **không được đăng ký** khi thiếu flag, nên agent không nhìn thấy chúng. + * `destructive` — cũng cần `--allow-write`; tool xóa dữ liệu không thể hoàn tác hoặc tiêu tốn tiền. Client cảnh báo trước khi gọi. +* **Dịch vụ global**: vMonitor không có region — không tool nào nhận parameter `region`, và `GRN_DEFAULT_REGION` bị bỏ qua. +* **Annotations**: mỗi tool khai báo `readOnlyHint` / `destructiveHint` để client auto-approve read và cảnh báo trước destructive call. +* **Structured JSON output** với `outputSchema` + `structuredContent` — client parse trực tiếp. +* **Paging**: các list tool nhận `page` / `size` bắt đầu từ 1 (bỏ `page` để lấy tất cả ở những tool có ghi chú); các endpoint list của Log dùng paging envelope dựa trên `content`. +* **Tốn tiền**: các tool đặt hàng quota (`create_log_project`, `resize_*`) tiêu tốn tiền — luôn gọi `get_creation_price` / `get_resize_price` trước (miễn phí, và validate luôn payload). + +*** + +### Supported Tools + +#### Dashboards + +| Tool | Access | Mô tả | +| --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | +| `list_dashboards` | read | List dashboard; filter `searching_text` / `searching_field` (optional), phân trang `page` / `size` từ 1 (bỏ `page` để lấy tất cả). | +| `get_dashboard` | read | Một dashboard theo ID (kèm số widget). | +| `get_dashboard_by_name` | read | Một dashboard theo đúng tên. | +| `create_dashboard` | write | Tạo dashboard rỗng (chỉ cần `name`). | +| `create_dashboard_clone` | write | Clone một dashboard thành dashboard mới. | +| `update_dashboard` | write | Cập nhật cài đặt chung (dark mode, refresh, time range, selected view). | +| `update_dashboard_name` | write | Đổi tên dashboard. | +| `update_dashboard_favorite` | write | Đánh dấu / bỏ đánh dấu favorite. | +| `delete_dashboard` | destructive | Xóa dashboard (không thể hoàn tác). | + +#### Widgets, variables & views + +| Tool | Access | Mô tả | +| ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | +| `list_dashboard_variables` | read | Các query variable dùng chung của dashboard. | +| `get_dashboard_variable` | read | Một variable. | +| `update_dashboard_variables` | write | Thay danh sách variable của dashboard (thay cả list). | +| `list_dashboard_views` | read | Các preset query / filter / time-range đã lưu. | +| `get_dashboard_view` | read | Một saved view. | +| `create_dashboard_view` | write | Lưu trạng thái dashboard hiện tại thành một view có tên. | +| `update_dashboard_view` | write | Cập nhật trạng thái đã lưu của một view. | +| `delete_dashboard_view` | destructive | Xóa một saved view (không thể hoàn tác). | +| `list_widgets` | read | Widget của dashboard **kèm metric query phía sau từng widget** — replay bằng `get_statistics_v2` mà không cần discovery dimension. | +| `get_widget` | read | Một widget (chart config + graph spec). | +| `create_widget` | write | Thêm widget (v2 `graphs` map; bỏ `layout` để tự đặt trên lưới 10 cột). | +| `update_widget` | write | Sửa nội dung widget (mảng v1 `metricGraphs` / `logGraphs`). | +| `update_widget_v2` | write | Sửa nội dung widget (v2 `graphs` map). | +| `update_widget_layout` | write | Di chuyển / resize widget và chỉnh time window của nó. | +| `delete_widget` | destructive | Xóa widget (không thể hoàn tác). | + +#### Metric query + +| Tool | Access | Mô tả | +| -------------------------- | ------ | ---------------------------------------------------------------------------------- | +| `get_statistics` | read | Dữ liệu time-series (lọc theo dimension, `group_by`, window) — dữ liệu phía sau chart. | +| `get_statistics_synthetic` | read | Một giá trị tổng hợp đơn (chart number / single-stat). | +| `get_statistics_v2` | read | Statistic query có typed (`type` = `SIMPLE` / `CUSTOM` + body `data`) — replay nguyên văn query của widget. | + +#### Metric catalogue & units + +| Tool | Access | Mô tả | +| ------------------------------ | ----------- | ----------------------------------------------------------------------- | +| `get_metric_names` | read | Catalogue metric — điểm khởi đầu khi chọn metric. | +| `list_metric_dimension_names` | read | Mọi dimension key biết được trên các metric. | +| `list_metric_dimension_values` | read | Các value đã quan sát của một dimension (vd: các host của `host`). | +| `get_metric_dimensions` | read | Dimension của một metric + value đã quan sát của từng dimension. | +| `list_metric_units` | read | Các đơn vị có thể gán cho metric. | +| `list_metric_unit_mappings` | read | Mapping metric → đơn vị hiển thị trong info panel. | +| `create_metric_unit_mapping` | write | Override đơn vị hiển thị của một metric cho user hiện tại. | +| `delete_metric_unit_mapping` | destructive | Reset đơn vị hiển thị (gỡ override). | + +#### Infrastructure hosts + +Host chạy agent (server có Metric Agent) và resource sản phẩm được giám sát như host. Nhóm `` mở rộng thành một tool cho từng loại sản phẩm — `vserver`, `vstorage`, `vdb`, `vlb`, `vbackup`, `vbandwidth`, `vas` (vDB Kafka chỉ có tool list). Các tool list host luôn gửi `page` / `size` và nhận thêm filter `name` (optional). + +| Tool | Access | Mô tả | +| ----------------------------------------------- | ----------- | --------------------------------------------------------- | +| `list_hosts` | read | Các infrastructure host chạy agent. | +| `get_host` | read | Một host chạy agent theo ID. | +| `get_host_metrics` | read | Metric snapshot hiện tại của host (status + CPU / load / memory). | +| `update_host_enabled` / `update_host_disabled` | write | Mở lại / tạm dừng giám sát host chạy agent (agent vẫn cài).| +| `delete_host` | destructive | Gỡ host khỏi danh sách Infrastructure (không thể hoàn tác).| +| `list_vserver_hosts` / `list_vstorage_hosts` / `list_vdb_hosts` / `list_vdb_kafka_hosts` / `list_vlb_hosts` / `list_vbackup_hosts` / `list_vbandwidth_hosts` / `list_vas_hosts` | read | List resource sản phẩm được giám sát như host. | +| `get__host_metrics` | read | Metric snapshot của host theo sản phẩm. | +| `update__host` | write | Bật / tắt giám sát host sản phẩm (body `{enabled}`). | +| `delete__host` | destructive | Gỡ host sản phẩm (không thể hoàn tác). | + +#### Alarms + +Alarm metric, synthetic, log và change-detection. Body create / update là DTO phẳng, typed đầy đủ — `name` là field bắt buộc duy nhất. + +| Tool | Access | Mô tả | +| ------------------------------- | ----------- | ------------------------------------------------------------------------- | +| `list_alarms` | read | List alarm (lọc theo name / severity / status / type). | +| `get_alarm` | read | Một alarm theo ID (kèm config theo loại). | +| `get_metric_alarm_definition` | read | Định nghĩa evaluator phía trên của metric alarm. | +| `list_metric_alarm_histories` | read | Lịch sử metric alarm (id = `alarms[].id` của sub-alarm trong definition). | +| `get_synthetic_alarm_definition`| read | Định nghĩa metric alarm dạng synthetic. | +| `list_synthetic_alarm_histories`| read | Lịch sử synthetic alarm (id = sub-alarm trong definition). | +| `list_log_alarm_histories` | read | Lịch sử log alarm. | +| `get_log_alarm_status` | read | Trạng thái hiện tại của log alarm. | +| `get_change_alarm` | read | Định nghĩa alarm change-detection (cần time window). | +| `list_change_alarm_histories` | read | Lịch sử change alarm (cần time window). | +| `create_metric_alarm` / `update_metric_alarm` | write | Tạo / sửa metric alarm (severity / condition không phân biệt hoa-thường). | +| `delete_metric_alarm` | destructive | Xóa metric alarm (không thể hoàn tác). | +| `delete_metric_sub_alarm` | destructive | Xóa sub-alarm của metric alarm tổng hợp. | +| `create_log_alarm` / `update_log_alarm` | write | Tạo / sửa log alarm. | +| `delete_log_alarm` | destructive | Xóa log alarm (không thể hoàn tác). | +| `create_change_alarm` / `update_change_alarm` | write | Tạo / sửa alarm change-detection. | +| `delete_change_alarm` | destructive | Xóa change alarm (không thể hoàn tác). | +| `delete_change_alarm_history` | destructive | Xóa lịch sử change alarm (không thể hoàn tác). | + +#### Integrations & metric API keys + +| Tool | Access | Mô tả | +| ---------------------------- | ----------- | ----------------------------------------------- | +| `list_integrations` | read | Các app metric-source cài được. | +| `get_integration` | read | Một integration. | +| `update_integration_installed` / `update_integration_uninstalled` | write | Cài / gỡ một integration. | +| `delete_integration` | destructive | Xóa integration (không thể hoàn tác). | +| `list_metric_api_keys` | read | List metric API key. | +| `create_metric_api_key` | write | Cấp metric API key mới. | +| `delete_metric_api_key` | destructive | Thu hồi metric API key (không thể hoàn tác). | + +#### Logs — projects, search & export + +`search_logs` / `search_logs_default` nhận DSL có cấu trúc `{type,value}` (match / range / exists / bool; các cách viết tắt kiểu Elasticsearch được chuyển đổi). + +| Tool | Access | Mô tả | +| ---------------------------------- | ----------- | ------------------------------------------------------------------------------- | +| `list_projects` | read | Log project (Log API). | +| `get_project` | read | Một log project. | +| `get_project_mappings` | read | Field mapping của project. | +| `get_project_log_data_exists` | read | Project có dữ liệu log đã ingest hay không. | +| `search_logs` / `search_logs_default` | read | Query dữ liệu project bằng DSL có cấu trúc. | +| `get_log_export` | read | Theo dõi một log export. | +| `get_project_certificate_download` | read | Tải certificate của project (ZIP base64; `cert_id` từ `list_projects` → `certInfos[]`). | +| `update_project` / `update_project_mappings` | write | Sửa cài đặt / field mapping của project. | +| `create_project_certificate` | write | Cấp client certificate cho project. | +| `delete_project_certificate` | destructive | Thu hồi client certificate của project. | +| `create_log_export` | write | Chuẩn bị log export bất đồng bộ. | + +#### Logs — archives & refills + +| Tool | Access | Mô tả | +| ------------------------------ | ----------- | --------------------------------------------- | +| `list_archives` / `get_archive`| read | Log archive (đích export). | +| `validate_archive_connection` | read | Kiểm tra kết nối storage của archive. | +| `create_archive` / `update_archive` | write | Tạo / sửa log archive. | +| `delete_archive` | destructive | Xóa log archive. | +| `list_refills` / `get_refill` | read | Job refill log (nạp lại). | +| `validate_refill_connection` | read | Kiểm tra kết nối storage của refill. | +| `create_refill` / `create_refill_from_archive` | write | Tạo job refill. | +| `delete_refill` | destructive | Xóa job refill. | + +#### Logs — pipelines & processors + +| Tool | Access | Mô tả | +| --------------------------------------- | ----------- | ------------------------------------------------------ | +| `list_pipelines` / `get_pipeline` | read | Processing pipeline của log. | +| `create_pipeline` / `update_pipeline` | write | Tạo / sửa pipeline. | +| `delete_pipeline` | destructive | Xóa pipeline. | +| `get_processor_group` | read | Một processor group. | +| `list_processor_group_libraries` | read | Processor group library. | +| `list_date_formats` | read | Danh sách date format hỗ trợ. | +| `validate_grok_parser` | read | Validate grok parser. | +| `create_processor_group` / `update_processor_group` / `update_processor_order` / `create_processor_group_library` | write | Quản lý processor group và thứ tự. | +| `delete_processor_group` | destructive | Xóa processor group. | +| `create_processor` / `update_processor` | write | Quản lý processor. | +| `delete_processor` | destructive | Xóa processor. | + +#### Logs — resource mappings + +Placeholder `` mở rộng thành `vcdn`, `vdb`, `vlb`, `vstorage` (kèm tool riêng cho vStorage bucket). + +| Tool | Access | Mô tả | +| --------------------------------------------------------------------- | ------ | ------------------------------------------------- | +| `list__log_mappings` (+ `list_vstorage_bucket_log_mappings`) | read | Log mapping resource → project. | +| `list_vcdn_log_mapping_types` / `list_vstorage_log_mapping_regions` | read | Tra cứu loại mapping / region. | +| `update__log_mapping[_enabled\|_disabled]` | write | Sửa / bật / tắt log mapping của resource. | +| `update_vstorage_bucket_log_mapping` | write | Gán log mapping cho vStorage bucket. | + +#### Notifications + +Việc tạo channel cần xác thực OTP: `create_notification_otp` → `validate_notification_otp` → `create_notification`. Channel gồm Email, SMS, Slack, Webhook, Telegram, Teams. + +| Tool | Access | Mô tả | +| ---------------------------- | ----------- | -------------------------------------------------- | +| `list_notification_types` | read | Các loại channel. | +| `list_notifications` | read | Các notification channel. | +| `get_notification_otp_info` | read | Thông tin OTP đang chờ. | +| `create_notification_otp` | write | Gửi OTP tới địa chỉ channel. | +| `validate_notification_otp` | write | Xác thực OTP. | +| `create_notification` / `update_notification` | write | Tạo / sửa channel (đã xác thực OTP). | +| `delete_notification` | destructive | Xóa notification channel (không thể hoàn tác). | + +#### Quota & usage (đọc — miễn phí) + +| Tool | Access | Mô tả | +| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------- | +| `get_quota_usage` / `get_log_usage` / `get_composite_usage` | read | Usage theo category / theo log project / gộp chung. | +| `get_current_quota` / `list_log_quotas` / `get_log_quota` / `get_quota_detail` | read | Quota đang hiệu lực và chi tiết. | +| `get_billing_settings` / `list_trash_quotas` / `get_convert_result` | read | Billing settings / quota trong thùng rác / kết quả chuyển đổi. | +| `list_tiers` / `get_tier` / `get_tier_description` | read | Catalogue quota tier (metric / synthetic / log). | +| `list_packages` / `get_package` / `get_package_detail` / `get_package_description` / `get_package_description_detail` | read | Catalogue package có thể mua. | +| `list_quota_classes` / `list_quota_class_packages` | read | Quota class v2 và package của chúng. | +| `get_creation_price` / `get_resize_price` / `get_recovery_price` / `get_renewal_price` | read | Báo giá (chưa đặt hàng). | + +#### Quota orders (tốn tiền; chỉ với `--allow-write`) + +Mỗi đơn hàng đều có pre-flight miễn phí qua `get_creation_price` / `get_resize_price`. + +| Tool | Access | Mô tả | +| ----------------------- | ----------- | ------------------------------------------------------------------------------------------ | +| `create_log_project` | write | Mua log project mới — đơn hàng log quota tạo project (**tốn tiền**). | +| `resize_log_project` | destructive | Tăng quota / nâng Basic → Pro (**tốn tiền**, không thể hoàn tác). | +| `delete_log_project` | destructive | Xóa project, quota và toàn bộ log đã lưu (không thể hoàn tác). | +| `resize_metric_quota` | destructive | Resize metric quota duy nhất của account (**tốn tiền**, không thể hoàn tác). | +| `resize_sms_quota` / `resize_email_quota` | destructive | Đổi quota notification SMS / email sang package khác (**tốn tiền**, không thể hoàn tác). | + +Renew và recover-from-trash hiện chỉ dừng ở báo giá. Kết quả đơn hàng gồm `order_id`, `amount` và `payment_url` — `payment_url` khác rỗng nghĩa là **đang chờ** (quota chỉ thay đổi sau khi user thanh toán qua link đó); `pay: true` trừ tiền trực tiếp từ account. + +#### Synthetic (uptime monitor & location) + +| Tool | Access | Mô tả | +| ---------------------------------------------------- | ----------- | --------------------------------------------------- | +| `list_uptimes` / `get_uptime` / `get_uptime_config` / `validate_uptime` | read | Uptime monitor + preview probe. | +| `create_uptime` / `update_uptime` / `update_uptime_status` | write | Tạo / sửa / bật-tắt monitor. | +| `delete_uptime` | destructive | Xóa monitor (không thể hoàn tác). | +| `list_locations` / `get_location` | read | Các probing location của synthetic. | +| `create_location` / `update_location` | write | Tạo / sửa private probing location. | +| `delete_location` | destructive | Xóa probing location (không thể hoàn tác). | + +#### Feature guide + +| Tool | Access | Mô tả | +| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `get_feature_guide` | read | Hướng dẫn từng bước cho một tính năng tổng hợp: `build_dashboard`, `query_metrics`, `create_metric_alarm`, `monitor_infrastructure`, `edit_metric_unit`, `manage_log_projects`, `manage_integrations`, `create_notification_channel`, `view_quota_usage`, `create_uptime_monitor`. | + +*** + +### Prompts (11) + +Server kèm **11 prompt** (tiếng Việt) — hướng dẫn tính năng từng bước, luôn khả dụng (không cần `--allow-write`). Load từ danh sách prompt của client (vd: prompt picker trong Claude Code), hoặc để agent gọi tool `get_feature_guide` với cùng feature key. + +| Prompt | Mục đích | +| -------------------------------------- | ------------------------------------------------------------------------------------------ | +| `vmonitor_getting_started` | Onboarding: khái niệm, thiết lập auth, mô hình không region, routing tool, sơ đồ tính năng.| +| `vmonitor_build_dashboard` | Dashboard + variable + view + widget (kèm cấu trúc `graphs` / auto-layout). | +| `vmonitor_query_metrics` | Query metric / vẽ dữ liệu, search & export log (kèm log search DSL). | +| `vmonitor_create_metric_alarm` | Tạo alarm (metric / log / change-detection): nguồn → ngưỡng → notification → cổng xác nhận.| +| `vmonitor_monitor_infrastructure` | Khám phá infrastructure host và metric của chúng. | +| `vmonitor_edit_metric_unit` | Override đơn vị hiển thị của metric. | +| `vmonitor_manage_log_projects` | Quản lý log project, mapping, certificate. | +| `vmonitor_manage_integrations` | Cài / gỡ tích hợp metric-source. | +| `vmonitor_create_notification_channel` | Tạo notification channel có xác thực OTP. | +| `vmonitor_view_quota_usage` | Đọc quota usage và giá, rồi mua / resize / xóa quota. | +| `vmonitor_create_uptime_monitor` | Tạo synthetic uptime monitor + probing location. | + +### Key workflows + +#### Đọc metric của một resource từ default dashboard + +Mọi resource GreenNode đều có một **system dashboard** tự sinh, và mỗi widget lưu nguyên văn query mà console đang vẽ (tên metric, statistic, grouping, chuỗi `dimensions` đầy đủ mang `resource_id`). Vì vậy hỏi "server này đang thế nào?" không cần đi hết metric catalogue: + +``` +list_dashboards searching_text="" → dashboard id +list_widgets dashboard_id= → metric_queries của từng widget +get_statistics_v2 body={"type":"SIMPLE","data":{"graph":{ + "name": , "statistics": , + "dimensions": , # dùng nguyên văn + "group_by": , "offset":0, "limit":"", "rollup":"", "rate":0}, + "start_time":, "end_time":, + "period":, "alarm":false}} +``` + +Dùng lại `period` của widget sẽ khớp đúng chart trên web. Widget có `log_graph_count > 0` đang vẽ dữ liệu log — query những widget đó bằng `search_logs`. + +#### Mua hoặc resize quota (tốn tiền, `--allow-write`) + +`packageId` nằm trong các retention entry của quota class, kèm các giới hạn mà `quantity` phải tuân theo. Lệnh báo giá vừa tính giá vừa validate payload: + +``` +list_quota_classes category=log → class → config.retentions[]: + { amount: 7, minSize: 20, maxSize: 5000, + step: 10, packageId: "" } +quantity = * # log quota: GB-days +get_creation_price category=log package_id= quantity= # chi phí 0 +create_log_project body={"projectName":"my-logs", + "packageId":"", "quantity":} +``` + +Đừng đụng vào `redirectUrl` — mỗi tool đặt hàng tự điền trang quota của console vMonitor. Resize theo cùng cấu trúc (`get_resize_price` → `resize_log_project`; `resize_metric_quota` dùng số host và `minResource` / `maxResource` / `step`). SMS / email là bundle cố định từ `list_packages category=sms|email` — không có `quantity`. + +### Usage notes + +* **Input theo parameter, không dùng resource URI.** Mọi thao tác là một tool. +* **Read-only mặc định** (110 tool). Thao tác write cần `--allow-write` — xem Configure Local MCP. Với endpoint host sẵn, access level do người deploy cố định. +* **Báo giá trước khi đặt hàng, xem kỹ trước khi xóa.** Đơn hàng quota luôn có bước báo giá miễn phí; trước các lần xóa không thể hoàn tác, hãy đọc tool detail / history của resource trước. +* **Mọi infrastructure host đều có default dashboard tự sinh, read-only** — con đường nhanh nhất tới metric của một resource.