diff --git a/examples/cursor/README.md b/examples/cursor/README.md new file mode 100644 index 0000000..ecaebbc --- /dev/null +++ b/examples/cursor/README.md @@ -0,0 +1,147 @@ + + + +# 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) diff --git a/examples/dify/README.md b/examples/dify/README.md new file mode 100644 index 0000000..cbd2ea9 --- /dev/null +++ b/examples/dify/README.md @@ -0,0 +1,156 @@ + + + +# 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) + + +3. Import from DSL,[dify_doris_dsl.yml](dify_doris_dsl.yml) + +----- + +## 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/cursor_add_mcp.png b/examples/images/cursor_add_mcp.png new file mode 100644 index 0000000..d02bf7c Binary files /dev/null and b/examples/images/cursor_add_mcp.png differ diff --git a/examples/images/cursor_agent.png b/examples/images/cursor_agent.png new file mode 100644 index 0000000..0d1cbb6 Binary files /dev/null and b/examples/images/cursor_agent.png differ diff --git a/examples/images/cursor_ask1.png b/examples/images/cursor_ask1.png new file mode 100644 index 0000000..aa8fbae Binary files /dev/null and b/examples/images/cursor_ask1.png differ diff --git a/examples/images/cursor_ask2.png b/examples/images/cursor_ask2.png new file mode 100644 index 0000000..96443a4 Binary files /dev/null and b/examples/images/cursor_ask2.png differ diff --git a/examples/images/cursor_doris-mcp.png b/examples/images/cursor_doris-mcp.png new file mode 100644 index 0000000..27d1d56 Binary files /dev/null and b/examples/images/cursor_doris-mcp.png differ