redshift-comment-mcp 0.1.0a0__py3-none-any.whl

redshift_comment_mcp/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0a0'
+__version_tuple__ = version_tuple = (0, 1, 0, 'a0')
+
+__commit_id__ = commit_id = None

redshift_comment_mcp/connection.py

@@ -0,0 +1,81 @@
+import logging
+import awswrangler as wr
+import redshift_connector
+from typing import Dict, Any
+from contextlib import contextmanager
+
+logger = logging.getLogger(__name__)
+
+class RedshiftConnectionConfig:
+    """
+    Redshift 連線配置類，儲存連線參數供每次使用時建立連線。
+    """
+    def __init__(self, host: str, port: int, user: str, password: str, dbname: str):
+        self.host = host
+        self.port = port
+        self.user = user
+        self.password = password
+        self.dbname = dbname
+        
+    def create_connection(self):
+        """
+        使用 redshift-connector 建立新的 Redshift 連線。
+        """
+        logger.debug(f"正在建立 Redshift 連線到 {self.host}:{self.port}/{self.dbname}")
+        try:
+            connection = redshift_connector.connect(
+                host=self.host,
+                port=self.port,
+                user=self.user,
+                password=self.password,
+                database=self.dbname
+            )
+            logger.debug("Redshift 連線建立成功")
+            return connection
+        except Exception as e:
+            logger.error(f"建立 Redshift 連線失敗: {e}", exc_info=True)
+            raise
+
+    @contextmanager
+    def get_connection(self):
+        """
+        Context manager 用於自動管理連線的建立和清理。
+        
+        使用方式:
+        with config.get_connection() as conn:
+            # 使用 conn 進行查詢
+            df = wr.redshift.read_sql_query(sql, con=conn)
+        """
+        connection = None
+        try:
+            connection = self.create_connection()
+            yield connection
+        finally:
+            if connection:
+                try:
+                    connection.close()
+                    logger.debug("Redshift 連線已關閉")
+                except Exception as e:
+                    logger.warning(f"關閉連線時發生警告: {e}")
+
+def create_redshift_config(host: str, port: int, user: str, password: str, dbname: str) -> RedshiftConnectionConfig:
+    """
+    建立 Redshift 連線配置。
+    """
+    logger.info(f"建立 Redshift 連線配置: {host}:{port}/{dbname}")
+    
+    # 驗證連線配置
+    config = RedshiftConnectionConfig(host, port, user, password, dbname)
+    
+    # 測試連線以確保配置正確
+    try:
+        with config.get_connection() as conn:
+            # 簡單測試查詢
+            test_query = "SELECT 1 AS test"
+            wr.redshift.read_sql_query(test_query, con=conn)
+            logger.info("Redshift 連線配置驗證成功")
+    except Exception as e:
+        logger.error(f"Redshift 連線配置驗證失敗: {e}", exc_info=True)
+        raise ValueError(f"無法建立 Redshift 連線，請檢查連線參數。錯誤: {e}")
+    
+    return config

redshift_comment_mcp/redshift_tools.py

