sqlsaber 0.2.0__tar.gz → 0.4.0__tar.gz

sqlsaber-0.4.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to SQLSaber will be documented in this file.
+
+## [Unreleased]
+
+## [0.4.0] - 2025-06-25
+
+### Added
+
+- MCP (Model Context Protocol) server support
+- `saber-mcp` console script for running MCP server
+- MCP tools: `get_databases()`, `list_tables()`, `introspect_schema()`, `execute_sql()`
+- Instructions and documentation for configuring MCP clients (Claude Code, etc.)
+
+## [0.3.0] - 2025-06-25
+
+### Added
+
+- Support for CSV files as a database option: `saber query -d mydata.csv`
+
+### Changed
+
+- Extracted tools to BaseSQLAgent for better inheritance across SQLAgents
+
+### Fixed
+
+- Fixed getting row counts for SQLite
+
+## [0.2.0] - 2025-06-24
+
+### Added
+
+- SSL support for database connections during configuration
+- Memory feature similar to Claude Code
+- Support for SQLite and MySQL databases
+- Model configuration (configure, select, set, reset) - Anthropic models only
+- Comprehensive database command to securely store multiple database connection info
+- API key storage using keyring for security
+- Interactive questionary for all user interactions
+- Test suite implementation
+
+### Changed
+
+- Package renamed from original name to sqlsaber
+- Better configuration handling
+- Simplified CLI interface
+- Refactored query stream function into smaller functions
+- Interactive markup cleanup
+- Extracted table display functionality
+- Refactored and cleaned up codebase structure
+
+### Fixed
+
+- Fixed list_tables tool functionality
+- Fixed introspect schema tool
+- Fixed minor type checking errors
+- Check before adding new database to prevent duplicates
+
+### Removed
+
+- Removed write support completely for security
+
+## [0.1.0] - 2025-06-19
+
+### Added
+
+- First working version of SQLSaber
+- Streaming tool response and status messages
+- Schema introspection with table listing
+- Result row streaming as agent works
+- Database connection and query capabilities
+- Added publish workflow
+- Created documentation and README
+- Added CLAUDE.md for development instructions

