---
name: dify-tool-mcp
description: 发现已配置的 Dify 能力，把用户请求匹配到正确的 Dify 应用，只收集其必需输入并通过 dify-tool-mcp 执行。当用户要求执行、自动化、运行、生成、分析、回答、转换或处理可能由多个已配置的 Dify workflow、chat app 或 completion app 处理的任务时使用。
---

# Dify 任务路由器

把 Dify Tool MCP 当作任务路由器使用，而不是一份安装指南。已配置的应用是不断变化的能力目录：先发现目录，再按功能匹配，最后执行最合适的任务。

## 安装本 Skill（引导）

如果你是从 npm 包路径（`dify_get_skill` 返回的 `skill_dir`）读到本 Skill，而不是从宿主平台的 skill 目录读到，请先安装再使用：

1. 为所在平台的 Skill/Instructions 机制选择目标目录，优先用户级，便于跨项目使用：
   - CodeBuddy（用户级）：`~/.codebuddy/skills/dify-tool-mcp/`
   - CodeBuddy（项目级）：`<MCP 工作目录>/.codebuddy/skills/dify-tool-mcp/`
   - Claude Code：`~/.claude/skills/dify-tool-mcp/`
   - 其他平台：遵循该平台的 skill/instruction 目录约定。
2. 把整个 skill 目录（`SKILL.md` 和 `agents/`）复制到目标位置，或用 `dify_get_skill` 返回的 `contents` 重建这些文件。
3. 向用户确认安装路径。

## 连接 MCP Server

在 MCP 客户端中使用下面的标准 stdio 配置。客户端决定配置文件位置，顶层字段名可能不同（常见为 `mcpServers`）：

```json
{
  "mcpServers": {
    "dify-tool-mcp": {
      "command": "npx",
      "args": ["-y", "dify-tool-mcp"],
      "env": {
        "DIFY_MCP_CONFIG_PATH": "/absolute/path/to/dify-mcp-config.json",
        "DIFY_BASE_URL": "https://dify.example.com"
      }
    }
  }
}
```

全局安装后可直接用 `dify-mcp` 作为 `command`。不要把 Dify API Key 放进 MCP 客户端配置。本指南可通过任意 Agent 平台的 Skill 或 Instructions 机制安装，其路由规则也可直接作为 Agent 指令使用。

## 用 API Key 配置应用

当用户明确要求添加、连接或配置 Dify 应用并提供 Service API Key 时，先调用 `dify_configure_app`，再进行任何任务调用。私有部署已知时提供 `base_url`，否则沿用已配置的 base URL。用户的说明能体现意图时，补充简洁的 `function_description`，有助于后续任务匹配。

该工具会先读取 Dify 应用元数据与参数来验证 Key，验证通过后才写入 `config.json`。不要在回复、工具摘要或建议的配置片段中重复 API Key。说明 `enabled: true` 需要重启 MCP 才会注册独立工具；通用 `dify_invoke` 立即可用。

## 任务路由协议

1. 在会话中第一次执行 Dify 任务前、配置变更后、或所需能力不明确时，先调用 `dify_list_configured_apps`。
2. 阅读每个应用的 `name`、`function_description`、`mode` 和 `inputs`，把 `function_description` 视为该应用能力的首要描述。
3. 把用户想要的结果匹配到最具体的应用描述，并确认会话中能提供其所需输入。
4. 若恰好一个应用匹配且输入齐全，立即用 `dify_invoke` 执行。
5. 若多个应用匹配，简要说明关键区别并询问用户想要哪个结果。若无应用匹配，说明没有已配置的 Dify 能力符合，不要随意调用某个应用。
6. 不要暴露原始 API Key、完整配置文件或授权头。

当用户询问 Dify 工具能做什么时，基于 `function_description` 把已配置应用作为面向用户的能力列出，然后邀请用户选择任务。

## 执行选中的任务

用选中应用的 `app_id`、`name` 或 `tool_name` 作为 `ref` 调用 `dify_invoke`：

- 只传该应用期望的变量到 `inputs`。
- `workflow`：把用户提供的数据映射到其命名变量。
- `advanced-chat`、`chat`、`completion`：把用户请求放入 `inputs.query`；仅在延续对话时传 `conversation_id`。
- 默认 `response_mode: "streaming"`；仅当调用方明确需要单个最终响应时才用 `blocking`。
- 把有用的任务结果返回给用户，不要返回原始配置或不必要的流式事件噪音。

任务调用示例：

```json
{
  "ref": "resume-review",
  "inputs": {
    "resume_text": "...",
    "target_role": "产品经理"
  },
  "response_mode": "streaming"
}
```

## 输入与容错

把列出的 `inputs` 作为当前契约。必需值缺失时，调用前先问一个聚焦的问题。

若 Dify 返回参数校验错误，读取返回中刷新的 `inputs`，更新输入映射，并询问任何新增的必需值；确认输入后再重试。不要自动重试非参数类的工作流失败。

`dify_config_status` 仅用于诊断加载或参数刷新问题，正常任务选择不需要它。

## 知识库（Datasets）任务

知识库操作使用独立的 Datasets API Key（`DIFY_DATASET_API_KEY`），不是按应用的 Service API Key。

- `dify_dataset_maintain`：维护知识库的统一入口，按参数自动判断动作——仅 `name` 创建新库并登记；`dataset_id` + `text`/`file_path` 新增文档；带 `document_id` 时更新文档；仅 `dataset_id` 时验证并登记。文件上传使用服务器本地 `file_path`，工具内部以 multipart 上传。
- `dify_dataset_retrieve`：检索知识库。传 `dataset_id` 或已登记的 `name`；用户按名称提到知识库（如"财务制度库"）时，先从登记的 `datasets` 列表解析，找不到再调用 `dify_dataset_maintain` 传入其 `dataset_id` 完成登记。支持两层 LLM Wiki 检索：`layer` 默认 `wiki`（优先查配对的组织视图库），`raw` 查原始文档库，`both` 先 wiki 再 raw。
- LLM Wiki 编译：`dify_wiki_build` 把原始文件编译为上层组织视图页面并上传，`dify_wiki_compile_one` 单文件编译/重摄取，`dify_wiki_lint` 审计命名、孤儿与缺失；编译器提示词按数据集 `compiler_prompt` 自动选用。
- 列出/状态/删除数据集操作是内部能力，不作为独立工具暴露。

## 安装与安全

运行 `dify-mcp --version` 或调用 `dify_get_skill` 定位随包指南，并安装到宿主平台的 Skill 或 Instructions 机制；不需要特定于 Codex 的位置。

保持 `config.json` 在版本库之外。优先使用明确的 HTTPS Dify `base_url`；使用非本地 HTTP 端点前先与用户确认。