diff --git a/README.md b/README.md index 5af31ff..47df73e 100644 --- a/README.md +++ b/README.md @@ -225,7 +225,6 @@ This command starts the FastAPI application with Streamable HTTP MCP service. * **Streamable HTTP**: `http://:/mcp` (Primary MCP endpoint - supports GET, POST, DELETE, OPTIONS) * **Health Check**: `http://:/health` -* **Status Check**: `http://:/status` > **Note**: The server uses Streamable HTTP for web-based communication, providing unified request/response and streaming capabilities. diff --git a/examples/dify/dify_demo.md b/examples/dify/dify_demo.md new file mode 100644 index 0000000..88c210a --- /dev/null +++ b/examples/dify/dify_demo.md @@ -0,0 +1,153 @@ + + + +# Dify Example: Integrating Doris MCP Server + +This document demonstrates how to integrate and use `doris-mcp-server` in Dify to perform Doris SQL calls via MCP. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [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 + +First, install `mcp-doris-server`: + +```bash +pip install mcp-doris-server +``` + +## Starting the MCP Server + +Run the startup script: + +```bash +# 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'll see logs similar to this: + +![Server start logs](../images/dify_start_server.png) + +----- + +## Ngrok Tunnel (Optional) + +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. + + +----- + +## 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) + +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" + } + } + ``` + ![Configure plugin](../images/dify_config_mcp.png) + +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**. +![Create app](../images/dify_create_app.png) + +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 + +### 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 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. + ![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 data. + ![Sales trend](../images/dify_sale_trend.png) diff --git a/examples/images/dify_add_tools.png b/examples/images/dify_add_tools.png new file mode 100644 index 0000000..89f55e7 Binary files /dev/null and b/examples/images/dify_add_tools.png differ diff --git a/examples/images/dify_agent_setup.png b/examples/images/dify_agent_setup.png new file mode 100644 index 0000000..d2ce46c Binary files /dev/null and b/examples/images/dify_agent_setup.png differ diff --git a/examples/images/dify_authorized.png b/examples/images/dify_authorized.png new file mode 100644 index 0000000..d17ccdf Binary files /dev/null and b/examples/images/dify_authorized.png differ diff --git a/examples/images/dify_config_mcp.png b/examples/images/dify_config_mcp.png new file mode 100644 index 0000000..a1a91ec Binary files /dev/null and b/examples/images/dify_config_mcp.png differ diff --git a/examples/images/dify_create_app.png b/examples/images/dify_create_app.png new file mode 100644 index 0000000..e5a7e78 Binary files /dev/null and b/examples/images/dify_create_app.png differ diff --git a/examples/images/dify_install_plugin.png b/examples/images/dify_install_plugin.png new file mode 100644 index 0000000..538c5f1 Binary files /dev/null and b/examples/images/dify_install_plugin.png differ diff --git a/examples/images/dify_query_tabels.png b/examples/images/dify_query_tabels.png new file mode 100644 index 0000000..d1bf773 Binary files /dev/null and b/examples/images/dify_query_tabels.png differ diff --git a/examples/images/dify_sale_trend.png b/examples/images/dify_sale_trend.png new file mode 100644 index 0000000..510aff8 Binary files /dev/null and b/examples/images/dify_sale_trend.png differ diff --git a/examples/images/dify_start_server.png b/examples/images/dify_start_server.png new file mode 100644 index 0000000..94b2c8d Binary files /dev/null and b/examples/images/dify_start_server.png differ