docs: align pipx setup and config examples

README-zh.md

@@ -64,37 +64,52 @@ MySQL 在当前实现中支持 `explain_query`，但不支持
 
 ## 快速开始
 
-如果你想先把服务跑起来，之后再继续了解其余部分，可以按以下步骤进行。
+`sql-query-mcp` 提供两种官方支持的 PyPI 接入方式。两种都适合正式使用，不
+只是本地试跑。
 
-1. 创建虚拟环境并安装项目。
+1. 先决定让 MCP 客户端如何启动服务。
+
+如果你希望先安装一次，之后在客户端里直接调用命令，可以使用安装命令模式。
 
 ```bash
-python3.10 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
-pip install -e .
+pipx install sql-query-mcp
 ```
 
-2. 复制示例连接配置。
+如果你希望把包来源直接写进 MCP 配置，让客户端通过 `pipx` 启动服务，可以使
+用托管启动模式。
 
 ```bash
-cp config/connections.example.json config/connections.json
+pipx run --spec sql-query-mcp sql-query-mcp
 ```
 
-3. 设置用于保存数据库 DSN 的环境变量。
+如果你想固定版本，可使用 `pipx install 'sql-query-mcp==X.Y.Z'`，或者使用
+`pipx run --spec 'sql-query-mcp==X.Y.Z' sql-query-mcp`。已安装版本可通过
+`pipx upgrade sql-query-mcp` 升级。
+
+2. 创建配置文件。
+
+无论你选择哪种启动方式，都建议把服务配置文件放在仓库之外，便于统一维护。
 
 ```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'
+mkdir -p ~/.config/sql-query-mcp
 ```
 
-4. 在你的 MCP 客户端中注册这个服务。
+然后把本节后面的示例 JSON 保存为
+`~/.config/sql-query-mcp/connections.json`。
+
+3. 在你的 MCP 客户端中注册这个服务。
 
 - Codex: `docs/codex-setup.md`
 - OpenCode: `docs/opencode-setup.md`
 
-默认配置路径是 `config/connections.json`。如果你需要使用其他位置，请设置
-`SQL_QUERY_MCP_CONFIG`。
+安装命令模式表示客户端直接运行 `sql-query-mcp`。托管启动模式表示客户端通
+过 `pipx run` 启动服务。
+
+无论使用哪种方式，都建议把 `SQL_QUERY_MCP_CONFIG` 和真实数据库 DSN 放在
+MCP 客户端的 `env` 或 `environment` 配置里，而不是单独在 shell 中导出。
+
+对于 `pipx install` 和 `pipx run`，建议显式设置 `SQL_QUERY_MCP_CONFIG`。
+默认的 `config/connections.json` 更适合源码 checkout 和本地开发场景。
 
 示例配置如下。
 
@@ -107,24 +122,24 @@ export MYSQL_CONN_CRM_PROD_MUQIAO_RO='mysql://user:password@host:3306/crm'
   },
   "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"
     }

README.md

@@ -72,51 +72,61 @@ 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. Create a virtual environment and install the project.
+1. Choose how you want your MCP client to start the server.
+
+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`.
 
-These example names match the copied `config/connections.example.json` file.
+2. Create a config 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 +139,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"
     }

config/connections.example.json

@@ -6,24 +6,24 @@
   },
   "connections": [
     {
-      "connection_id": "crm_prod_muqiao_ro",
+      "connection_id": "crm_prod_main_ro",
       "engine": "postgres",
-      "label": "CRM PostgreSQL 生产库 / 穆桥 / 只读",
+      "label": "CRM PostgreSQL 生产库 / Main / 只读",
       "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 生产库 / 穆桥 / 只读",
+      "label": "CRM MySQL 生产库 / Main / 只读",
       "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"
     }