@@ -0,0 +1,135 @@
+import logging
+import awswrangler as wr
+from fastmcp import FastMCP
+from typing import List, Dict
+from .connection import RedshiftConnectionConfig
+
+logger = logging.getLogger(__name__)
+
+# --- Redshift Tools Implementation ---
+class RedshiftTools:
+    """
+    Provides a set of tools for interacting with Redshift databases to support guided data exploration.
+    Uses a connect/disconnect pattern for each operation to ensure maximum robustness.
+    """
+    def __init__(self, connection_config: RedshiftConnectionConfig):
+        self.config = connection_config
+        self.mcp = FastMCP("Redshift Tools")
+        self._setup_tools()
+
+    def _setup_tools(self):
+        """設定所有 MCP 工具"""
+        
+        @self.mcp.tool
+        def list_schemas() -> List[Dict[str, str]]:
+            """
+            [功能] (探索流程第一步) 列出資料庫中所有可用的 schema 及其註解。
+            [用途] 用於理解資料庫的頂層結構和各個資料主題域的用途。
+            """
+            sql = """
+            SELECT
+                n.nspname AS schema_name,
+                d.description AS schema_comment
+            FROM pg_namespace n
+            LEFT JOIN pg_description d ON n.oid = d.objoid
+            WHERE n.nspowner > 1 AND n.nspname NOT LIKE 'pg_%' AND n.nspname <> 'information_schema'
+            ORDER BY n.nspname;
+            """
+            
+            # 每次使用時建立新連線
+            with self.config.get_connection() as conn:
+                df = wr.redshift.read_sql_query(sql, con=conn)
+                df['schema_comment'] = df['schema_comment'].fillna('')
+                return df.to_dict(orient='records')
+
+        @self.mcp.tool
+        def list_tables(schema_name: str) -> List[Dict[str, str]]:
+            """
+            [功能] (探索流程第二步) 列出指定 schema 中的所有資料表、視圖及其註解。
+            [用途] 在選擇一個 schema 後，用此工具來了解該主題域下有哪些資料表以及它們的具體內容。
+            """
+            # 輸入驗證
+            if not schema_name or not schema_name.isidentifier():
+                raise ValueError("無效的 schema 名稱。")
+                
+            sql = """
+            SELECT
+                t.table_name,
+                t.table_type,
+                d.description AS table_comment
+            FROM information_schema.tables t
+            LEFT JOIN pg_class c ON c.relname = t.table_name AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = t.table_schema)
+            LEFT JOIN pg_description d ON d.objoid = c.oid AND d.objsubid = 0
+            WHERE t.table_schema = %s
+            ORDER BY t.table_name;
+            """
+            
+            # 每次使用時建立新連線
+            with self.config.get_connection() as conn:
+                df = wr.redshift.read_sql_query(sql, con=conn, params=[schema_name])
+                df['table_comment'] = df['table_comment'].fillna('')
+                return df.to_dict(orient='records')
+
+        @self.mcp.tool
+        def list_columns(schema_name: str, table_name: str) -> List[Dict[str, str]]:
+            """
+            [功能] (探索流程第三步) 列出指定資料表的所有欄位、資料型態及其註解。
+            [用途] 在鎖定目標資料表後，用此工具來精確理解每個欄位的商業意義、格式和用途。
+            """
+            # 輸入驗證
+            if not schema_name.isidentifier() or not table_name.isidentifier():
+                raise ValueError("無效的 schema 或 table 名稱。")
+                
+            sql = """
+            SELECT
+                c.column_name,
+                c.data_type,
+                c.is_nullable,
+                d.description AS column_comment
+            FROM information_schema.columns c
+            LEFT JOIN pg_description d ON d.objoid = (
+                SELECT oid FROM pg_class WHERE relname = c.table_name AND relnamespace = (
+                    SELECT oid FROM pg_namespace WHERE nspname = c.table_schema
+                )
+            ) AND d.objsubid = c.ordinal_position
+            WHERE c.table_schema = %s AND c.table_name = %s
+            ORDER BY c.ordinal_position;
+            """
+            
+            # 每次使用時建立新連線
+            with self.config.get_connection() as conn:
+                df = wr.redshift.read_sql_query(sql, con=conn, params=[schema_name, table_name])
+                df['column_comment'] = df['column_comment'].fillna('')
+                return df.to_dict(orient='records')
+
+        @self.mcp.tool
+        def execute_sql(sql_statement: str) -> List[Dict]:
+            """
+            [功能] (最終執行步驟) 在探索完資料結構後，執行一個 SQL 查詢以獲取資料。
+            [注意] 此工具僅能執行唯讀的 SELECT 查詢。任何 DML/DDL 操作都將失敗。
+            [範例] 若要查詢 public schema 中的 users 表，SQL 應為 "SELECT * FROM public.users LIMIT 10;"
+            """
+            # 基本 SQL 安全檢查
+            sql_upper = sql_statement.strip().upper()
+            if not sql_upper.startswith('SELECT') and not sql_upper.startswith('WITH'):
+                raise ValueError("此工具僅支援 SELECT 和 WITH 查詢語句。")
+            
+            # 檢查危險的 SQL 關鍵字
+            dangerous_keywords = ['DROP', 'DELETE', 'UPDATE', 'INSERT', 'ALTER', 'CREATE', 'TRUNCATE']
+            for keyword in dangerous_keywords:
+                if keyword in sql_upper:
+                    raise ValueError(f"不允許使用 {keyword} 語句。")
+            
+            try:
+                # 每次使用時建立新連線
+                with self.config.get_connection() as conn:
+                    df = wr.redshift.read_sql_query(sql_statement, con=conn)
+                    return df.to_dict(orient='records')
+            except Exception as e:
+                logger.error(f"執行 SQL 失敗: {sql_statement}", exc_info=True)
+                error_message = f"執行 SQL 時發生錯誤，請檢查您的語法。原始錯誤訊息: {e}"
+                raise ValueError(error_message)
+
+    def get_server(self):
+        """取得配置好的 MCP 伺服器"""
+        return self.mcp

redshift_comment_mcp/server.py

