sql-query-mcp 0.1.3__tar.gz → 0.2.0__tar.gz

{sql_query_mcp-0.1.3/sql_query_mcp.egg-info → sql_query_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-query-mcp
-Version: 0.1.3
+Version: 0.2.0
 Summary: Read-only SQL MCP server for PostgreSQL and MySQL.
 Author: Andy Wang
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp>=1.12.4
+Requires-Dist: openpyxl>=3.1
 Requires-Dist: PyMySQL>=1.1
 Requires-Dist: psycopg[binary]>=3.2
 Requires-Dist: psycopg-pool>=3.2
@@ -35,6 +36,8 @@ Dynamic: license-file
 A general-purpose MCP server that lets AI work with multiple databases within
 clear boundaries.
 
+[![sql-query-mcp MCP server](https://glama.ai/mcp/servers/andyWang1688/sql-query-mcp/badges/card.svg)](https://glama.ai/mcp/servers/andyWang1688/sql-query-mcp)
+
 ## Current database support
 
 | Database | Status | Current availability |
@@ -56,9 +59,10 @@ without exposing raw connection strings or flattening engine-specific concepts.
 
 ## What AI can do with it
 
-The current tool set focuses on database discovery and controlled query
-workflows. You can use it to help an AI assistant understand structure before
-it generates or refines SQL.
+The current tool set focuses on database discovery, controlled query workflows,
+and one narrow local file import path. You can use it to help an AI assistant
+understand structure before it generates SQL or imports a prepared CSV/XLSX file
+into an existing table.
 
 MySQL supports `explain_query`, but not `explain_query(..., analyze=True)` in
 the current implementation.
@@ -73,16 +77,18 @@ the current implementation.
 | `run_select(connection_id, sql, limit?)` | Yes | Yes | Run read-only queries |
 | `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Inspect query plans |
 | `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Fetch small table samples |
+| `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Import local CSV/XLSX files |
 
 These tools are useful for tasks such as listing namespaces, inspecting table
-definitions, reviewing indexes, sampling records, and analyzing read-only
-queries with `EXPLAIN`. For full request and response details, see
-`docs/api-reference.md` (Chinese).
+definitions, reviewing indexes, sampling records, analyzing read-only queries
+with `EXPLAIN`, and importing prepared local files. For full request and
+response details, see `docs/api-reference.md` (Chinese).
 
 ## How boundaries are constrained
 
 The product boundary is intentionally narrow today. Only PostgreSQL and MySQL
-are available today, and the current tool set is fully read-only.
+are available today. Query tools remain read-only, and the only write path is a
+controlled local CSV/XLSX import into existing tables.
 
 The service keeps those boundaries explicit in a few ways.
 
@@ -96,57 +102,69 @@ The service keeps those boundaries explicit in a few ways.
   database.
 - The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
   multi-statement input, and records audit logs for each call.
+- `import_table_file` doesn't accept raw SQL. It inserts only file columns whose
+  headers exactly match existing table columns.
 
 For MySQL, `explain_query(..., analyze=True)` is not available in the current
 implementation.
 
 ## Quick start
 
-If you want to get the server running first and explore the rest later, follow
-these steps.
+`sql-query-mcp` supports two official PyPI-based setup modes. Both are intended
+for real usage, not just local testing.
+
+1. Choose how you want your MCP client to start the server.
 
-1. Create a virtual environment and install the project.
+Use installed command mode if you want a simple local command after one
+install.
 
 ```bash
-python3.10 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
-pip install sql-query-mcp
+pipx install sql-query-mcp
 ```
 
-Install a specific release with `pip install sql-query-mcp==X.Y.Z` if you want
-to pin a version. Published release artifacts are also attached to each GitHub
-Release.
-
-2. Copy the example connection config.
+Use managed launch mode if you want the package source declared directly in
+your MCP client config.
 
 ```bash
-cp config/connections.example.json config/connections.json
+pipx run --spec sql-query-mcp sql-query-mcp
 ```
 
-3. Export your database DSNs as environment variables.
+Pin a version with `pipx install 'sql-query-mcp==X.Y.Z'` or
+`pipx run --spec 'sql-query-mcp==X.Y.Z' sql-query-mcp`. Upgrade installed
+command mode with `pipx upgrade sql-query-mcp`.
+
+2. Create a config file.
 
-These example names match the copied `config/connections.example.json` file.
+The server configuration should live outside the repository so the same file
+works with either startup mode.
 
 ```bash
-export PG_CONN_CRM_PROD_MUQIAO_RO='postgresql://user:password@host:5432/dbname'
-export MYSQL_CONN_CRM_PROD_MUQIAO_RO='mysql://user:password@host:3306/crm'
-export SQL_QUERY_MCP_CONFIG='/absolute/path/to/sql-query-mcp/config/connections.json'
+mkdir -p ~/.config/sql-query-mcp
 ```
 
-4. Register the server in your MCP client.
+Then save the example JSON later in this section as
+`~/.config/sql-query-mcp/connections.json`.
+
+3. Register the server in your MCP client.
 
 - Codex: `docs/codex-setup.md` (Chinese)
 - OpenCode: `docs/opencode-setup.md` (Chinese)
 
+Installed command mode means your client runs `sql-query-mcp` directly.
+Managed launch mode means your client starts the server through `pipx run`.
+
+In both modes, put `SQL_QUERY_MCP_CONFIG` and your real database DSNs in the
+MCP client's environment block instead of exporting them in your shell.
+
 The console entry point is `sql-query-mcp`, which maps to
 `sql_query_mcp.app:main`.
 
 The PyPI install name is `sql-query-mcp`, and the Python package import path is
 `sql_query_mcp`.
 
-The default config path is `config/connections.json`. If you need a different
-location, set `SQL_QUERY_MCP_CONFIG`.
+For `pipx install` and `pipx run`, set `SQL_QUERY_MCP_CONFIG` explicitly to
+your config file path. The default `config/connections.json` path is mainly for
+source checkouts and local development.
 
 The example config looks like this.
 
@@ -159,24 +177,24 @@ The example config looks like this.
   },
   "connections": [
     {
-      "connection_id": "crm_prod_muqiao_ro",
+      "connection_id": "crm_prod_main_ro",
       "engine": "postgres",
-      "label": "CRM PostgreSQL production / Muqiao / read-only",
+      "label": "CRM PostgreSQL production / Main / read-only",
       "env": "prod",
-      "tenant": "muqiao",
+      "tenant": "main",
       "role": "ro",
-      "dsn_env": "PG_CONN_CRM_PROD_MUQIAO_RO",
+      "dsn_env": "PG_CONN_CRM_PROD_MAIN_RO",
       "enabled": true,
       "default_schema": "public"
     },
     {
-      "connection_id": "crm_mysql_prod_muqiao_ro",
+      "connection_id": "crm_mysql_prod_main_ro",
       "engine": "mysql",
-      "label": "CRM MySQL production / Muqiao / read-only",
+      "label": "CRM MySQL production / Main / read-only",
       "env": "prod",
-      "tenant": "muqiao",
+      "tenant": "main",
       "role": "ro",
-      "dsn_env": "MYSQL_CONN_CRM_PROD_MUQIAO_RO",
+      "dsn_env": "MYSQL_CONN_CRM_PROD_MAIN_RO",
       "enabled": true,
       "default_database": "crm"
     }

{sql_query_mcp-0.1.3 → sql_query_mcp-0.2.0}/README.md

@@ -5,6 +5,8 @@
 A general-purpose MCP server that lets AI work with multiple databases within
 clear boundaries.
 
+[![sql-query-mcp MCP server](https://glama.ai/mcp/servers/andyWang1688/sql-query-mcp/badges/card.svg)](https://glama.ai/mcp/servers/andyWang1688/sql-query-mcp)
+
 ## Current database support
 
 | Database | Status | Current availability |
@@ -26,9 +28,10 @@ without exposing raw connection strings or flattening engine-specific concepts.
 
 ## What AI can do with it
 
-The current tool set focuses on database discovery and controlled query
-workflows. You can use it to help an AI assistant understand structure before
-it generates or refines SQL.
+The current tool set focuses on database discovery, controlled query workflows,
+and one narrow local file import path. You can use it to help an AI assistant
+understand structure before it generates SQL or imports a prepared CSV/XLSX file
+into an existing table.
 
 MySQL supports `explain_query`, but not `explain_query(..., analyze=True)` in
 the current implementation.
@@ -43,16 +46,18 @@ the current implementation.
 | `run_select(connection_id, sql, limit?)` | Yes | Yes | Run read-only queries |
 | `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Inspect query plans |
 | `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Fetch small table samples |
+| `import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?)` | Yes | Yes | Import local CSV/XLSX files |
 
 These tools are useful for tasks such as listing namespaces, inspecting table
-definitions, reviewing indexes, sampling records, and analyzing read-only
-queries with `EXPLAIN`. For full request and response details, see
-`docs/api-reference.md` (Chinese).
+definitions, reviewing indexes, sampling records, analyzing read-only queries
+with `EXPLAIN`, and importing prepared local files. For full request and
+response details, see `docs/api-reference.md` (Chinese).
 
 ## How boundaries are constrained
 
 The product boundary is intentionally narrow today. Only PostgreSQL and MySQL
-are available today, and the current tool set is fully read-only.
+are available today. Query tools remain read-only, and the only write path is a
+controlled local CSV/XLSX import into existing tables.
 
 The service keeps those boundaries explicit in a few ways.
 
@@ -66,57 +71,69 @@ The service keeps those boundaries explicit in a few ways.
   database.
 - The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
   multi-statement input, and records audit logs for each call.
+- `import_table_file` doesn't accept raw SQL. It inserts only file columns whose
+  headers exactly match existing table columns.
 
 For MySQL, `explain_query(..., analyze=True)` is not available in the current
 implementation.
 
 ## Quick start
 
-If you want to get the server running first and explore the rest later, follow
-these steps.
+`sql-query-mcp` supports two official PyPI-based setup modes. Both are intended
+for real usage, not just local testing.
+
+1. Choose how you want your MCP client to start the server.
 
-1. Create a virtual environment and install the project.
+Use installed command mode if you want a simple local command after one
+install.
 
 ```bash
-python3.10 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
-pip install sql-query-mcp
+pipx install sql-query-mcp
 ```
 
-Install a specific release with `pip install sql-query-mcp==X.Y.Z` if you want
-to pin a version. Published release artifacts are also attached to each GitHub
-Release.
-
-2. Copy the example connection config.
+Use managed launch mode if you want the package source declared directly in
+your MCP client config.
 
 ```bash
-cp config/connections.example.json config/connections.json
+pipx run --spec sql-query-mcp sql-query-mcp
 ```
 
-3. Export your database DSNs as environment variables.
+Pin a version with `pipx install 'sql-query-mcp==X.Y.Z'` or
+`pipx run --spec 'sql-query-mcp==X.Y.Z' sql-query-mcp`. Upgrade installed
+command mode with `pipx upgrade sql-query-mcp`.
+
+2. Create a config file.
 
-These example names match the copied `config/connections.example.json` file.
+The server configuration should live outside the repository so the same file
+works with either startup mode.
 
 ```bash
-export PG_CONN_CRM_PROD_MUQIAO_RO='postgresql://user:password@host:5432/dbname'
-export MYSQL_CONN_CRM_PROD_MUQIAO_RO='mysql://user:password@host:3306/crm'
-export SQL_QUERY_MCP_CONFIG='/absolute/path/to/sql-query-mcp/config/connections.json'
+mkdir -p ~/.config/sql-query-mcp
 ```
 
-4. Register the server in your MCP client.
+Then save the example JSON later in this section as
+`~/.config/sql-query-mcp/connections.json`.
+
+3. Register the server in your MCP client.
 
 - Codex: `docs/codex-setup.md` (Chinese)
 - OpenCode: `docs/opencode-setup.md` (Chinese)
 
+Installed command mode means your client runs `sql-query-mcp` directly.
+Managed launch mode means your client starts the server through `pipx run`.
+
+In both modes, put `SQL_QUERY_MCP_CONFIG` and your real database DSNs in the
+MCP client's environment block instead of exporting them in your shell.
+
 The console entry point is `sql-query-mcp`, which maps to
 `sql_query_mcp.app:main`.
 
 The PyPI install name is `sql-query-mcp`, and the Python package import path is
 `sql_query_mcp`.
 
-The default config path is `config/connections.json`. If you need a different
-location, set `SQL_QUERY_MCP_CONFIG`.
+For `pipx install` and `pipx run`, set `SQL_QUERY_MCP_CONFIG` explicitly to
+your config file path. The default `config/connections.json` path is mainly for
+source checkouts and local development.
 
 The example config looks like this.
 
@@ -129,24 +146,24 @@ The example config looks like this.
   },
   "connections": [
     {
-      "connection_id": "crm_prod_muqiao_ro",
+      "connection_id": "crm_prod_main_ro",
       "engine": "postgres",
-      "label": "CRM PostgreSQL production / Muqiao / read-only",
+      "label": "CRM PostgreSQL production / Main / read-only",
       "env": "prod",
-      "tenant": "muqiao",
+      "tenant": "main",
       "role": "ro",
-      "dsn_env": "PG_CONN_CRM_PROD_MUQIAO_RO",
+      "dsn_env": "PG_CONN_CRM_PROD_MAIN_RO",
       "enabled": true,
       "default_schema": "public"
     },
     {
-      "connection_id": "crm_mysql_prod_muqiao_ro",
+      "connection_id": "crm_mysql_prod_main_ro",
       "engine": "mysql",
-      "label": "CRM MySQL production / Muqiao / read-only",
+      "label": "CRM MySQL production / Main / read-only",
       "env": "prod",
-      "tenant": "muqiao",
+      "tenant": "main",
       "role": "ro",
-      "dsn_env": "MYSQL_CONN_CRM_PROD_MUQIAO_RO",
+      "dsn_env": "MYSQL_CONN_CRM_PROD_MAIN_RO",
       "enabled": true,
       "default_database": "crm"
     }

{sql_query_mcp-0.1.3 → sql_query_mcp-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sql-query-mcp"
-version = "0.1.3"
+version = "0.2.0"
 description = "Read-only SQL MCP server for PostgreSQL and MySQL."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ classifiers = [
 ]
 dependencies = [
   "mcp>=1.12.4",
+  "openpyxl>=3.1",
   "PyMySQL>=1.1",
   "psycopg[binary]>=3.2",
   "psycopg-pool>=3.2",

{sql_query_mcp-0.1.3 → sql_query_mcp-0.2.0}/sql_query_mcp/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{sql_query_mcp-0.1.3 → sql_query_mcp-0.2.0}/sql_query_mcp/adapters/mysql.py

@@ -115,6 +115,14 @@ class MySQLAdapter:
             f"{self._quote_identifier(table_name)} LIMIT {int(sentinel_limit)}"
         )
 
+    def build_insert_query(self, database: str, table_name: str, columns: List[str]) -> str:
+        quoted_columns = ", ".join(self._quote_identifier(column) for column in columns)
+        placeholders = ", ".join(["%s"] * len(columns))
+        return (
+            f"INSERT INTO {self._quote_identifier(database)}."
+            f"{self._quote_identifier(table_name)} ({quoted_columns}) VALUES ({placeholders})"
+        )
+
     def build_explain_query(self, sql_text: str, analyze: bool = False) -> str:
         if analyze:
             raise SecurityError("MySQL 首版不支持 analyze=True。")

{sql_query_mcp-0.1.3 → sql_query_mcp-0.2.0}/sql_query_mcp/adapters/postgres.py

@@ -155,6 +155,16 @@ class PostgresAdapter:
             sql.Literal(sentinel_limit),
         )
 
+    def build_insert_query(self, schema: str, table_name: str, columns: List[str]):
+        if sql is None:
+            raise ConfigurationError("缺少 psycopg 依赖，请先安装项目依赖。")
+        return sql.SQL("INSERT INTO {}.{} ({}) VALUES ({})").format(
+            sql.Identifier(schema),
+            sql.Identifier(table_name),
+            sql.SQL(", ").join(sql.Identifier(column) for column in columns),
+            sql.SQL(", ").join(sql.Placeholder() for _ in columns),
+        )
+
     def build_explain_query(self, sql_text: str, analyze: bool = False) -> str:
         return f"EXPLAIN (FORMAT JSON, ANALYZE {'TRUE' if analyze else 'FALSE'}) {sql_text}"
 

{sql_query_mcp-0.1.3 → sql_query_mcp-0.2.0}/sql_query_mcp/app.py

@@ -10,6 +10,7 @@ from .audit import AuditLogger
 from .config import load_config
 from .errors import SqlQueryMCPError
 from .executor import QueryExecutor
+from .importer import TableFileImporter
 from .introspection import MetadataService
 from .registry import ConnectionRegistry
 
@@ -20,6 +21,7 @@ def create_app() -> FastMCP:
     audit_logger = AuditLogger(app_config.settings.audit_log_path)
     metadata = MetadataService(registry, app_config.settings, audit_logger)
     executor = QueryExecutor(registry, app_config.settings, audit_logger)
+    importer = TableFileImporter(registry, app_config.settings, audit_logger)
 
     mcp = FastMCP("sql-query-mcp", json_response=True)
 
@@ -86,6 +88,28 @@ def create_app() -> FastMCP:
 
         return _run_tool(lambda: executor.get_table_sample(connection_id, table_name, schema, database, limit))
 
+    @mcp.tool()
+    def import_table_file(
+        connection_id: str,
+        table_name: str,
+        file_path: str,
+        schema: Optional[str] = None,
+        database: Optional[str] = None,
+        sheet_name: Optional[str] = None,
+    ) -> dict:
+        """Import a local CSV or XLSX file into an existing table."""
+
+        return _run_tool(
+            lambda: importer.import_table_file(
+                connection_id,
+                table_name,
+                file_path,
+                schema,
+                database,
+                sheet_name,
+            )
+        )
+
     return mcp