doris-mcp-server 0.0.1__tar.gz

doris_mcp_server-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hailin Xie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

doris_mcp_server-0.0.1/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: doris-mcp-server
+Version: 0.0.1
+Summary: An MCP server for analytics on Apache Doris database.
+Project-URL: Homepage, https://github.com/NomotoK/doris-mcp-server
+Project-URL: Repository, https://github.com/NomotoK/doris-mcp-server
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pyarrow>=19.0.1
+Requires-Dist: pymysql>=1.1.1
+Dynamic: license-file
+
+# **📖 Doris-MCP-Server**
+
+A lightweight **MCP server** designed for connecting to **Apache Doris** or other **MySQL compatible** database schemas, providing tools and prompts for LLM applications.
+
+This server enables LLMs and MCP clients to explore database schemas, run read-only SQL queries, and leverage pre-built analytical prompts — all through a standardized, secure MCP interface.
+
+> [!WARNING]
+> This is an early developer version of doris-mcp-server. Some functions may not operate properly and minor bugs may exist. If you have any quesions, please open an [issue](https://github.com/NomotoK/Doris-MCP-Server/issues).
+
+## **🚀 Features**
+
+### **🛠️ Tools**
+
+- Execute **read-only SQL queries** against your Doris database.
+- Perform **data analysis operations** such as retrieving yearly, monthly, and daily usage data.
+- Query metadata such as **database schemas**, **table structures**, and **resource usage**.
+
+### **🧠 Prompts**
+
+- Built-in prompt templates to assist LLMs in asking **analytics questions**.
+- Support for **user-defined** and **general-purpose** SQL analysis prompts.
+
+### **🗂️ Resources**
+
+- Expose your Doris **database schema** as **structured resources**.
+- Allow LLMs to **contextually access** table and field definitions to improve query understanding.
+
+## **📦 Installation Options**
+
+We recommend using [uv](https://docs.astral.sh/uv/) to manage your Python environment.
+
+### **Option 1: Install via shell script**
+
+> **Recommended for server deployment**
+
+This is the easiest way to install. Please copy the `setup.sh`  file in project and run it locally. For more information please refer: [Doris MCP install guide](INSTALL.md)
+
+1. Copy the `setup.sh` to local.
+2. Make the script executable:
+
+```bash
+chmod +x setup.sh
+```
+
+3. Run the script:
+
+```bash
+./setup.sh
+```
+
+The script will automatically install the server and help you walk through database configuration.
+### **Option 2: Install via `pip`**
+
+> **Recommended for production usage**
+
+```bash
+pip install doris-mcp-server
+```
+
+✅ After installation, the command-line tool server will be available to launch the MCP server.
+
+### **Option 3: Clone the source and install manually**
+
+> **Recommended if you want to modify the server**
+
+1. Fork and clone the repository:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/doris-mcp-server.git
+cd doris-mcp-server
+```
+
+1. Set up a local Python environment using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv venv
+uv pip install -e .
+```
+
+1. Add this server to your LLM client or Run the server:
+
+```bash
+uv run server
+```
+
+### **Option 4: Install using uv directly**
+
+> **For local editable installations**
+
+```bash
+uv pip install 'git+https://github.com/YOUR_USERNAME/doris-mcp-server.git'
+```
+
+## **⚙️ Post-Installation Setup**
+
+### **Step 1: Configure `.env` file**
+
+Doris-MCP-Server uses .env file to configure database connection info. Please follow these steps to finish configuration:
+
+#### **Configure through shell script**
+
+This is the most recommended and easiest way to setup. Please refer to [Doris MCP install guide](INSTALL.md).
+
+#### **Configure manually**
+
+After installing, navigate to the `doris_mcp_server/config/` directory inside your project directory. If you are using pip, your package will be installed in Python site-packages:
+
+- **Mac/Linux:** `/Users/YOUR_USERNAME/.local/lib/python3.x/site-packages/doris_mcp_server/config/`
+
+- **Windows:** `C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python3x\Lib\site-packages\doris_mcp_server\config\`
+
+You can run the following command to locate pip install location:
+
+```bash
+pip show doris-mcp-server
+```
+
+You will find a `.env.example` file:
+
+1. Copy `.env.example` to `.env`:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit .env to set your **Doris** database connection information:
+
+```bash
+DB_HOST=your-doris-host
+DB_PORT=9030
+DB_USER=your-username
+DB_PASSWORD=your-password
+DB_NAME=your-database
+
+MCP_SERVER_NAME=DorisAnalytics
+DEBUG=false
+```
+
+> [!NOTE]
+> If `.env `is missing, the server will attempt to auto-create it from `.env.example` but you must manually fill in correct credentials.
+
+### **Step 2: Configure MCP Client**
+
+To connect this server to an MCP-compatible client (e.g., Claude Desktop, CherryStudio, Cline), you need to modify your MCP client configuration JSON.
+
+Example if you are using CherryStudio:
+
+- name: doris-mcp-server
+- type: stdio
+- command: absolute/path/to/your/uv
+- arguments:
+
+```bash
+--directory
+/Users/hailin/dev/Doris-MCP-Server
+run
+server
+```
+
+
+Example if you are installing with pip (`mcp_setting.json`):
+
+```json
+{
+  "mcpServers": {
+    "DorisAnalytics": {
+      "command": "server",
+      "args": [],
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+Alternatively, if you prefer a more robust form:
+
+```json
+{
+  "mcpServers": {
+    "DorisAnalytics": {
+      "command": "python",
+      "args": ["-m", "doris_mcp_server.server"],
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+If you are installing with source code or using `setup.sh`:
+
+```json
+{
+"mcpServers": {
+	"DorisAnalytics": {
+		"disabled": false,
+		"timeout": 60,
+		"command": "absolute/path/to/uv",
+		"args": [
+			"--directory",
+			"absolute/path/to/mcp/server",
+			"run",
+			"server"
+		],
+		"transportType": "stdio"
+		}
+	}
+
+}
+```
+
+For more information on how to configure your client, please refer to :
+
+[For Server Developers - Model Context Protocol - Claude](https://modelcontextprotocol.io/quickstart/server)
+
+
+[配置和使用 MCP | CherryStudio](https://docs.cherry-ai.com/advanced-basic/mcp/config)
+
+✅ Now your LLM client will discover Doris Analytics tools, prompts, and resources through the MCP server.
+
+---
+
+## **🖥️ Usage**
+
+### **Testing MCP server**
+
+Before you start, you can run the `test.py` in the project `src/doris-mcp-server` directory to directly call the MCP Server functional interface to test resources, tools, etc. without using LLM (such as Claude, GPT, etc. models). You can control what functions to test by passing arguments through the command line.
+
+Test all resources exposed by the server:
+
+```bash
+python test.py --server server.py --test resources
+```
+
+or test all the tools provided by the server:
+
+```bash
+python test.py --server server.py --test tools
+```
+
+or test all functions of resources, tools, and prompt words at one time:
+
+```bash
+python test.py --server server.py --test all
+```
+
+### **Testing Database connection and run server**
+
+Launch the MCP server by running the command:
+
+```bash
+server
+```
+
+Or manually:
+
+```bash
+python -m doris_mcp_server.server
+```
+
+The server immediately attempts to connect to the database. If the connection is successful, after startup, you should see:
+
+```bash
+🚀 Doris MCP Server is starting...
+[DorisConnector] Connected to 127.0.0.1:9030
+✅ Database connection successful.
+[DorisConnector] Connection closed.
+```
+
+You can now use the tools and prompts inside your MCP client.
+
+## **📚 Project Structure Overview**
+
+```bash
+src/
+└── doris_mcp_server/
+	├── config/             # Configuration files
+	│   ├── __init__.py
+	│   ├── config.py       # Loads environment variables
+	│   ├── .env.example    # Environment variables template
+	│   └── .env            # Stores your database credentials
+	│
+	├── db/                 # Database interaction logic
+	│   ├── __init__.py
+	│   ├── db.py           # Doris database connection class
+	│   └── tools.py        # SQL query execution tools
+	│
+	├── res/                # Resource definitions (e.g., schemas)
+	│   ├── __init__.py
+	│   └── resources.py
+	│
+	├── prompts/            # Prebuilt prompt templates
+	│   ├── __init__.py
+	│   ├── general_prompts.py
+	│   └── customize_prompts.py
+	│
+	├── server.py           # Main entry point to start the MCP server
+	├── mcp_app.py          # MCP object
+	└── test.py             # Unit test script
+README.md                   # Documentation
+INSTALL.md                  # Installation guide
+LISENCE                     # Lisence
+setup.sh                    # Auto setup wizard
+pyproject.toml              # Project build configuration
+.gitignore                  # Git ignore settings
+```
+
+## **📜 License**
+
+This project is licensed under the [MIT License](LICENSE).
+
+## **🌟Acknowledgements**
+
+- Built using the [MCP Python SDK](https://pypi.org/project/mcp/).
+- Inspired by MCP official examples and best practices.
+
+---
+
+## **🤝 Contributions**
+
+Contributions are welcome! Feel free to open issues or submit pull requests.

doris_mcp_server-0.0.1/README.md

@@ -0,0 +1,320 @@
+# **📖 Doris-MCP-Server**
+
+A lightweight **MCP server** designed for connecting to **Apache Doris** or other **MySQL compatible** database schemas, providing tools and prompts for LLM applications.
+
+This server enables LLMs and MCP clients to explore database schemas, run read-only SQL queries, and leverage pre-built analytical prompts — all through a standardized, secure MCP interface.
+
+> [!WARNING]
+> This is an early developer version of doris-mcp-server. Some functions may not operate properly and minor bugs may exist. If you have any quesions, please open an [issue](https://github.com/NomotoK/Doris-MCP-Server/issues).
+
+## **🚀 Features**
+
+### **🛠️ Tools**
+
+- Execute **read-only SQL queries** against your Doris database.
+- Perform **data analysis operations** such as retrieving yearly, monthly, and daily usage data.
+- Query metadata such as **database schemas**, **table structures**, and **resource usage**.
+
+### **🧠 Prompts**
+
+- Built-in prompt templates to assist LLMs in asking **analytics questions**.
+- Support for **user-defined** and **general-purpose** SQL analysis prompts.
+
+### **🗂️ Resources**
+
+- Expose your Doris **database schema** as **structured resources**.
+- Allow LLMs to **contextually access** table and field definitions to improve query understanding.
+
+## **📦 Installation Options**
+
+We recommend using [uv](https://docs.astral.sh/uv/) to manage your Python environment.
+
+### **Option 1: Install via shell script**
+
+> **Recommended for server deployment**
+
+This is the easiest way to install. Please copy the `setup.sh`  file in project and run it locally. For more information please refer: [Doris MCP install guide](INSTALL.md)
+
+1. Copy the `setup.sh` to local.
+2. Make the script executable:
+
+```bash
+chmod +x setup.sh
+```
+
+3. Run the script:
+
+```bash
+./setup.sh
+```
+
+The script will automatically install the server and help you walk through database configuration.
+### **Option 2: Install via `pip`**
+
+> **Recommended for production usage**
+
+```bash
+pip install doris-mcp-server
+```
+
+✅ After installation, the command-line tool server will be available to launch the MCP server.
+
+### **Option 3: Clone the source and install manually**
+
+> **Recommended if you want to modify the server**
+
+1. Fork and clone the repository:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/doris-mcp-server.git
+cd doris-mcp-server
+```
+
+1. Set up a local Python environment using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv venv
+uv pip install -e .
+```
+
+1. Add this server to your LLM client or Run the server:
+
+```bash
+uv run server
+```
+
+### **Option 4: Install using uv directly**
+
+> **For local editable installations**
+
+```bash
+uv pip install 'git+https://github.com/YOUR_USERNAME/doris-mcp-server.git'
+```
+
+## **⚙️ Post-Installation Setup**
+
+### **Step 1: Configure `.env` file**
+
+Doris-MCP-Server uses .env file to configure database connection info. Please follow these steps to finish configuration:
+
+#### **Configure through shell script**
+
+This is the most recommended and easiest way to setup. Please refer to [Doris MCP install guide](INSTALL.md).
+
+#### **Configure manually**
+
+After installing, navigate to the `doris_mcp_server/config/` directory inside your project directory. If you are using pip, your package will be installed in Python site-packages:
+
+- **Mac/Linux:** `/Users/YOUR_USERNAME/.local/lib/python3.x/site-packages/doris_mcp_server/config/`
+
+- **Windows:** `C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python3x\Lib\site-packages\doris_mcp_server\config\`
+
+You can run the following command to locate pip install location:
+
+```bash
+pip show doris-mcp-server
+```
+
+You will find a `.env.example` file:
+
+1. Copy `.env.example` to `.env`:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit .env to set your **Doris** database connection information:
+
+```bash
+DB_HOST=your-doris-host
+DB_PORT=9030
+DB_USER=your-username
+DB_PASSWORD=your-password
+DB_NAME=your-database
+
+MCP_SERVER_NAME=DorisAnalytics
+DEBUG=false
+```
+
+> [!NOTE]
+> If `.env `is missing, the server will attempt to auto-create it from `.env.example` but you must manually fill in correct credentials.
+
+### **Step 2: Configure MCP Client**
+
+To connect this server to an MCP-compatible client (e.g., Claude Desktop, CherryStudio, Cline), you need to modify your MCP client configuration JSON.
+
+Example if you are using CherryStudio:
+
+- name: doris-mcp-server
+- type: stdio
+- command: absolute/path/to/your/uv
+- arguments:
+
+```bash
+--directory
+/Users/hailin/dev/Doris-MCP-Server
+run
+server
+```
+
+
+Example if you are installing with pip (`mcp_setting.json`):
+
+```json
+{
+  "mcpServers": {
+    "DorisAnalytics": {
+      "command": "server",
+      "args": [],
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+Alternatively, if you prefer a more robust form:
+
+```json
+{
+  "mcpServers": {
+    "DorisAnalytics": {
+      "command": "python",
+      "args": ["-m", "doris_mcp_server.server"],
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
+If you are installing with source code or using `setup.sh`:
+
+```json
+{
+"mcpServers": {
+	"DorisAnalytics": {
+		"disabled": false,
+		"timeout": 60,
+		"command": "absolute/path/to/uv",
+		"args": [
+			"--directory",
+			"absolute/path/to/mcp/server",
+			"run",
+			"server"
+		],
+		"transportType": "stdio"
+		}
+	}
+
+}
+```
+
+For more information on how to configure your client, please refer to :
+
+[For Server Developers - Model Context Protocol - Claude](https://modelcontextprotocol.io/quickstart/server)
+
+
+[配置和使用 MCP | CherryStudio](https://docs.cherry-ai.com/advanced-basic/mcp/config)
+
+✅ Now your LLM client will discover Doris Analytics tools, prompts, and resources through the MCP server.
+
+---
+
+## **🖥️ Usage**
+
+### **Testing MCP server**
+
+Before you start, you can run the `test.py` in the project `src/doris-mcp-server` directory to directly call the MCP Server functional interface to test resources, tools, etc. without using LLM (such as Claude, GPT, etc. models). You can control what functions to test by passing arguments through the command line.
+
+Test all resources exposed by the server:
+
+```bash
+python test.py --server server.py --test resources
+```
+
+or test all the tools provided by the server:
+
+```bash
+python test.py --server server.py --test tools
+```
+
+or test all functions of resources, tools, and prompt words at one time:
+
+```bash
+python test.py --server server.py --test all
+```
+
+### **Testing Database connection and run server**
+
+Launch the MCP server by running the command:
+
+```bash
+server
+```
+
+Or manually:
+
+```bash
+python -m doris_mcp_server.server
+```
+
+The server immediately attempts to connect to the database. If the connection is successful, after startup, you should see:
+
+```bash
+🚀 Doris MCP Server is starting...
+[DorisConnector] Connected to 127.0.0.1:9030
+✅ Database connection successful.
+[DorisConnector] Connection closed.
+```
+
+You can now use the tools and prompts inside your MCP client.
+
+## **📚 Project Structure Overview**
+
+```bash
+src/
+└── doris_mcp_server/
+	├── config/             # Configuration files
+	│   ├── __init__.py
+	│   ├── config.py       # Loads environment variables
+	│   ├── .env.example    # Environment variables template
+	│   └── .env            # Stores your database credentials
+	│
+	├── db/                 # Database interaction logic
+	│   ├── __init__.py
+	│   ├── db.py           # Doris database connection class
+	│   └── tools.py        # SQL query execution tools
+	│
+	├── res/                # Resource definitions (e.g., schemas)
+	│   ├── __init__.py
+	│   └── resources.py
+	│
+	├── prompts/            # Prebuilt prompt templates
+	│   ├── __init__.py
+	│   ├── general_prompts.py
+	│   └── customize_prompts.py
+	│
+	├── server.py           # Main entry point to start the MCP server
+	├── mcp_app.py          # MCP object
+	└── test.py             # Unit test script
+README.md                   # Documentation
+INSTALL.md                  # Installation guide
+LISENCE                     # Lisence
+setup.sh                    # Auto setup wizard
+pyproject.toml              # Project build configuration
+.gitignore                  # Git ignore settings
+```
+
+## **📜 License**
+
+This project is licensed under the [MIT License](LICENSE).
+
+## **🌟Acknowledgements**
+
+- Built using the [MCP Python SDK](https://pypi.org/project/mcp/).
+- Inspired by MCP official examples and best practices.
+
+---
+
+## **🤝 Contributions**
+
+Contributions are welcome! Feel free to open issues or submit pull requests.

doris_mcp_server-0.0.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=67", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "doris-mcp-server"
+version = "0.0.1"
+description = "An MCP server for analytics on Apache Doris database."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.6.0",
+    "pandas>=2.2.3",
+    "pyarrow>=19.0.1",
+    "pymysql>=1.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/NomotoK/doris-mcp-server"
+Repository = "https://github.com/NomotoK/doris-mcp-server"
+
+[project.scripts]
+server = "doris_mcp_server.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

doris_mcp_server-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

doris_mcp_server-0.0.1/src/doris_mcp_server/config/__init__.py

@@ -0,0 +1,3 @@
+from .config import DB_CONFIG, MCP_SERVER_NAME, DEBUG
+
+__all__ = ["DB_CONFIG", "MCP_SERVER_NAME", "DEBUG"]