@@ -0,0 +1,56 @@
+import os
+import argparse
+import logging
+from .connection import create_redshift_config
+from .redshift_tools import RedshiftTools
+
+logger = logging.getLogger(__name__)
+
+def main():
+    """主程式進入點，負責解析命令列參數並啟動伺服器。"""
+    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(name)s - %(message)s')
+    parser = argparse.ArgumentParser(description="Redshift MCP Server")
+    parser.add_argument("--host", required=True, help="Redshift 主機位址")
+    parser.add_argument("--port", type=int, default=5439, help="Redshift 連接埠")
+    parser.add_argument("--user", required=True, help="Redshift 使用者名稱")
+    parser.add_argument("--password", required=False, help="Redshift 密碼 (若未提供，則嘗試從 REDSHIFT_PASSWORD 環境變數讀取)")
+    parser.add_argument("--dbname", required=True, help="Redshift 資料庫名稱")
+    args = parser.parse_args()
+
+    password = args.password or os.getenv('REDSHIFT_PASSWORD')
+    if not password:
+        raise ValueError("必須透過 --password 參數或 REDSHIFT_PASSWORD 環境變數提供密碼。")
+
+    logger.info("正在啟動 Redshift MCP 伺服器...")
+    
+    # 1. 建立 Redshift 連線配置（會進行連線測試）
+    try:
+        connection_config = create_redshift_config(
+            host=args.host,
+            port=args.port,
+            user=args.user,
+            password=password,
+            dbname=args.dbname
+        )
+        logger.info("Redshift 連線配置建立成功")
+    except Exception as e:
+        logger.critical(f"無法建立 Redshift 連線配置：{e}")
+        return
+
+    # 2. 實例化工具提供者，傳入連線配置
+    redshift_tools = RedshiftTools(connection_config)
+    mcp_server = redshift_tools.get_server()
+    
+    # 3. 啟動 MCP 伺服器
+    try:
+        logger.info("MCP 伺服器啟動中...")
+        mcp_server.run()  # FastMCP defaults to STDIO transport
+    except KeyboardInterrupt:
+        logger.info("收到中止信號，正在關閉伺服器...")
+    except Exception as e:
+        logger.error(f"伺服器運行時發生錯誤: {e}", exc_info=True)
+    finally:
+        logger.info("MCP 伺服器已關閉。")
+
+if __name__ == "__main__":
+    main()

