dagucloud · yohamta0 · Aug 4, 2026 · Aug 4, 2026 · Aug 4, 2026
diff --git 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
@@ -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
@@ -2,17 +2,17 @@
 
 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
 
 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
@@ -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
@@ -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:
 }
 ```
 
+Preview a document create or update:
+
+```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.