add cursor demo (#4)

* add cursor demo

* fix image

examples/cursor/README.md

@@ -0,0 +1,147 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+
+# Cursor Example: Integrating Doris MCP Server
+
+This guide provides step-by-step instructions on how to integrate the `doris-mcp-server` with the [Cursor](https://cursor.sh/) IDE. This integration allows you to interact with your Apache Doris database using natural language queries directly within Cursor's AI chat.
+
+## Table of Contents
+
+* [Prerequisites](#prerequisites)
+* [Step 1: Set Up the Project](#step-1-set-up-the-project)
+* [Step 2: Configure the MCP Server in Cursor](#step-2-configure-the-mcp-server-in-cursor)
+* [Step 3: Verify the Integration](#step-3-verify-the-integration)
+* [Step 4: Query Your Database](#step-4-query-your-database)
+
+  * [Example 1: List Tables](#example-1-list-tables)
+  * [Example 2: Analyze Sales Trends](#example-2-analyze-sales-trends)
+
+---
+
+### Prerequisites
+
+Before you begin, ensure you have the following installed and configured:
+
+* The **Cursor** IDE
+* **Git** for cloning the repository
+* Access to an **Apache Doris** cluster (FE host, port, username, and password)
+* **uv**, a fast Python package installer and runner
+
+You can install `uv` with one of the following commands:
+
+```bash
+# For macOS (recommended)
+brew install uv
+
+# For other systems using pipx
+pipx install uv
+```
+
+---
+
+### Step 1: Set Up the Project
+
+First, clone the `doris-mcp-server` repository to your local machine:
+
+```bash
+git clone https://github.com/apache/doris-mcp-server.git
+
+cd doris-mcp-server
+```
+
+The necessary dependencies are listed in `requirements.txt` and will be managed automatically by `uv` in the next step.
+
+---
+
+### Step 2: Configure the MCP Server in Cursor
+
+1. Open the cloned `doris-mcp-server` directory in Cursor.
+2. Click the ⚙️ icon (top-right), then go to **Tools & Integrations**.
+   ![add MCP Server](../images/cursor_add_mcp.png)
+3. Click **Add a custom MCP Server**.
+4. Paste the following JSON configuration:
+
+```json
+{
+  "mcpServers": {
+    "doris-mcp": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project",
+        "/path/to/your/doris-mcp-server",
+        "mcp-doris-server"
+      ],  
+      "env": {
+        "DB_HOST": "your_doris_fe_host",
+        "DB_PORT": "9030",
+        "DB_USER": "your_username",
+        "DB_PASSWORD": "your_password",
+        "DB_DATABASE": "ssb"
+      }
+    }
+  }
+}
+```
+
+> ⚠️ **Important:**
+>
+> * Replace `"/path/to/your/doris-mcp-server"` with the **absolute path** to your local project directory.
+> * Fill in your actual Doris FE host, username, password, and database name.
+
+---
+
+### Step 3: Verify the Integration
+
+Once saved, go back to the **Settings** panel. If everything is configured correctly, you’ll see a green status dot next to `doris-mcp-server`, along with available tools like `exec_query`.
+
+![MCP Server](../images/cursor_doris-mcp.png)
+
+---
+
+### Step 4: Query Your Database
+
+You can now chat with Cursor Agent to run SQL queries against your Doris database.
+
+1. Open the chat panel using `Cmd + K` (macOS) or `Ctrl + K` (Windows/Linux), or click the chat icon in the top-right.
+2. Switch to **Agent Mode**.
+3. Start asking questions using natural language.
+
+![ask](../images/cursor_agent.png)
+
+---
+
+#### Example 1: List Tables
+
+> **Prompt:** What tables are in the `ssb` database?
+
+The agent will call the `get_db_table_list` tool and return the results.
+
+![ask](../images/cursor_ask1.png)
+
+---
+
+#### Example 2: Analyze Sales Trends
+
+> **Prompt:** What has been the sales trend over the past ten years in the `ssb` database, and which year had the fastest growth?
+
+The agent will generate an appropriate SQL query, send it to the MCP server, and interpret the results to give you growth trends and highlights.
+
+![ask](../images/cursor_ask2.png)

examples/dify/README.md

@@ -0,0 +1,156 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+
+# 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://<your-domain>/mcp`. If Dify can directly access your local server, use `http://localhost:3000/mcp`.
+
+    ```json
+    {
+      "doris_mcp_server": {
+        "transport": "streamable_http",
+        "url": "https://<your-domain>/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)
+
+
+3.  Import from DSL,[dify_doris_dsl.yml](dify_doris_dsl.yml)
+
+-----
+
+## Instructions & Tool Configuration
+
+### Instruction Block
+
+Paste the following into the **Instruction** field:
+
+```
+<instruction>
+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": "<tool_name>", "arguments": "{}"}}
+5. Output plain text only—no XML tags.
+<input>
+User question: user_query
+</input>
+<output>
+Return tool results or a final answer, including analysis.
+</output>
+</instruction>
+```
+
+### 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)