diff --git a/examples/dify/dify_demo.md b/examples/dify/dify_demo.md index 0c023be..e843a6b 100644 --- a/examples/dify/dify_demo.md +++ b/examples/dify/dify_demo.md @@ -24,114 +24,86 @@ This document demonstrates how to integrate and use `doris-mcp-server` in Dify t ## Table of Contents -- [Prerequisites](#prerequisites) -- [Installation & Configuration](#installation--configuration) -- [Starting the MCP Server](#starting-the-mcp-server) -- [Ngrok Tunnel (Optional)](#ngrok-tunnel-optional) -- [Installing & Configuring the Plugin in Dify](#installing--configuring-the-plugin-in-dify) -- [Creating a Dify App](#creating-a-dify-app) -- [Adding MCP Tools](#adding-mcp-tools) -- [Example Calls](#example-calls) + - [Prerequisites](https://www.google.com/search?q=%23prerequisites) + - [Installation & Configuration](https://www.google.com/search?q=%23installation--configuration) + - [Starting the MCP Server](https://www.google.com/search?q=%23starting-the-mcp-server) + - [Ngrok Tunnel (Optional)](https://www.google.com/search?q=%23ngrok-tunnel-optional) + - [Installing & Configuring the Plugin in Dify](https://www.google.com/search?q=%23installing--configuring-the-plugin-in-dify) + - [Creating a Dify App](https://www.google.com/search?q=%23creating-a-dify-app) + - [Adding MCP Tools](https://www.google.com/search?q=%23adding-mcp-tools) + - [Example Calls](https://www.google.com/search?q=%23example-calls) ---- +----- -## Prerequisites +### Prerequisites -1. Clone the repository: - ```bash - git clone https://github.com/apache/doris-mcp-server.git - - cd doris-mcp-server - ``` - -2. Install the latest Python package and copy the environment template: - - ```bash - pip install mcp-doris-server - - cp .env.example .env - - vim .env - ``` - - Fill in your Doris FE connection settings in `.env`: - - ```env - DORIS_HOST=localhost - DORIS_PORT=9030 - DORIS_USER=root - DORIS_PASSWORD= - DORIS_DATABASE=information_schema - - DORIS_FE_HTTP_PORT=8030 - - # Optional: custom BE host list - DORIS_BE_HOSTS= - ``` +First, install `mcp-doris-server`: +```bash +pip install mcp-doris-server +``` ## Starting the MCP Server Run the startup script: ```bash -./start_server.sh +# Full configuration with database connection +doris-mcp-server \ + --transport http \ + --host 0.0.0.0 \ + --port 3000 \ + --db-host 127.0.0.1 \ + --db-port 9030 \ + --db-user root \ + --db-password your_password ``` -If successful, you will see logs like this: +If successful, you'll see logs similar to this: + ![Server start logs](../images/dify_start_server.png) ---- +----- ## Ngrok Tunnel (Optional) -If your Dify deployment requires a public endpoint, use [ngrok](https://ngrok.com): +If your Dify deployment requires a publicly accessible endpoint, you can use the **ngrok** tool. Ngrok is a third-party service that securely exposes local servers to the internet. -```bash -ngrok http http://localhost:3000 -``` -Use the generated public URL in subsequent steps. -![Ngrok tunnel](../images/dify_ngrok.png) - ---- +----- ## Installing & Configuring the Plugin in Dify -1. In the Dify console, go to **Plugin Marketplace**, search for and install **MCP‑SSE / StreamableHTTP**: - ![Install plugin](../images/dify_install_plugin.png) +1. In the Dify console, go to **Plugin Marketplace**, search for, and install **MCP‑SSE / StreamableHTTP**: + ![Install plugin](../images/dify_install_plugin.png) -2. After installation, click **Configure** and set the URL to your public or local address (e.g., `https://abc123.ngrok.io/mcp`): +2. After installation, click **Configure** and set the URL to your public or local address. For example, if you're using `ngrok`, this should be the public URL `ngrok` provides, in the format `https:///mcp`. If Dify can directly access your local server, use `http://localhost:3000/mcp`. - ```json - { - "doris_mcp_server": { - "transport": "streamable_http", - "url": "https:///mcp" - } - } - ``` + ```json + { + "doris_mcp_server": { + "transport": "streamable_http", + "url": "https:///mcp" + } + } + ``` + ![Configure plugin](../images/dify_config_mcp.png) - ![Configure plugin](../images/dify_config_mcp.png) - -3. Click **Save**. If configured correctly, you will see a green **Authorized** indicator: +3. Click **Save**. If configured correctly, you'll see a green **Authorized** indicator: ![Authorized](../images/dify_authorized.png) ---- - +----- ## Creating a Dify App -1. In the Dify console, click **New App** → **Blank App**. - +1. In the Dify console, click **New App** → **Blank App**. ![Create app](../images/dify_create_app.png) -2. Select **Agent** as the template, set **App Name** (e.g., `Doris ChatBI`). - +2. Select **Agent** as the template and set the **App Name** (e.g., `Doris ChatBI`). ![Agent setup](../images/dify_agent_setup.png) ---- +----- ## Instructions & Tool Configuration @@ -142,18 +114,15 @@ Paste the following into the **Instruction** field: ``` Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps: - 1. Analyze the user's question and match the most appropriate tool. 2. Use tool names and parameters exactly as defined; do not invent new ones. 3. Pass parameters in the required JSON format. 4. When calling tools, use: {"mcp_sse_call_tool": {"tool_name": "", "arguments": "{}"}} 5. Output plain text only—no XML tags. - User question: user_query - Return tool results or a final answer, including analysis. @@ -162,209 +131,23 @@ Return tool results or a final answer, including analysis. ### Adding MCP Tools -In the **Tools** pane, click **Add** twice to add two entries both named `mcp_sse` (they will inherit transport and URL from the plugin): - +In the **Tools** pane, click **Add** twice to add two entries, both named `mcp_sse` (they will inherit the transport and URL from the plugin): ![Add tools](../images/dify_add_tools.png) - ---- +----- ## Example Calls ### List Tables in Database -* **User**: What tables are in the database? -* **Result**: Dify will call the MCP tool to run `SHOW TABLES` and return the list. + * **User**: What tables are in the database? + + * **Result**: Dify will call the MCP tool to run `SHOW TABLES` and return the list. ![Query tables](../images/dify_query_tabels.png) ### Sales Trend Over Ten Years -* **User**: What has been the sales trend over the past ten years in the ssb database, and which year had the fastest growth? -* **Result**: The tool will execute the SQL, calculate growth rates, and return a trend chart or table. + * **User**: What has been the sales trend over the past ten years in the ssb database, and which year had the fastest growth? + + * **Result**: The tool will execute the SQL, calculate growth rates, and return data. ![Sales trend](../images/dify_sale_trend.png) - - - - -````md - - -# Dify Example: Integrating Doris MCP Server - -This document demonstrates how to integrate and use the `doris-mcp-server` in Dify to perform Doris SQL calls via MCP. - -## Table of Contents - -- [Prerequisites](#prerequisites) -- [Installation & Configuration](#installation--configuration) -- [Starting the MCP Server](#starting-the-mcp-server) -- [Ngrok Tunnel (Optional)](#ngrok-tunnel-optional) -- [Installing & Configuring the Plugin](#installing--configuring-the-plugin) -- [Creating a Dify App](#creating-a-dify-app) -- [Instructions & Tool Configuration](#instructions--tool-configuration) -- [Example Calls](#example-calls) - ---- - -## Prerequisites - -1. Clone the repository: - ```bash - git clone https://github.com/apache/doris-mcp-server.git - cd doris-mcp-server -```` - -2. Install the Python package and prepare the environment file: - - ```bash - pip install mcp-doris-server - cp .env.example .env - vim .env - ``` - -3. In `.env`, set your Doris front-end connection: - - ```env - DORIS_HOST=localhost - DORIS_PORT=9030 - DORIS_USER=root - DORIS_PASSWORD= - DORIS_DATABASE=information_schema - DORIS_FE_HTTP_PORT=8030 - # Optional: custom BE host list - DORIS_BE_HOSTS= - ``` - ---- - -## Installation & Configuration - -1. Install the MCP server package: - - ```bash - pip install mcp-doris-server - ``` -2. Copy and edit the environment template as shown above. - ---- - -## Starting the MCP Server - -Run the startup script: - -```bash -./start_server.sh -``` - -If successful, you will see logs like this: - -![Server start logs](../images/dify_start_server.png) - ---- - -## Ngrok Tunnel (Optional) - -If your Dify deployment requires a public endpoint, use [ngrok](https://ngrok.com/): - -```bash -ngrok http http://localhost:3000 -``` - -Use the generated URL in the plugin configuration. - - -![Ngrok tunnel](../images/dify_ngrok.png) - ---- - -## Installing & Configuring the Plugin - -1. In the Dify console, go to **Plugin Marketplace**, search for **MCP‑SSE / StreamableHTTP**, and install it. - -![Install plugin](../images/dify_install_plugin.png) - -2. Click **Configure**, and set the URL (e.g., `https:///mcp`): - -```json -{ - "doris_mcp_server": { - "transport": "streamable_http", - "url": "https:///mcp" - } -} -``` - -![Configure plugin](../images/dify_config_mcp.png) - -3. Click **Save**. A green **Authorized** indicator should appear: - -![Authorized](../images/dify_authorized.png) - ---- - -## Creating a Dify App - -1. In the Dify console, click **New App** → **Blank App**. - -![Create app](../images/dify_create_app.png) - -2. Select **Agent** as the template, set **App Name** (e.g., `Doris ChatBI`). - -![Agent setup](../images/dify_agent_setup.png) - ---- - -## Instructions & Tool Configuration - -### Instruction Block - -Paste the following into the **Instruction** field: - -``` - -Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps: - -1. Analyze the user's question and match the most appropriate tool. -2. Use tool names and parameters exactly as defined; do not invent new ones. -3. Pass parameters in the required JSON format. -4. When calling tools, use: - {"mcp_sse_call_tool": {"tool_name": "", "arguments": "{}"}} -5. Output plain text only—no XML tags. - - -User question: user_query - - - -Return tool results or a final answer, including analysis. - - -``` - -### Adding MCP Tools - -In the **Tools** pane, click **Add** twice to add two entries both named `mcp_sse` (they will inherit transport and URL from the plugin): - -![Add tools](../images/dify_add_tools.png) - ---- - -## Example Calls - -### List Tables in Database - -* **User**: What tables are in the database? -* **Result**: Dify calls the MCP tool to run `SHOW TABLES` and returns the list. - -![Query tables](../images/dify_query_tabels.png) - -### Sales Trend Over Ten Years - -* **User**: What has been the sales trend in the `ssb` database over the past ten years, and which year saw the fastest growth? -* **Result**: The tool executes SQL, computes growth rates, and returns a chart or table. - -![Sales trend](../images/dify_sale_trend.png) diff --git a/examples/images/dify_ngrok.png b/examples/images/dify_ngrok.png deleted file mode 100644 index 4d9dccc..0000000 Binary files a/examples/images/dify_ngrok.png and /dev/null differ diff --git a/examples/images/dify_start_server.png b/examples/images/dify_start_server.png index 9431501..94b2c8d 100644 Binary files a/examples/images/dify_start_server.png and b/examples/images/dify_start_server.png differ