redshift_comment_mcp-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: redshift-comment-mcp
+Version: 0.1.0a0
+Summary: A Model-Context Protocol server for Amazon Redshift.
+Author-email: kouko <kouko@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2025 Redshift Comment MCP Contributors
+        
+        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.
+Project-URL: Homepage, https://github.com/kouko/redshift-comment-mcp
+Project-URL: Bug Tracker, https://github.com/kouko/redshift-comment-mcp/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: awswrangler[redshift]
+Requires-Dist: redshift-connector
+Requires-Dist: pandas
+Requires-Dist: fastmcp
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file
+
+# Redshift MCP 伺服器
+
+這是一個基於 Model Context Protocol (MCP) 的 Amazon Redshift 資料庫探索工具，專為 AI 語言模型設計，提供結構化的資料庫探索功能。
+
+## 功能特色
+
+- **引導式資料探索**：遵循 Schema → Table → Column 的探索流程
+- **穩健連線管理**：採用每次使用時建立/切斷連線的模式確保最高穩定性
+- **MCP 標準協定**：使用 FastMCP 框架實作，符合 MCP 協定標準
+- **多種工具**：提供 schema、table、column 列表查詢及 SQL 執行功能
+
+## 安裝
+
+### 從 PyPI 安裝 (推薦)
+
+```bash
+pip install redshift-comment-mcp
+```
+
+### 本地開發安裝
+
+```bash
+git clone https://github.com/kouko/redshift-comment-mcp.git
+cd redshift-comment-mcp
+pip install -e ".[dev]"
+```
+
+**系統需求**：本專案需要 Python 3.10 或更高版本。
+
+## 使用方式
+
+### 命令列執行
+
+```bash
+redshift-comment-mcp --host your-cluster.region.redshift.amazonaws.com \
+                --port 5439 \
+                --user your_username \
+                --password your_password \
+                --dbname your_database
+```
+
+### 使用環境變數
+
+您可以將密碼存放在環境變數中：
+
+```bash
+export REDSHIFT_PASSWORD=your_password
+redshift-comment-mcp --host your-cluster.region.redshift.amazonaws.com \
+                --port 5439 \
+                --user your_username \
+                --dbname your_database
+```
+
+### MCP Client 設定
+
+在 MCP Client 的設定檔中加入以下設定：
+
+```json
+{
+  "mcpServers": {
+    "redshift-comment-mcp": {
+      "command": "uvx",
+      "args": [
+        "redshift-comment-mcp@latest",
+        "--host", "your-cluster.region.redshift.amazonaws.com",
+        "--port", "5439",
+        "--user", "your_username",
+        "--password", "your_password",
+        "--dbname", "your_database"
+      ]
+    }
+  }
+}
+```
+
+### 本地開發設定
+
+對於本地開發，可以使用以下設定：
+
+```json
+{
+  "mcpServers": {
+    "redshift-comment-mcp-local": {
+      "command": "python",
+      "args": [
+        "-m", "redshift_comment_mcp.server",
+        "--host", "your-local-db-host",
+        "--port", "5439",
+        "--user", "your_username",
+        "--password", "your_password",
+        "--dbname", "dev"
+      ],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+## 可用工具
+
+### 1. List Schemas
+列出資料庫中所有可用的 schema 及其註解。這是探索流程的第一步。
+
+### 2. List Tables
+列出指定 schema 中的所有資料表、視圖及其註解。
+
+### 3. List Columns
+列出指定資料表的所有欄位、資料型態及其註解。
+
+### 4. Execute SQL
+執行 SQL 查詢以獲取資料。僅支援 SELECT 查詢。
+
+## 開發
+
+### 執行測試
+
+```bash
+pytest tests/
+```
+
+### 建置套件
+
+```bash
+python -m build
+```
+
+### 發佈到 PyPI
+
+#### 自動化發佈（推薦）
+本專案使用 GitHub Actions 自動化發佈流程：
+
+1. 更新 `pyproject.toml` 中的版本號
+2. 建立 GitHub Release
+3. GitHub Actions 自動執行測試、建置並發佈到 PyPI
+
+詳細設定請參考 [.github/DEPLOYMENT.md](.github/DEPLOYMENT.md)
+
+#### 手動發佈
+```bash
+python -m twine upload dist/*
+```
+
+## 資料庫註解最佳實踐
+
+為了讓 AI 更好地理解您的資料庫結構，建議在資料庫中新增結構化的註解：
+
+### Schema 註解範例
+```sql
+COMMENT ON SCHEMA sales IS '[用途] 儲存所有與線上零售相關的銷售數據。 [主要實體] 訂單, 客戶, 產品';
+```
+
+### Table 註解範例
+```sql
+COMMENT ON TABLE sales.orders IS '[實體] 訂單 [內容] 包含每一筆客戶訂單的詳細記錄。 [PK] order_id [FK] customer_id -> customers.customer_id';
+```
+
+### Column 註解範例
+```sql
+COMMENT ON COLUMN sales.orders.revenue IS '[定義] 該筆訂單的總銷售金額。 [語意類型] Metric [單位] 新台幣 [計算方式] 未稅商品總價 + 稅金 - 折扣。';
+```
+
+## 授權
+
+MIT License
+
+## 貢獻
+
+歡迎提交 Issue 和 Pull Request。

redshift_comment_mcp-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,11 @@
+redshift_comment_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+redshift_comment_mcp/_version.py,sha256=BwAbItUzx8GHBL4bMhoyf_-80mXHGCMRjXF_rX0pWbM,712
+redshift_comment_mcp/connection.py,sha256=N2AnBP2zxorhCjgDOFJOEhl3HmuRotA7y4rFvbowAhY,2802
+redshift_comment_mcp/redshift_tools.py,sha256=zoA2IDi5wDuWjHEZ5XJ4Hfx0egRi2mTBAnvMpmJRxi0,6286
+redshift_comment_mcp/server.py,sha256=l2GUt0zFEekHchBe8qFX06pA_HNym6WY964e3ApPNHo,2267
+redshift_comment_mcp-0.1.0a0.dist-info/licenses/LICENSE,sha256=XzRdj7ZLKC7b5gI7Q5et406Gt6OltI0lgBdbAHu5muk,1089
+redshift_comment_mcp-0.1.0a0.dist-info/METADATA,sha256=fwpo-CFO_TkEnSHrD5HTK8gtcIcTwszI05oQiPNQDMk,6036
+redshift_comment_mcp-0.1.0a0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+redshift_comment_mcp-0.1.0a0.dist-info/entry_points.txt,sha256=xJNvUHN7qO54_K1lVLtBClwosE-Aheh-JUX6Jx7Qyhs,74
+redshift_comment_mcp-0.1.0a0.dist-info/top_level.txt,sha256=SZLawNXj6WzG1McXwau3YDqHhLYakjPj_imvdRjLS6A,21
+redshift_comment_mcp-0.1.0a0.dist-info/RECORD,,

redshift_comment_mcp-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

redshift_comment_mcp-0.1.0a0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+redshift-comment-mcp = redshift_comment_mcp.server:main

redshift_comment_mcp-0.1.0a0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Redshift Comment MCP Contributors
+
+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.

redshift_comment_mcp-0.1.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+redshift_comment_mcp