sqlseed 0.1.16__tar.gz → 0.1.18__tar.gz

{sqlseed-0.1.16 → sqlseed-0.1.18}/CHANGELOG.md

@@ -7,6 +7,27 @@ All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.1.17]
+
+### Added
+
+- `RichProgressBackend` now accepts `ascii_only` parameter: when `True`, uses `"line"` spinner (`|/-\`) and omits `BarColumn`, avoiding `UnicodeEncodeError` on GBK/Big5/CP936 console encodings
+- `_can_render_unicode()` cached helper probes whether stdout can encode Rich's Braille/block-element characters (U+280B, U+2588, U+2591)
+- `create_progress()` auto-falls back to `ascii_only=True` when `_can_render_unicode()` returns `False`, with a debug log message
+- `DataOrchestrator` adds SQL operation methods: `execute(sql, params)`, `query(sql, params)`, `fetch_one(sql, params)`, `fetch_all(sql, params)` for direct database interaction
+- `BaseSQLiteAdapter._execute(sql, params)` method for parameterized SQL execution
+- `DatabaseAdapter` protocol updated with `_execute` method signature
+
+### Changed
+
+- `RichProgressBackend` refresh rate set to 1 Hz (was default 10 Hz) to reduce terminal flicker
+- Test suite: `TestRichProgressBackend` and `TestRichProgressBackendAsciiOnly` merged via `pytest.mark.parametrize` to eliminate code duplication
+
+### Fixed
+
+- Windows compatibility: GBK/GB2312/Big5/CP936 encoded terminals no longer crash with `UnicodeEncodeError` when displaying Rich progress bars
+- `.gitignore`: removed `*汇总.md` pattern (no longer needed)
+
 ## [v0.1.16]
 
 ### Added

{sqlseed-0.1.16 → sqlseed-0.1.18}/CHANGELOG.zh-CN.md

@@ -7,6 +7,27 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，
 本项目遵循[语义化版本](https://semver.org/spec/v2.0.0.html)。
 
+## [v0.1.17]
+
+### 新增
+
+- `RichProgressBackend` 新增 `ascii_only` 参数：启用时使用 `"line"` 旋转符（`|/-\`）并省略 `BarColumn`，避免 GBK/Big5/CP936 编码终端的 `UnicodeEncodeError`
+- `_can_render_unicode()` 缓存辅助函数，检测 stdout 是否能编码 Rich 的盲文/方块字符（U+280B, U+2588, U+2591）
+- `create_progress()` 在 `_can_render_unicode()` 返回 `False` 时自动回退到 `ascii_only=True`，并输出 debug 日志
+- `DataOrchestrator` 新增 SQL 操作方法：`execute(sql, params)`、`query(sql, params)`、`fetch_one(sql, params)`、`fetch_all(sql, params)` 用于直接数据库交互
+- `BaseSQLiteAdapter._execute(sql, params)` 参数化 SQL 执行方法
+- `DatabaseAdapter` 协议新增 `_execute` 方法签名
+
+### 变更
+
+- `RichProgressBackend` 刷新频率设为 1 Hz（原默认 10 Hz），减少终端闪烁
+- 测试套件：`TestRichProgressBackend` 和 `TestRichProgressBackendAsciiOnly` 通过 `pytest.mark.parametrize` 合并，消除代码重复
+
+### 修复
+
+- Windows 兼容性：GBK/GB2312/Big5/CP936 编码终端不再因 Rich 进度条的 Unicode 字符而崩溃
+- `.gitignore`：移除 `*汇总.md` 规则（不再需要）
+
 ## [v0.1.16]
 
 ### 新增

{sqlseed-0.1.16 → sqlseed-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlseed
-Version: 0.1.16
+Version: 0.1.18
 Summary: Declarative SQLite test data generation toolkit
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Documentation, https://github.com/sunbos/sqlseed#readme

sqlseed-0.1.18/plugins/mcp-server-sqlseed/README.md

@@ -0,0 +1,77 @@
+# mcp-server-sqlseed
+
+**[English](README.md)** | [中文](README.zh-CN.md)
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [sqlseed](https://github.com/sunbos/sqlseed) — enabling AI assistants to inspect schemas, generate configs, and fill SQLite databases.
+
+## Installation
+
+```bash
+# Basic
+pip install mcp-server-sqlseed
+
+# With AI support (includes sqlseed-ai)
+pip install mcp-server-sqlseed[ai]
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:
+
+```json
+{
+  "mcpServers": {
+    "sqlseed": {
+      "command": "mcp-server-sqlseed"
+    }
+  }
+}
+```
+
+### Cursor / Other MCP Clients
+
+Use command: `mcp-server-sqlseed`
+
+## MCP Tools
+
+| Tool | Description |
+|:-----|:------------|
+| `sqlseed_inspect_schema` | Inspect database schema: columns, foreign keys, indexes, sample data, schema_hash. Accepts optional `table_name` (all tables if omitted). |
+| `sqlseed_generate_yaml` | AI-driven YAML config generation with self-correction. Requires `sqlseed-ai` plugin and API key. Supports `api_key`/`base_url`/`model` parameter overrides. |
+| `sqlseed_execute_fill` | Execute data generation. Accepts optional `yaml_config` string, `count`, and `enrich` flag. Max YAML config size: 256KB. |
+
+### MCP Resource
+
+| Resource | Description |
+|:---------|:------------|
+| `sqlseed://schema/{db_path}/{table_name}` | Read-only JSON schema for a specific table |
+
+## Example Usage
+
+After configuring your MCP client, you can prompt:
+
+> "Inspect the schema of `app.db`, generate a YAML config for the `users` table, then fill 1000 rows."
+
+The AI assistant will call:
+1. `sqlseed_inspect_schema` → get table structure
+2. `sqlseed_generate_yaml` → generate YAML config (if sqlseed-ai is installed)
+3. `sqlseed_execute_fill` → fill data
+
+## AI Integration
+
+When `sqlseed-ai` is installed and an API key is configured (`SQLSEED_AI_API_KEY` or `OPENAI_API_KEY`), the `sqlseed_generate_yaml` tool uses LLM-driven analysis with self-correction. Without the AI plugin, the tool returns a fallback message.
+
+## Requirements
+
+- Python >= 3.10
+- `sqlseed >= 0.1.0`
+- `mcp >= 1.0`
+
+Optional:
+- `sqlseed-ai` (for `sqlseed_generate_yaml` tool)
+
+## License
+
+AGPL-3.0-or-later

sqlseed-0.1.18/plugins/mcp-server-sqlseed/README.zh-CN.md

@@ -0,0 +1,77 @@
+# mcp-server-sqlseed
+
+[English](README.md) | **[中文](README.zh-CN.md)**
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，用于 [sqlseed](https://github.com/sunbos/sqlseed) — 让 AI 助手直接检查 Schema、生成配置和填充 SQLite 数据库。
+
+## 安装
+
+```bash
+# 基础安装
+pip install mcp-server-sqlseed
+
+# 含 AI 支持（包含 sqlseed-ai）
+pip install mcp-server-sqlseed[ai]
+```
+
+## 配置
+
+### Claude Desktop
+
+添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
+
+```json
+{
+  "mcpServers": {
+    "sqlseed": {
+      "command": "mcp-server-sqlseed"
+    }
+  }
+}
+```
+
+### Cursor / 其他 MCP 客户端
+
+使用命令：`mcp-server-sqlseed`
+
+## MCP Tools
+
+| Tool | 说明 |
+|:-----|:-----|
+| `sqlseed_inspect_schema` | 检查数据库 Schema：列、外键、索引、样本数据、schema_hash。可选 `table_name`（省略则返回所有表）。 |
+| `sqlseed_generate_yaml` | AI 驱动的 YAML 配置生成，含自纠正。需要 `sqlseed-ai` 插件和 API Key。支持 `api_key`/`base_url`/`model` 参数覆盖。 |
+| `sqlseed_execute_fill` | 执行数据生成。可选 `yaml_config` 字符串、`count` 和 `enrich` 标志。YAML 配置最大 256KB。 |
+
+### MCP Resource
+
+| Resource | 说明 |
+|:---------|:-----|
+| `sqlseed://schema/{db_path}/{table_name}` | 指定表的只读 JSON Schema |
+
+## 使用示例
+
+配置 MCP 客户端后，可以这样提示：
+
+> "检查 `app.db` 的 Schema，为 `users` 表生成 YAML 配置，然后填充 1000 行数据。"
+
+AI 助手会依次调用：
+1. `sqlseed_inspect_schema` → 获取表结构
+2. `sqlseed_generate_yaml` → 生成 YAML 配置（需安装 sqlseed-ai）
+3. `sqlseed_execute_fill` → 填充数据
+
+## AI 集成
+
+当安装了 `sqlseed-ai` 并配置了 API Key（`SQLSEED_AI_API_KEY` 或 `OPENAI_API_KEY`）时，`sqlseed_generate_yaml` 工具使用 LLM 驱动的分析和自纠正。未安装 AI 插件时，该工具返回回退消息。
+
+## 依赖
+
+- Python >= 3.10
+- `sqlseed >= 0.1.0`
+- `mcp >= 1.0`
+
+可选：
+- `sqlseed-ai`（用于 `sqlseed_generate_yaml` 工具）
+
+## 许可证
+
+AGPL-3.0-or-later

sqlseed-0.1.18/plugins/mcp-server-sqlseed/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-server-sqlseed"
+dynamic = ["version"]
+requires-python = ">=3.10"
+description = "MCP server for sqlseed - AI-powered SQLite test data generation"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+authors = [
+    {name = "SunBo", email = "1443584939@qq.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "sqlseed>=0.1.0,<2",
+    "mcp>=1.0,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/sunbos/sqlseed"
+Repository = "https://github.com/sunbos/sqlseed/tree/main/plugins/mcp-server-sqlseed"
+
+[project.optional-dependencies]
+ai = ["sqlseed-ai"]
+
+[project.scripts]
+mcp-server-sqlseed = "mcp_server_sqlseed:main"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"
+
+[tool.hatch.version.raw-options]
+root = "../.."
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_server_sqlseed"]

sqlseed-0.1.18/plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from mcp_server_sqlseed.server import mcp
+
+
+def main() -> None:
+    mcp.run()

sqlseed-0.1.18/plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from mcp_server_sqlseed import main
+
+if __name__ == "__main__":
+    main()

sqlseed-0.1.18/plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/config.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class MCPServerConfig(BaseModel):
+    db_path: str | None = None
+    host: str = "localhost"
+    port: int = 8000

sqlseed-0.1.18/plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/server.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from mcp.server.fastmcp import FastMCP
+
+from sqlseed.config.models import GeneratorConfig
+from sqlseed.core.orchestrator import DataOrchestrator
+
+try:
+    from sqlseed_ai.analyzer import SchemaAnalyzer
+    from sqlseed_ai.config import AIConfig
+    from sqlseed_ai.refiner import AiConfigRefiner, AISuggestionFailedError
+
+    _AI_AVAILABLE = True
+except ImportError:
+    _AI_AVAILABLE = False
+
+mcp = FastMCP("sqlseed")
+
+_MAX_YAML_CONFIG_SIZE = 256 * 1024
+
+
+def _validate_db_path(db_path: str) -> str:
+    resolved = Path(db_path).resolve()
+    valid_exts = (".db", ".sqlite", ".sqlite3")
+    if not str(resolved).endswith(valid_exts):
+        raise ValueError(f"Invalid database path: {db_path}. Must be a .db, .sqlite, or .sqlite3 file.")
+    if not resolved.exists():
+        raise ValueError(f"Database file not found: {db_path}")
+    return str(resolved)
+
+
+def _validate_table_name(table_name: str, allowed_tables: list[str]) -> str:
+    if table_name not in allowed_tables:
+        raise ValueError(f"Table '{table_name}' does not exist in the database. Available: {allowed_tables}")
+    return table_name
+
+
+def _serialize_schema_context(ctx: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "table_name": ctx["table_name"],
+        "columns": [
+            {
+                "name": c.name,
+                "type": c.type,
+                "nullable": c.nullable,
+                "default": c.default,
+                "is_primary_key": c.is_primary_key,
+                "is_autoincrement": c.is_autoincrement,
+            }
+            for c in ctx["columns"]
+        ],
+        "foreign_keys": [
+            {"column": fk.column, "ref_table": fk.ref_table, "ref_column": fk.ref_column} for fk in ctx["foreign_keys"]
+        ],
+        "indexes": ctx["indexes"],
+        "sample_data": ctx["sample_data"],
+        "all_table_names": ctx["all_table_names"],
+    }
+
+
+def _compute_schema_hash(schema_ctx: dict[str, Any]) -> str:
+    hash_input = json.dumps(
+        {
+            "columns": [{"name": c.name, "type": c.type, "nullable": c.nullable} for c in schema_ctx["columns"]],
+            "foreign_keys": [{"column": fk.column, "ref_table": fk.ref_table} for fk in schema_ctx["foreign_keys"]],
+        },
+        sort_keys=True,
+    )
+    return hashlib.sha256(hash_input.encode()).hexdigest()[:16]
+
+
+@mcp.resource("sqlseed://schema/{db_path}/{table_name}")
+def get_schema_resource(db_path: str, table_name: str) -> str:
+    db_path = _validate_db_path(db_path)
+    with DataOrchestrator(db_path) as orch:
+        _validate_table_name(table_name, orch.get_table_names())
+        ctx = orch.get_schema_context(table_name)
+        serializable_ctx = _serialize_schema_context(ctx)
+        return json.dumps(serializable_ctx, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+def sqlseed_inspect_schema(db_path: str, table_name: str | None = None) -> dict[str, Any]:
+    """Inspect database schema. Returns column info, foreign keys, indexes,
+    sample data, and schema_hash for specified table or all tables."""
+    db_path = _validate_db_path(db_path)
+    with DataOrchestrator(db_path) as orch:
+        if table_name:
+            _validate_table_name(table_name, orch.get_table_names())
+        tables = [table_name] if table_name else orch.get_table_names()
+        result: dict[str, Any] = {}
+        for tbl in tables:
+            ctx = orch.get_schema_context(tbl)
+            result[tbl] = _serialize_schema_context(ctx)
+            result[tbl]["schema_hash"] = _compute_schema_hash(ctx)
+        return result
+
+
+@mcp.tool()
+def sqlseed_generate_yaml(
+    db_path: str,
+    table_name: str,
+    max_retries: int = 3,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str | None = None,
+) -> str:
+    """Generate YAML config for a table using AI analysis with self-correction.
+    Returns YAML string for human review. Requires sqlseed-ai plugin and API key."""
+    if not _AI_AVAILABLE:
+        return "# No AI suggestions available. Ensure sqlseed-ai plugin is installed and API key is configured."
+
+    db_path = _validate_db_path(db_path)
+    with DataOrchestrator(db_path) as orch:
+        _validate_table_name(table_name, orch.get_table_names())
+
+    ai_config = AIConfig.from_env().apply_overrides(api_key=api_key, base_url=base_url, model=model)
+
+    ai_config.resolve_model()
+
+    analyzer = SchemaAnalyzer(config=ai_config)
+    refiner = AiConfigRefiner(analyzer, db_path)
+
+    try:
+        result = refiner.generate_and_refine(
+            table_name=table_name,
+            max_retries=max_retries,
+        )
+    except AISuggestionFailedError as e:
+        return f"# AI suggestion failed: {e}"
+    except (ValueError, RuntimeError, OSError) as e:
+        return f"# Error: {e}"
+
+    if result:
+        output = {"db_path": db_path, "provider": "mimesis", "locale": "en_US", "tables": [result]}
+        return str(yaml.dump(output, allow_unicode=True, sort_keys=False, default_flow_style=False))
+    return "# No AI suggestions available. Ensure sqlseed-ai plugin is installed and API key is configured."
+
+
+@mcp.tool()
+def sqlseed_execute_fill(
+    db_path: str,
+    table_name: str,
+    count: int = 1000,
+    yaml_config: str | None = None,
+    enrich: bool = False,
+) -> dict[str, Any]:
+    """Execute data generation for a table. Optionally provide YAML config string for column rules."""
+    db_path = _validate_db_path(db_path)
+
+    if yaml_config is not None and len(yaml_config) > _MAX_YAML_CONFIG_SIZE:
+        raise ValueError(f"yaml_config exceeds maximum allowed size of {_MAX_YAML_CONFIG_SIZE} bytes")
+
+    with DataOrchestrator(db_path) as orch:
+        _validate_table_name(table_name, orch.get_table_names())
+        column_configs = None
+        clear_before = False
+        seed = None
+
+        if yaml_config:
+            data = yaml.safe_load(yaml_config)
+            config = GeneratorConfig(**data)
+            for t in config.tables:
+                if t.name == table_name:
+                    column_configs = t.columns
+                    clear_before = t.clear_before
+                    seed = t.seed
+                    break
+
+        result = orch.fill_table(
+            table_name=table_name,
+            count=count,
+            column_configs=column_configs,
+            clear_before=clear_before,
+            seed=seed,
+            enrich=enrich,
+        )
+
+        return {
+            "table_name": result.table_name,
+            "count": result.count,
+            "elapsed": result.elapsed,
+            "errors": result.errors,
+        }