{sqlsaber-0.2.0 → sqlsaber-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlsaber
-Version: 0.2.0
+Version: 0.4.0
 Summary: SQLSaber - Agentic SQL assistant like Claude Code
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -8,8 +8,10 @@ Requires-Dist: aiomysql>=0.2.0
 Requires-Dist: aiosqlite>=0.21.0
 Requires-Dist: anthropic>=0.54.0
 Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastmcp>=2.9.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: keyring>=25.6.0
+Requires-Dist: pandas>=2.0.0
 Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=13.7.0
@@ -33,6 +35,7 @@ Ask your questions in natural language and it will gather the right context and
 - 💬 Interactive REPL mode
 - 🎨 Beautiful formatted output with syntax highlighting
 - 🗄️ Support for PostgreSQL, SQLite, and MySQL
+- 🔌 MCP (Model Context Protocol) server support
 
 ## Installation
 
@@ -139,6 +142,43 @@ saber query "show me the distribution of customer ages"
 saber query "which products had the highest sales growth last quarter?"
 ```
 
+## MCP Server Integration
+
+SQLSaber includes an MCP (Model Context Protocol) server that allows AI agents like Claude Code to directly leverage tools available in SQLSaber.
+
+### Starting the MCP Server
+
+Run the MCP server using uvx:
+
+```bash
+uvx saber-mcp
+```
+
+### Configuring MCP Clients
+
+#### Claude Code
+
+Add SQLSaber as an MCP server in Claude Code:
+
+```bash
+claude mcp add -- uvx saber-mcp
+```
+
+#### Other MCP Clients
+
+For other MCP clients, configure them to run the command: `uvx saber-mcp`
+
+### Available MCP Tools
+
+Once connected, the MCP client will have access to these tools:
+
+- `get_databases()` - Lists all configured databases
+- `list_tables(database)` - Get all tables in a database with row counts
+- `introspect_schema(database, table_pattern?)` - Get detailed schema information
+- `execute_sql(database, query, limit?)` - Execute SQL queries (read-only)
+
+The MCP server uses your existing SQLSaber database configurations, so make sure to set up your databases using `saber db add` first.
+
 ## How It Works
 
 SQLSaber uses an intelligent three-step process optimized for minimal token usage:

{sqlsaber-0.2.0 → sqlsaber-0.4.0}/README.md

@@ -15,6 +15,7 @@ Ask your questions in natural language and it will gather the right context and
 - 💬 Interactive REPL mode
 - 🎨 Beautiful formatted output with syntax highlighting
 - 🗄️ Support for PostgreSQL, SQLite, and MySQL
+- 🔌 MCP (Model Context Protocol) server support
 
 ## Installation
 
@@ -121,6 +122,43 @@ saber query "show me the distribution of customer ages"
 saber query "which products had the highest sales growth last quarter?"
 ```
 
+## MCP Server Integration
+
+SQLSaber includes an MCP (Model Context Protocol) server that allows AI agents like Claude Code to directly leverage tools available in SQLSaber.
+
+### Starting the MCP Server
+
+Run the MCP server using uvx:
+
+```bash
+uvx saber-mcp
+```
+
+### Configuring MCP Clients
+
+#### Claude Code
+
+Add SQLSaber as an MCP server in Claude Code:
+
+```bash
+claude mcp add -- uvx saber-mcp
+```
+
+#### Other MCP Clients
+
+For other MCP clients, configure them to run the command: `uvx saber-mcp`
+
+### Available MCP Tools
+
+Once connected, the MCP client will have access to these tools:
+
+- `get_databases()` - Lists all configured databases
+- `list_tables(database)` - Get all tables in a database with row counts
+- `introspect_schema(database, table_pattern?)` - Get detailed schema information
+- `execute_sql(database, query, limit?)` - Execute SQL queries (read-only)
+
+The MCP server uses your existing SQLSaber database configurations, so make sure to set up your databases using `saber db add` first.
+
 ## How It Works
 
 SQLSaber uses an intelligent three-step process optimized for minimal token usage:

{sqlsaber-0.2.0 → sqlsaber-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlsaber"
-version = "0.2.0"
+version = "0.4.0"
 description = "SQLSaber - Agentic SQL assistant like Claude Code"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -15,6 +15,8 @@ dependencies = [
     "httpx>=0.28.1",
     "aiomysql>=0.2.0",
     "aiosqlite>=0.21.0",
+    "pandas>=2.0.0",
+    "fastmcp>=2.9.0",
 ]
 
 [tool.uv]
@@ -31,3 +33,5 @@ packages = ["src/sqlsaber"]
 sqlsaber = "sqlsaber.cli.commands:main"
 saber = "sqlsaber.cli.commands:main"
 sql = "sqlsaber.cli.commands:main"
+sqlsaber-mcp = "sqlsaber.mcp.mcp:main"
+saber-mcp = "sqlsaber.mcp.mcp:main"

{sqlsaber-0.2.0 → sqlsaber-0.4.0}/src/sqlsaber/agents/anthropic.py

@@ -11,13 +11,7 @@ from sqlsaber.agents.streaming import (
     build_tool_result_block,
 )
 from sqlsaber.config.settings import Config
-from sqlsaber.database.connection import (
-    BaseDatabaseConnection,
-    MySQLConnection,
-    PostgreSQLConnection,
-    SQLiteConnection,
-)
-from sqlsaber.database.schema import SchemaManager
+from sqlsaber.database.connection import BaseDatabaseConnection
 from sqlsaber.memory.manager import MemoryManager
 from sqlsaber.models.events import StreamEvent
 from sqlsaber.models.types import ToolDefinition
@@ -36,7 +30,6 @@ class AnthropicSQLAgent(BaseSQLAgent):
 
         self.client = AsyncAnthropic(api_key=config.api_key)
         self.model = config.model_name.replace("anthropic:", "")
-        self.schema_manager = SchemaManager(db_connection)
 
         self.database_name = database_name
         self.memory_manager = MemoryManager()
@@ -94,17 +87,6 @@ class AnthropicSQLAgent(BaseSQLAgent):
         # Build system prompt with memories if available
         self.system_prompt = self._build_system_prompt()
 
-    def _get_database_type_name(self) -> str:
-        """Get the human-readable database type name."""
-        if isinstance(self.db, PostgreSQLConnection):
-            return "PostgreSQL"
-        elif isinstance(self.db, MySQLConnection):
-            return "MySQL"
-        elif isinstance(self.db, SQLiteConnection):
-            return "SQLite"
-        else:
-            return "database"  # Fallback
-
     def _build_system_prompt(self) -> str:
         """Build system prompt with optional memory context."""
         db_type = self._get_database_type_name()
@@ -152,109 +134,33 @@ Guidelines:
         self.system_prompt = self._build_system_prompt()
         return memory.id
 
-    async def introspect_schema(self, table_pattern: Optional[str] = None) -> str:
-        """Introspect database schema to understand table structures."""
-        try:
-            # Pass table_pattern to get_schema_info for efficient filtering at DB level
-            schema_info = await self.schema_manager.get_schema_info(table_pattern)
-
-            # Format the schema information
-            formatted_info = {}
-            for table_name, table_info in schema_info.items():
-                formatted_info[table_name] = {
-                    "columns": {
-                        col_name: {
-                            "type": col_info["data_type"],
-                            "nullable": col_info["nullable"],
-                            "default": col_info["default"],
-                        }
-                        for col_name, col_info in table_info["columns"].items()
-                    },
-                    "primary_keys": table_info["primary_keys"],
-                    "foreign_keys": [
-                        f"{fk['column']} -> {fk['references']['table']}.{fk['references']['column']}"
-                        for fk in table_info["foreign_keys"]
-                    ],
-                }
-
-            return json.dumps(formatted_info)
-        except Exception as e:
-            return json.dumps({"error": f"Error introspecting schema: {str(e)}"})
-
-    async def list_tables(self) -> str:
-        """List all tables in the database with basic information."""
-        try:
-            tables_info = await self.schema_manager.list_tables()
-            return json.dumps(tables_info)
-        except Exception as e:
-            return json.dumps({"error": f"Error listing tables: {str(e)}"})
-
     async def execute_sql(self, query: str, limit: Optional[int] = 100) -> str:
-        """Execute a SQL query against the database."""
-        try:
-            # Security check - only allow SELECT queries unless write is enabled
-            write_error = self._validate_write_operation(query)
-            if write_error:
-                return json.dumps(
-                    {
-                        "error": write_error,
-                    }
-                )
-
-            # Add LIMIT if not present and it's a SELECT query
-            query = self._add_limit_to_query(query, limit)
-
-            # Execute the query (wrapped in a transaction for safety)
-            results = await self.db.execute_query(query)
-
-            # Format results - but also store the actual data
-            actual_limit = limit if limit is not None else len(results)
-            self._last_results = results[:actual_limit]
-            self._last_query = query
+        """Execute a SQL query against the database with streaming support."""
+        # Call parent implementation for core functionality
+        result = await super().execute_sql(query, limit)
 
-            return json.dumps(
-                {
-                    "success": True,
-                    "row_count": len(results),
-                    "results": results[:actual_limit],  # Extra safety for limit
-                    "truncated": len(results) > actual_limit,
-                }
-            )
-
-        except Exception as e:
-            error_msg = str(e)
-
-            # Provide helpful error messages
-            suggestions = []
-            if "column" in error_msg.lower() and "does not exist" in error_msg.lower():
-                suggestions.append(
-                    "Check column names using the schema introspection tool"
-                )
-            elif "table" in error_msg.lower() and "does not exist" in error_msg.lower():
-                suggestions.append(
-                    "Check table names using the schema introspection tool"
-                )
-            elif "syntax error" in error_msg.lower():
-                suggestions.append(
-                    "Review SQL syntax, especially JOIN conditions and WHERE clauses"
+        # Parse result to extract data for streaming (AnthropicSQLAgent specific)
+        try:
+            result_data = json.loads(result)
+            if result_data.get("success") and "results" in result_data:
+                # Store results for streaming
+                actual_limit = (
+                    limit if limit is not None else len(result_data["results"])
                 )
+                self._last_results = result_data["results"][:actual_limit]
+                self._last_query = query
+        except (json.JSONDecodeError, KeyError):
+            # If we can't parse the result, just continue without storing
+            pass
 
-            return json.dumps({"error": error_msg, "suggestions": suggestions})
+        return result
 
     async def process_tool_call(
         self, tool_name: str, tool_input: Dict[str, Any]
     ) -> str:
         """Process a tool call and return the result."""
-        if tool_name == "list_tables":
-            return await self.list_tables()
-        elif tool_name == "introspect_schema":
-            return await self.introspect_schema(tool_input.get("table_pattern"))
-        elif tool_name == "execute_sql":
-            return await self.execute_sql(
-                tool_input["query"], tool_input.get("limit", 100)
-            )
-        else:
-            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+        # Use parent implementation for core tools
+        return await super().process_tool_call(tool_name, tool_input)
 
     async def _process_stream_events(
         self, stream, content_blocks: List[Dict], tool_use_blocks: List[Dict]

sqlsaber-0.4.0/src/sqlsaber/agents/base.py

@@ -0,0 +1,184 @@
+"""Abstract base class for SQL agents."""
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator, Dict, List, Optional
+
+from sqlsaber.database.connection import (
+    BaseDatabaseConnection,
+    CSVConnection,
+    MySQLConnection,
+    PostgreSQLConnection,
+    SQLiteConnection,
+)
+from sqlsaber.database.schema import SchemaManager
+from sqlsaber.models.events import StreamEvent
+
+
+class BaseSQLAgent(ABC):
+    """Abstract base class for SQL agents."""
+
+    def __init__(self, db_connection: BaseDatabaseConnection):
+        self.db = db_connection
+        self.schema_manager = SchemaManager(db_connection)
+        self.conversation_history: List[Dict[str, Any]] = []
+
+    @abstractmethod
+    async def query_stream(
+        self, user_query: str, use_history: bool = True
+    ) -> AsyncIterator[StreamEvent]:
+        """Process a user query and stream responses."""
+        pass
+
+    def clear_history(self):
+        """Clear conversation history."""
+        self.conversation_history = []
+
+    def _get_database_type_name(self) -> str:
+        """Get the human-readable database type name."""
+        if isinstance(self.db, PostgreSQLConnection):
+            return "PostgreSQL"
+        elif isinstance(self.db, MySQLConnection):
+            return "MySQL"
+        elif isinstance(self.db, SQLiteConnection):
+            return "SQLite"
+        elif isinstance(self.db, CSVConnection):
+            return "SQLite"  # we convert csv to in-memory sqlite
+        else:
+            return "database"  # Fallback
+
+    async def introspect_schema(self, table_pattern: Optional[str] = None) -> str:
+        """Introspect database schema to understand table structures."""
+        try:
+            # Pass table_pattern to get_schema_info for efficient filtering at DB level
+            schema_info = await self.schema_manager.get_schema_info(table_pattern)
+
+            # Format the schema information
+            formatted_info = {}
+            for table_name, table_info in schema_info.items():
+                formatted_info[table_name] = {
+                    "columns": {
+                        col_name: {
+                            "type": col_info["data_type"],
+                            "nullable": col_info["nullable"],
+                            "default": col_info["default"],
+                        }
+                        for col_name, col_info in table_info["columns"].items()
+                    },
+                    "primary_keys": table_info["primary_keys"],
+                    "foreign_keys": [
+                        f"{fk['column']} -> {fk['references']['table']}.{fk['references']['column']}"
+                        for fk in table_info["foreign_keys"]
+                    ],
+                }
+
+            return json.dumps(formatted_info)
+        except Exception as e:
+            return json.dumps({"error": f"Error introspecting schema: {str(e)}"})
+
+    async def list_tables(self) -> str:
+        """List all tables in the database with basic information."""
+        try:
+            tables_info = await self.schema_manager.list_tables()
+            return json.dumps(tables_info)
+        except Exception as e:
+            return json.dumps({"error": f"Error listing tables: {str(e)}"})
+
+    async def execute_sql(self, query: str, limit: Optional[int] = 100) -> str:
+        """Execute a SQL query against the database."""
+        try:
+            # Security check - only allow SELECT queries unless write is enabled
+            write_error = self._validate_write_operation(query)
+            if write_error:
+                return json.dumps(
+                    {
+                        "error": write_error,
+                    }
+                )
+
+            # Add LIMIT if not present and it's a SELECT query
+            query = self._add_limit_to_query(query, limit)
+
+            # Execute the query (wrapped in a transaction for safety)
+            results = await self.db.execute_query(query)
+
+            # Format results
+            actual_limit = limit if limit is not None else len(results)
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "row_count": len(results),
+                    "results": results[:actual_limit],  # Extra safety for limit
+                    "truncated": len(results) > actual_limit,
+                }
+            )
+
+        except Exception as e:
+            error_msg = str(e)
+
+            # Provide helpful error messages
+            suggestions = []
+            if "column" in error_msg.lower() and "does not exist" in error_msg.lower():
+                suggestions.append(
+                    "Check column names using the schema introspection tool"
+                )
+            elif "table" in error_msg.lower() and "does not exist" in error_msg.lower():
+                suggestions.append(
+                    "Check table names using the schema introspection tool"
+                )
+            elif "syntax error" in error_msg.lower():
+                suggestions.append(
+                    "Review SQL syntax, especially JOIN conditions and WHERE clauses"
+                )
+
+            return json.dumps({"error": error_msg, "suggestions": suggestions})
+
+    async def process_tool_call(
+        self, tool_name: str, tool_input: Dict[str, Any]
+    ) -> str:
+        """Process a tool call and return the result."""
+        if tool_name == "list_tables":
+            return await self.list_tables()
+        elif tool_name == "introspect_schema":
+            return await self.introspect_schema(tool_input.get("table_pattern"))
+        elif tool_name == "execute_sql":
+            return await self.execute_sql(
+                tool_input["query"], tool_input.get("limit", 100)
+            )
+        else:
+            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+    def _validate_write_operation(self, query: str) -> Optional[str]:
+        """Validate if a write operation is allowed.
+
+        Returns:
+            None if operation is allowed, error message if not allowed.
+        """
+        query_upper = query.strip().upper()
+
+        # Check for write operations
+        write_keywords = [
+            "INSERT",
+            "UPDATE",
+            "DELETE",
+            "DROP",
+            "CREATE",
+            "ALTER",
+            "TRUNCATE",
+        ]
+        is_write_query = any(query_upper.startswith(kw) for kw in write_keywords)
+
+        if is_write_query:
+            return (
+                "Write operations are not allowed. Only SELECT queries are permitted."
+            )
+
+        return None
+
+    def _add_limit_to_query(self, query: str, limit: int = 100) -> str:
+        """Add LIMIT clause to SELECT queries if not present."""
+        query_upper = query.strip().upper()
+        if query_upper.startswith("SELECT") and "LIMIT" not in query_upper:
+            return f"{query.rstrip(';')} LIMIT {limit};"
+        return query

sqlsaber-0.4.0/src/sqlsaber/agents/mcp.py

@@ -0,0 +1,21 @@
+"""Generic SQL agent implementation for MCP tools."""
+
+from typing import AsyncIterator
+from sqlsaber.agents.base import BaseSQLAgent
+from sqlsaber.database.connection import BaseDatabaseConnection
+from sqlsaber.models.events import StreamEvent
+
+
+class MCPSQLAgent(BaseSQLAgent):
+    """MCP SQL Agent for MCP tool operations without LLM-specific logic."""
+
+    def __init__(self, db_connection: BaseDatabaseConnection):
+        super().__init__(db_connection)
+
+    async def query_stream(
+        self, user_query: str, use_history: bool = True
+    ) -> AsyncIterator[StreamEvent]:
+        """Not implemented for generic agent as it's only used for tool operations."""
+        raise NotImplementedError(
+            "MCPSQLAgent does not support query streaming. Use specific agent implementations for conversation."
+        )

{sqlsaber-0.2.0 → sqlsaber-0.4.0}/src/sqlsaber/agents/streaming.py

@@ -14,13 +14,3 @@ class StreamingResponse:
 def build_tool_result_block(tool_use_id: str, content: str) -> Dict[str, Any]:
     """Build a tool result block for the conversation."""
     return {"type": "tool_result", "tool_use_id": tool_use_id, "content": content}
-
-
-def extract_sql_from_text(text: str) -> str:
-    """Extract SQL query from markdown-formatted text."""
-    if "```sql" in text:
-        sql_start = text.find("```sql") + 6
-        sql_end = text.find("```", sql_start)
-        if sql_end > sql_start:
-            return text[sql_start:sql_end].strip()
-    return ""

{sqlsaber-0.2.0 → sqlsaber-0.4.0}/src/sqlsaber/cli/commands.py

@@ -1,6 +1,7 @@
 """CLI command definitions and handlers."""
 
 import asyncio
+from pathlib import Path
 from typing import Optional
 
 import typer
@@ -62,15 +63,31 @@ def query(
     """Run a query against the database or start interactive mode."""
 
     async def run_session():
-        # Get database configuration
+        # Get database configuration or handle direct CSV file
         if database:
-            db_config = config_manager.get_database(database)
-            if not db_config:
-                console.print(
-                    f"[bold red]Error:[/bold red] Database connection '{database}' not found."
-                )
-                console.print("Use 'sqlsaber db list' to see available connections.")
-                raise typer.Exit(1)
+            # Check if this is a direct CSV file path
+            if database.endswith(".csv"):
+                csv_path = Path(database).expanduser().resolve()
+                if not csv_path.exists():
+                    console.print(
+                        f"[bold red]Error:[/bold red] CSV file '{database}' not found."
+                    )
+                    raise typer.Exit(1)
+                connection_string = f"csv:///{csv_path}"
+                db_name = csv_path.stem
+            else:
+                # Look up configured database connection
+                db_config = config_manager.get_database(database)
+                if not db_config:
+                    console.print(
+                        f"[bold red]Error:[/bold red] Database connection '{database}' not found."
+                    )
+                    console.print(
+                        "Use 'sqlsaber db list' to see available connections."
+                    )
+                    raise typer.Exit(1)
+                connection_string = db_config.to_connection_string()
+                db_name = db_config.name
         else:
             db_config = config_manager.get_default_database()
             if not db_config:
@@ -81,10 +98,11 @@ def query(
                     "Use 'sqlsaber db add <name>' to add a database connection."
                 )
                 raise typer.Exit(1)
+            connection_string = db_config.to_connection_string()
+            db_name = db_config.name
 
         # Create database connection
         try:
-            connection_string = db_config.to_connection_string()
             db_conn = DatabaseConnection(connection_string)
         except Exception as e:
             console.print(
@@ -93,7 +111,7 @@ def query(
             raise typer.Exit(1)
 
         # Create agent instance with database name for memory context
-        agent = AnthropicSQLAgent(db_conn, db_config.name)
+        agent = AnthropicSQLAgent(db_conn, db_name)
 
         try:
             if query_text: