From a72ea37aec777de32290fc02b142e99f66aad3eb Mon Sep 17 00:00:00 2001 From: Yota Hamada Date: Tue, 4 Aug 2026 22:06:55 +0900 Subject: [PATCH 1/2] docs: document MCP support for documents --- mcp/architecture.md | 11 ++++--- mcp/auditability.md | 6 ++-- mcp/index.md | 10 +++--- mcp/resources.md | 15 ++++++++- mcp/tools.md | 76 ++++++++++++++++++++++++++++++++++++++++----- 5 files changed, 98 insertions(+), 20 deletions(-) diff --git a/mcp/architecture.md b/mcp/architecture.md index 4d6576c..aad1cba 100644 --- a/mcp/architecture.md +++ b/mcp/architecture.md @@ -8,7 +8,7 @@ flowchart LR route --> auth["Auth middleware"] auth --> mcp["MCP server"] mcp --> api["Dagu API service"] - api --> stores["DAG, run, queue, and log stores"] + api --> stores["DAG, document, run, queue, and log stores"] api --> runtime["Runtime and scheduler operations"] auth --> audit["Audit context"] mcp --> audit @@ -29,8 +29,8 @@ The route honors the server base path. With `base_path: /dagu`, the route is `/d Dagu exposes a small tool surface by design: -- `dagu_read` reads state and reference resources. -- `dagu_change` validates and optionally writes DAG YAML. +- `dagu_read` reads state, Markdown documents, and reference resources. +- `dagu_change` validates and optionally writes DAG YAML or workspace-aware document changes. - `dagu_execute` starts, enqueues, retries, or stops DAG runs. This keeps client instructions stable and avoids exposing every REST endpoint as a separate MCP tool. @@ -44,11 +44,14 @@ The MCP server exposes resource templates for current Dagu state: | Resource | Backing operation | |----------|-------------------| | `dagu://dags/{name}/spec` | Current DAG YAML from the DAG spec API | +| `dagu://docs` | Document tree from the Documents API across accessible workspaces | +| `dagu://docs/{workspace}` | Document tree for one workspace | +| `dagu://docs/{workspace}/{path}` | Markdown content for one document | | `dagu://runs/{name}/{dagRunId}` | DAG-run details from the run details API | | `dagu://runs/{name}/{dagRunId}/logs` | DAG-run logs from the logs API | | `dagu://reference/{topic}` | Built-in MCP guidance bundled with the server | -Run resources can be subscribed to. Dagu watches subscribed run resources and sends a resource update notification when a run reaches a terminal state. +Run resources can be subscribed to. Dagu watches subscribed run resources and sends a resource update notification when a run reaches a terminal state. Document resources are read on demand; successful document mutations continue to notify the Web UI through the existing Documents API notifier. ## Audit Context diff --git a/mcp/auditability.md b/mcp/auditability.md index 5532f1a..c8c9fba 100644 --- a/mcp/auditability.md +++ b/mcp/auditability.md @@ -12,8 +12,8 @@ MCP audit entries use the `mcp` category and include MCP-specific fields when av | `surface` | Accepted credential surface. MCP API-key requests use `mcp`. | | `result` | Outcome such as `received`, `started`, `succeeded`, `failed`, or `denied`. | | `correlation_id` | Shared ID that connects MCP attempt events with downstream domain events. | -| `resource_type` | Affected resource class such as `dag`, `run`, `run_logs`, `dag_run_step_log`, or `mcp_request`. | -| `resource_id` | Affected resource identifier, such as a DAG name, `dagName/dagRunId`, or `dagName/dagRunId/stepName`. | +| `resource_type` | Affected resource class such as `dag`, `doc`, `run`, `run_logs`, `dag_run_step_log`, or `mcp_request`. | +| `resource_id` | Affected resource identifier, such as a DAG name, document path, `dagName/dagRunId`, or `dagName/dagRunId/stepName`. | | `workspace` | Canonical workspace used for audit filtering. | | `credential_id` | Accepted credential identifier, independent of the user or service-account subject. | | `credential_type` | Credential class such as `api_key`, `session`, `basic`, or `none`. | @@ -45,7 +45,7 @@ Authentication and subscription behavior is also auditable: ## Correlating With DAG Events -MCP tools call the same internal API service used by the Web UI and REST API. When `dagu_change` applies a DAG update or `dagu_execute` starts, enqueues, retries, or stops a run, the downstream DAG audit event keeps the MCP source context. +MCP tools call the same internal API service used by the Web UI and REST API. When `dagu_change` applies a DAG or document update, or `dagu_execute` starts, enqueues, retries, or stops a run, the downstream domain audit event keeps the MCP source context. Document mutations therefore produce both the MCP tool lifecycle events and the normal `doc_create`, `doc_update`, `doc_rename`, or `doc_delete` event without recording Markdown content. Filter audit logs by: diff --git a/mcp/index.md b/mcp/index.md index 02ceeca..4dfc082 100644 --- a/mcp/index.md +++ b/mcp/index.md @@ -2,7 +2,7 @@ Dagu includes a built-in Model Context Protocol (MCP) server. There is no separate Dagu MCP package to install: run the Dagu HTTP server and point an MCP client at the `/mcp` endpoint. -Use MCP when an AI tool should operate a running Dagu server: inspect workflows, read run state, preview workflow edits, apply DAG changes, or control DAG runs through the same authenticated server boundary as the REST API. +Use MCP when an AI tool should operate a running Dagu server: inspect workflows, maintain Markdown documents, read run state, preview changes, apply DAG or document edits, or control DAG runs through the same authenticated server boundary as the REST API. ## What Dagu Exposes @@ -10,9 +10,9 @@ The MCP server is intentionally compact: | Surface | Purpose | |---------|---------| -| Tools | `dagu_read`, `dagu_change`, and `dagu_execute` cover reading state, editing DAG YAML, and controlling runs. | -| Resources | `dagu://...` resources expose DAG specs, run details, run logs, and built-in MCP references. | -| Prompts | Built-in prompts guide common authoring, editing, and failed-run debugging workflows. | +| Tools | `dagu_read`, `dagu_change`, and `dagu_execute` cover reading state, maintaining documents and DAG YAML, and controlling runs. | +| Resources | `dagu://...` resources expose DAG specs, Markdown documents, run details, run logs, and built-in MCP references. | +| Prompts | Built-in prompts guide DAG and document authoring, editing, and failed-run debugging workflows. | | Audit events | MCP requests, tool calls, subscriptions, and downstream DAG actions are audit-attributed to the accepted credential. | The server uses Streamable HTTP. The default local URL is: @@ -42,6 +42,6 @@ The Dagu skill and the Dagu MCP server solve related but different problems. | Integration | Configure | Best for | |-------------|-----------|----------| | Dagu skill | `gh skill install dagucloud/dagu dagu` | Teaching AI coding tools how to write valid Dagu workflow YAML. | -| Dagu MCP server | `http://localhost:8080/mcp` | Letting MCP clients read Dagu state, validate or apply DAG edits, and control runs. | +| Dagu MCP server | `http://localhost:8080/mcp` | Letting MCP clients read Dagu state and documents, apply scoped edits, and control runs. | Most AI-assisted workflow authoring setups benefit from both: install the skill for authoring guidance, then connect MCP when the tool should operate a running Dagu server. diff --git a/mcp/resources.md b/mcp/resources.md index 946fa57..958ca1a 100644 --- a/mcp/resources.md +++ b/mcp/resources.md @@ -1,6 +1,6 @@ # MCP Resources -Dagu exposes MCP resources for DAG specs, DAG-run details, scheduler and step logs, and built-in references. +Dagu exposes MCP resources for DAG specs, Markdown documents, DAG-run details, scheduler and step logs, and built-in references. ## Resource URIs @@ -10,6 +10,9 @@ Dagu exposes MCP resources for DAG specs, DAG-run details, scheduler and step lo | `dagu://reference/tools` | `text/markdown` | Compact tool reference for `dagu_read`, `dagu_change`, and `dagu_execute`. | | `dagu://reference/notifications` | `text/markdown` | How run-completion notifications work over MCP resources. | | `dagu://dags/{name}/spec` | `application/yaml` | Current YAML spec for a DAG. | +| `dagu://docs` | `application/json` | Document tree across accessible workspaces. | +| `dagu://docs/{workspace}` | `application/json` | Document tree for `default` or one named workspace. | +| `dagu://docs/{workspace}/{path}` | `text/markdown` | Current Markdown content for one document. | | `dagu://runs/{name}/{dagRunId}` | `application/json` | Current DAG-run details. | | `dagu://runs/{name}/{dagRunId}/logs` | `application/json` | Scheduler log and step log metadata. | | `dagu://runs/{name}/{dagRunId}/steps/{stepName}/logs` | `application/json` | Standard output and standard error for one step. | @@ -24,6 +27,14 @@ Use `dagu_read` with a `uri` to read any resource directly: { "uri": "dagu://dags/nightly-report/spec" } ``` +Document resources use an explicit workspace so an identical path in two workspaces is unambiguous. Encode a nested document path as one URI segment: + +```text +dagu://docs/operations/runbooks%2Frestart +``` + +The `dagu_read` list and search targets return these canonical URIs. `dagu://docs` and workspace collection resources accept the same `page`, `perPage`, `flat`, `sort`, and `order` query parameters as `target=docs`. + Log resources accept query parameters supported by Dagu's log readers, such as `tail=100`: ```text @@ -62,4 +73,6 @@ Dagu also exposes MCP prompts for common workflows: |--------|-----------|---------| | `dagu_create_dag` | `goal` | Draft, validate, and apply a new DAG using Dagu's compact MCP tool surface. | | `dagu_edit_dag` | `name`, `change` | Read an existing DAG spec, make a scoped edit, preview validation, then apply. | +| `dagu_create_doc` | `workspace`, `path`, `goal` | Draft, preview, and create a Markdown document. | +| `dagu_edit_doc` | `workspace`, `path`, `change` | Read a Markdown document, make a scoped edit, preview, then apply. | | `dagu_debug_failed_run` | `name`, `dagRunId` | Read a run and logs, explain the likely failure, then offer retry or stop when appropriate. | diff --git a/mcp/tools.md b/mcp/tools.md index 1626ad1..b823492 100644 --- a/mcp/tools.md +++ b/mcp/tools.md @@ -4,8 +4,8 @@ Dagu intentionally exposes three MCP tools. | Tool | Purpose | |------|---------| -| `dagu_read` | Read DAG specs, DAG details, DAG-run details, logs, list views, and Dagu MCP reference resources. | -| `dagu_change` | Validate and optionally apply a DAG YAML upsert. | +| `dagu_read` | Read DAGs, Markdown documents, DAG runs, logs, list views, and Dagu MCP reference resources. | +| `dagu_change` | Preview or apply DAG YAML and workspace-aware document changes. | | `dagu_execute` | Start, enqueue, retry, or stop DAG runs. | ## `dagu_read` @@ -14,11 +14,14 @@ Use `dagu_read` for current Dagu state. | Input | Values | |-------|--------| -| `target` | `dags`, `dag`, `dag_spec`, `runs`, `run`, `run_logs`, `step_log`, or `reference` | +| `target` | `dags`, `dag`, `dag_spec`, `docs`, `doc`, `doc_search`, `runs`, `run`, `run_logs`, `step_log`, or `reference` | | `name` | DAG name for DAG and run targets | | `dagRunId` | DAG-run ID for run and log targets | | `stepName` | Step name for the `step_log` target | | `query` | URL query string for list and log targets, such as `page=1&perPage=100` or `tail=100` | +| `workspace` | `all`, `default`, or a workspace name for document targets. Required for `doc`; optional for `docs` and `doc_search`. | +| `path` | Document path without `.md`; required for `doc` | +| `search` | Search text; required for `doc_search` | | `uri` | Direct resource URI, such as `dagu://reference/authoring` | Examples: @@ -31,6 +34,26 @@ Examples: { "target": "dag_spec", "name": "nightly-report" } ``` +List documents in one workspace: + +```json +{ + "target": "docs", + "workspace": "operations", + "query": "flat=true&perPage=100" +} +``` + +Read or search Markdown documents: + +```json +{ "target": "doc", "workspace": "operations", "path": "runbooks/restart" } +``` + +```json +{ "target": "doc_search", "workspace": "all", "search": "database failover" } +``` + ```json { "uri": "dagu://runs/nightly-report/latest/logs?tail=100" } ``` @@ -48,14 +71,18 @@ Read stdout and stderr for one step: ## `dagu_change` -Use `dagu_change` for DAG YAML edits. The only current change type is `upsert_dag`. +Use `dagu_change` for DAG YAML and Markdown document changes. Preview does not write; apply uses the same workspace authorization, path validation, Git Sync write policy, mutation notifications, and audit path as the REST API. | Input | Values | |-------|--------| | `mode` | `preview` or `apply`; defaults to `preview` | -| `type` | `upsert_dag`; defaults to `upsert_dag` | -| `name` | DAG name to create or update | -| `spec` | Full DAG YAML specification | +| `type` | `upsert_dag`, `upsert_doc`, `rename_doc`, or `delete_doc`; defaults to `upsert_dag` | +| `name` | DAG name for `upsert_dag` | +| `spec` | Full DAG YAML specification for `upsert_dag` | +| `workspace` | `default` or a named workspace for document changes; `all` is not allowed | +| `path` | Document or directory path without `.md` for document changes | +| `content` | Full Markdown content for `upsert_doc`; empty content is allowed | +| `newPath` | Destination document or directory path for `rename_doc` | Preview validates the spec without writing it: @@ -79,6 +106,41 @@ Apply writes only after validation succeeds: } ``` +Create or update a document: + +```json +{ + "mode": "preview", + "type": "upsert_doc", + "workspace": "operations", + "path": "runbooks/restart", + "content": "# Restart procedure\n\n..." +} +``` + +Rename or move a document or directory: + +```json +{ + "mode": "apply", + "type": "rename_doc", + "workspace": "operations", + "path": "runbooks", + "newPath": "procedures" +} +``` + +Delete a document or directory: + +```json +{ + "mode": "preview", + "type": "delete_doc", + "workspace": "operations", + "path": "procedures/obsolete" +} +``` + ## `dagu_execute` Use `dagu_execute` for run control. From b9e683e6ef847b4cd83dac6d52ad7738f5cf5e22 Mon Sep 17 00:00:00 2001 From: Yota Hamada Date: Tue, 4 Aug 2026 22:25:23 +0900 Subject: [PATCH 2/2] docs: clarify MCP document preview example --- mcp/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/tools.md b/mcp/tools.md index b823492..06d0609 100644 --- a/mcp/tools.md +++ b/mcp/tools.md @@ -106,7 +106,7 @@ Apply writes only after validation succeeds: } ``` -Create or update a document: +Preview a document create or update: ```json {