wtinydb-mcp 0.1.0__py3-none-any.whl

wtinydb_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""wtinydb-mcp package initialization."""
+
+__version__ = "0.1.0"

wtinydb_mcp/catalog.py

@@ -0,0 +1,59 @@
+"""WTinyDB Architectural Patterns Catalog."""
+
+from typing import Dict, List, Optional
+
+
+class PatternsCatalog:
+    """Catalog of production-ready patterns for WTinyDB document database architectures."""
+
+    PATTERNS = [
+        {
+            "id": "pydantic-crud",
+            "name": "Pydantic Document Repository",
+            "feature": "CRUD & Models",
+            "module": "wtinydb.core.database",
+            "description": "Standard repository pattern wrapping WTinyDB with Pydantic model validation.",
+            "origin": "wisrovi SUITE",
+        },
+        {
+            "id": "async-wtinydb",
+            "name": "Async Document Operations",
+            "feature": "Async / FastAPI Integration",
+            "module": "wtinydb.core.async_db",
+            "description": "Non-blocking ThreadPoolExecutor wrapper for high-throughput async APIs.",
+            "origin": "wisrovi SUITE",
+        },
+        {
+            "id": "fluent-query",
+            "name": "Fluent Query Builder",
+            "feature": "Queries & Filtering",
+            "module": "wtinydb.core.query",
+            "description": "Chainable query builder (Q) for NoSQL field matching, regex search, and list filters.",
+            "origin": "wisrovi SUITE",
+        },
+        {
+            "id": "soft-delete-audit",
+            "name": "Soft Delete & Audit Trailing",
+            "feature": "Audit & Lifecycle",
+            "module": "wtinydb.models",
+            "description": "Mixins for automatic created_at, updated_at timestamps and logical deletion.",
+            "origin": "wisrovi SUITE",
+        },
+        {
+            "id": "n-level-nested-crud",
+            "name": "N-Level Nested JSON CRUD",
+            "feature": "Nested Documents & Path Querying",
+            "module": "wtinydb.core.database",
+            "description": "Single-responsibility modular CRUD for N-level deep nested JSON objects with dotted path matching.",
+            "origin": "wisrovi SUITE",
+        },
+    ]
+
+    def search(self, query: str) -> List[Dict[str, str]]:
+        """Search patterns matching query string across name, feature, or description."""
+        q = query.lower()
+        results = []
+        for p in self.PATTERNS:
+            if q in p["name"].lower() or q in p["feature"].lower() or q in p["description"].lower():
+                results.append(p)
+        return results

wtinydb_mcp/server.py

@@ -0,0 +1,245 @@
+"""wtinydb-mcp: Model Context Protocol server for WTinyDB architecting and code generation."""
+
+import argparse
+import ast
+import json
+import logging
+import os
+import signal
+import subprocess
+import sys
+from functools import lru_cache
+
+from mcp.server.fastmcp import FastMCP
+
+from wtinydb_mcp.catalog import PatternsCatalog
+from wtinydb_mcp.templates import TemplateGenerator
+
+# Setup logging strictly to stderr to avoid breaking MCP protocol
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s", stream=sys.stderr)
+logger = logging.getLogger(__name__)
+
+PID_FILE = os.path.expanduser("~/.wtinydb_mcp.pid")
+
+# Create primary FastMCP Server instance
+mcp = FastMCP("wtinydb-mcp-server")
+
+
+@lru_cache(maxsize=1)
+def get_catalog() -> PatternsCatalog:
+    """Return shared patterns catalog instance."""
+    return PatternsCatalog()
+
+
+def _is_pydantic_model(cls: ast.ClassDef) -> bool:
+    """Return True if class inherits from BaseModel or Mixins."""
+    return any(
+        isinstance(b, ast.Name) and b.id in ("BaseModel", "TimestampMixin", "SoftDeleteMixin", "AuditMixin")
+        for b in cls.bases
+    )
+
+
+@mcp.tool()
+def validate_model_schema(model_code: str) -> str:
+    """Validate a Pydantic model definition for WTinyDB compatibility."""
+    try:
+        tree = ast.parse(model_code)
+        issues = []
+        warnings = []
+
+        classes = [n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]
+        model_classes = [c for c in classes if _is_pydantic_model(c)]
+
+        if not model_classes:
+            issues.append("No Pydantic BaseModel or WTinyDB Mixin subclass found.")
+
+        result = "Valid Model Validation Result:\n"
+        if issues:
+            result += "Issues:\n" + "\n".join(f"  ❌ {i}" for i in issues) + "\n"
+        if warnings:
+            result += "Warnings:\n" + "\n".join(f"  ⚠️ {w}" for w in warnings) + "\n"
+        if not issues and not warnings:
+            result += "✅ Model looks good for WTinyDB document storage!"
+        return result
+
+    except SyntaxError as e:
+        return f"❌ Syntax Error in model code: {e}"
+    except Exception as e:
+        return f"❌ Validation Error: {type(e).__name__}: {e}"
+
+
+@mcp.tool()
+def search_wtinydb_pattern(query: str) -> str:
+    """Search for production-ready WTinyDB architectural patterns."""
+    results = get_catalog().search(query)
+    if not results:
+        return f"No pattern matching '{query}' was found in WTinyDB catalog."
+
+    response = "Found production-ready architectural patterns in wisrovi SUITE:\n\n"
+    for p in results:
+        response += f"🚀 [{p['origin']}] {p['name']}\n"
+        response += f"   - Feature: {p['feature']}\n"
+        response += f"   - Module: {p['module']}\n"
+        response += f"   - Description: {p['description']}\n\n"
+    return response
+
+
+@mcp.tool()
+def deploy_wtinydb_scaffolding(
+    target_dir: str,
+    project_name: str = "wtinydb_project",
+    scaffold_type: str = "standard",
+) -> str:
+    """Deploys a professional WTinyDB project structure following wisrovi standards."""
+    try:
+        if not os.path.isabs(target_dir):
+            return "Error: target_dir must be an absolute path."
+
+        for folder in TemplateGenerator.get_folders(scaffold_type):
+            os.makedirs(os.path.join(target_dir, folder), exist_ok=True)
+
+        blueprints = TemplateGenerator.get_files_blueprint(scaffold_type, project_name)
+        for rel_path, content in blueprints.items():
+            full_path = os.path.join(target_dir, rel_path)
+            os.makedirs(os.path.dirname(full_path), exist_ok=True)
+            with open(full_path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+        return f"Success: WTinyDB architecture '{project_name}' deployed at {target_dir}"
+    except Exception as e:
+        return f"Error deploying scaffolding: {str(e)}"
+
+
+@mcp.tool()
+def get_wtinydb_architect_blueprints() -> str:
+    """Complete reference with read/write/update examples for every WTinyDB feature."""
+    crud_code = (
+        "from pydantic import BaseModel, Field\n"
+        "from wtinydb import WTinyDB, SoftDeleteMixin\n\n"
+        "class Article(SoftDeleteMixin, BaseModel):\n"
+        "    title: str\n"
+        "    content: str\n"
+        "    tags: list[str] = []\n\n"
+        "db = WTinyDB(Article, db_path='articles.json')\n"
+        "# WRITE\n"
+        "art = db.insert(Article(title='Intro', content='Hello World'))\n"
+        "# READ\n"
+        "all_articles = db.get_all()\n"
+        "art1 = db.get(1)\n"
+        "# UPDATE\n"
+        "db.update(1, {'title': 'Updated Title'})\n"
+        "# DELETE\n"
+        "db.delete(1, hard=False)\n"
+    )
+
+    async_code = (
+        "import asyncio\n"
+        "from wtinydb import WTinyDB, AsyncWTinyDB\n\n"
+        "async def main():\n"
+        "    sync_db = WTinyDB(Article, db_path='articles.json')\n"
+        "    db = AsyncWTinyDB(sync_db)\n"
+        "    art = await db.insert(Article(title='Async Title', content='Text'))\n"
+        "    rows = await db.get_all()\n"
+        "    await db.close()\n"
+    )
+
+    query_code = (
+        "from wtinydb import WTinyDB, Q\n\n"
+        "db = WTinyDB(Article, in_memory=True)\n"
+        "# Query with operators\n"
+        "tech_articles = db.find(Q('tags').in_list('tags', ['tech', 'python']))\n"
+        "regex_matches = db.find(Q('title').matches('title', r'^Intro'))\n"
+    )
+
+    nested_code = (
+        "from wtinydb import WTinyDB, Q\n\n"
+        "db = WTinyDB(Company, db_path='companies.json')\n"
+        "# N-Level Dotted Path Querying\n"
+        "results = db.find(Q('department.manager.contact.address.city').eq('San Francisco'))\n"
+        "# N-Level Deep Field Updating\n"
+        "db.update(target_company, {'department.budget': 7500000.00})\n"
+    )
+
+    return (
+        "WTINYDB EXPERT BLUEPRINTS (COMPLETE REFERENCE)\n\n"
+        "=== 1. MODEL & CRUD ===\n" + crud_code + "\n"
+        "=== 2. ASYNC OPERATIONS ===\n" + async_code + "\n"
+        "=== 3. FLUENT QUERY BUILDER ===\n" + query_code + "\n"
+        "=== 4. N-LEVEL NESTED JSON CRUD ===\n" + nested_code
+    )
+
+
+@mcp.tool()
+def get_wtinydb_architect_manual() -> str:
+    """Expert manual for building high-performance document database systems with WTinyDB."""
+    manual_text = (
+        "WTINYDB ARCHITECT MANUAL (ADVANCED)\n"
+        "--- PROJECT STRUCTURE RULES (MANDATORY) ---\n"
+        "1. CONFIG: All database settings MUST be centralized in `config/settings.py` as a `DatabaseSettings` dataclass.\n"
+        "2. MODELS: All Pydantic models MUST be placed inside `models/` directory.\n"
+        "3. REPOSITORIES: All data-access logic MUST live in `repositories/` wrapping `WTinyDB` or `AsyncWTinyDB`.\n"
+        "4. ORCHESTRATOR: Service entrypoint MUST be `main.py` at root level.\n\n"
+        "--- CORE RULES ---\n"
+        "1. Always use Pydantic models for schema definitions.\n"
+        "2. Use `SoftDeleteMixin` or `AuditMixin` for soft-deletion and automatic creation/update timestamps.\n"
+        "3. Use `Q` fluent query builder for complex filtering.\n"
+        "4. For FastAPI/async apps, wrap WTinyDB with `AsyncWTinyDB`.\n\n"
+        "Generated by WTinyDB MCP by wisrovi"
+    )
+    return manual_text
+
+
+@mcp.tool()
+def generate_wtinydb_crud(model_code: str) -> str:
+    """Generate repository CRUD wrapper code for a Pydantic model definition."""
+    try:
+        tree = ast.parse(model_code)
+        classes = [n.name for n in ast.walk(tree) if isinstance(n, ast.ClassDef) and _is_pydantic_model(n)]
+        if not classes:
+            return "# Error: No Pydantic model found in provided code."
+
+        model_name = classes[0]
+        repo_name = f"{model_name}Repository"
+
+        code = (
+            f"from typing import List, Optional\n"
+            f"from wtinydb import WTinyDB, Q\n"
+            f"# Import {model_name} from models module\n\n"
+            f"class {repo_name}:\n"
+            f"    def __init__(self, db_path: str = '{model_name.lower()}.json', in_memory: bool = False):\n"
+            f"        self.db = WTinyDB({model_name}, db_path=db_path, in_memory=in_memory)\n\n"
+            f"    def create(self, item: {model_name}) -> {model_name}:\n"
+            f"        return self.db.insert(item)\n\n"
+            f"    def get_by_id(self, doc_id: int) -> {model_name}:\n"
+            f"        return self.db.get(doc_id)\n\n"
+            f"    def get_all(self) -> List[{model_name}]:\n"
+            f"        return self.db.get_all()\n\n"
+            f"    def update(self, doc_id: int, data: dict) -> {model_name}:\n"
+            f"        return self.db.update(doc_id, data)\n\n"
+            f"    def delete(self, doc_id: int, hard: bool = False) -> bool:\n"
+            f"        return self.db.delete(doc_id, hard=hard)\n"
+        )
+        return code
+    except Exception as e:
+        return f"# Generation error: {e}"
+
+
+def run_stdio():
+    """Run MCP server in stdio mode."""
+    mcp.run(transport="stdio")
+
+
+def main():
+    """Main CLI entrypoint for wtinydb-mcp server."""
+    parser = argparse.ArgumentParser(description="wtinydb-mcp: WTinyDB Architect MCP Server")
+    parser.add_argument("command", nargs="?", default="run", choices=["run", "help"])
+    args = parser.parse_args()
+
+    if args.command == "run":
+        run_stdio()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

wtinydb_mcp/templates.py

@@ -0,0 +1,86 @@
+"""WTinyDB Scaffolding Code and Folder Generator."""
+
+from typing import Dict, List
+
+
+class TemplateGenerator:
+    """Generates standard directory structures and starter files for WTinyDB projects."""
+
+    @staticmethod
+    def get_folders(scaffold_type: str = "standard") -> List[str]:
+        """Return list of directory relative paths to create."""
+        return [
+            "config",
+            "models",
+            "repositories",
+            "services",
+            "tests",
+        ]
+
+    @staticmethod
+    def get_files_blueprint(scaffold_type: str = "standard", project_name: str = "wtinydb_project") -> Dict[str, str]:
+        """Return dictionary of relative file paths and their starter contents."""
+        settings_py = (
+            "from dataclasses import dataclass\n"
+            "import os\n\n"
+            "@dataclass\n"
+            "class DatabaseSettings:\n"
+            "    db_path: str = os.getenv('TINYDB_PATH', 'app_data.json')\n"
+            "    in_memory: bool = os.getenv('TINYDB_IN_MEMORY', 'False').lower() == 'true'\n"
+        )
+
+        user_model_py = (
+            "from pydantic import BaseModel, Field\n"
+            "from wtinydb import AuditMixin\n\n"
+            "class User(AuditMixin, BaseModel):\n"
+            "    name: str = Field(description='User name')\n"
+            "    email: str = Field(description='User email')\n"
+            "    role: str = Field(default='user', description='Role')\n"
+        )
+
+        user_repo_py = (
+            "from wtinydb import WTinyDB, Q\n"
+            "from config.settings import DatabaseSettings\n"
+            "from models.user import User\n\n"
+            "class UserRepository:\n"
+            "    def __init__(self, settings: DatabaseSettings = None):\n"
+            "        settings = settings or DatabaseSettings()\n"
+            "        self.db = WTinyDB(User, db_path=settings.db_path, in_memory=settings.in_memory)\n\n"
+            "    def create_user(self, user: User) -> User:\n"
+            "        return self.db.insert(user)\n\n"
+            "    def get_by_email(self, email: str):\n"
+            "        return self.db.get_by_field('email', email)\n"
+        )
+
+        main_py = (
+            f"'''{project_name} Entrypoint'''\n"
+            "from models.user import User\n"
+            "from repositories.user_repo import UserRepository\n\n"
+            "def main():\n"
+            "    repo = UserRepository()\n"
+            "    user = repo.create_user(User(name='Alice', email='alice@example.com'))\n"
+            "    print(f'User created: {user.name} (email: {user.email})')\n\n"
+            "if __name__ == '__main__':\n"
+            "    main()\n"
+        )
+
+        readme_md = (
+            f"# {project_name}\n\n"
+            "WTinyDB Document Store Application.\n\n"
+            "## Architecture\n"
+            "```mermaid\n"
+            "flowchart TD\n"
+            "    Main[main.py] --> Repo[UserRepository]\n"
+            "    Repo --> WTinyDB[WTinyDB Engine]\n"
+            "    WTinyDB --> JSON[(TinyDB JSON Storage)]\n"
+            "```\n\n"
+            "*Generated by WTinyDB MCP by wisrovi*\n"
+        )
+
+        return {
+            "config/settings.py": settings_py,
+            "models/user.py": user_model_py,
+            "repositories/user_repo.py": user_repo_py,
+            "main.py": main_py,
+            "README.md": readme_md,
+        }

wtinydb_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: wtinydb-mcp
+Version: 0.1.0
+Summary: Model Context Protocol (MCP) server for WTinyDB architecture and code generation
+Author-email: "WILLIAM R." <william@ecapturedtech.com>
+License: MIT
+Keywords: mcp,wtinydb,tinydb,ai-agent,fastmcp,architecture
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# wtinydb-mcp: Model Context Protocol Server for WTinyDB
+
+`wtinydb-mcp` is an official **Model Context Protocol (MCP)** server built on top of **FastMCP** that equips AI agents with tools to architect, validate, scaffold, and generate code for **WTinyDB** (TinyDB + Pydantic document database engine).
+
+## Key Technologies & Libraries
+
+- **[MCP Protocol](https://modelcontextprotocol.io/)**: Open standard connecting AI models to external tools and context.
+- **[FastMCP](https://github.com/jlowin/fastmcp)**: Python framework for fast MCP server implementation.
+- **[WTinyDB](file:///home/william.rodriguez/Documents/w_libraries/w_libraries/wtinydb_os/wtinydb)**: Pydantic-powered document database engine on top of TinyDB.
+- **[Pydantic v2](https://docs.pydantic.dev/)**: Data schema validation and Python AST inspection.
+- **[Pytest](https://docs.pytest.org/)**: Modern Python testing framework.
+- **[Pytest-Cov](https://pytest-cov.readthedocs.io/)**: Code coverage measurement for pytest.
+- **[Docker](https://www.docker.com/)**: Containerized test execution environment.
+
+---
+
+## MCP Tools Exposed
+
+1. **`validate_model_schema(model_code: str)`**: Validates Pydantic document models for WTinyDB compatibility.
+2. **`search_wtinydb_pattern(query: str)`**: Searches the official wisrovi SUITE catalog for WTinyDB architectural patterns.
+3. **`deploy_wtinydb_scaffolding(target_dir: str, project_name: str, scaffold_type: str)`**: Deploys project scaffolding with repository, config, models, and tests.
+4. **`get_wtinydb_architect_blueprints()`**: Returns code reference and blueprints for WTinyDB features.
+5. **`get_wtinydb_architect_manual()`**: Returns the comprehensive WTinyDB architecting manual.
+6. **`generate_wtinydb_crud(model_code: str)`**: Automatically generates repository CRUD class for Pydantic models.
+
+---
+
+## Running Unit Tests & Coverage
+
+### Local Pytest Execution
+
+```bash
+# Install editable package
+pip install -e .
+
+# Run pytest test suite
+pytest tests/
+
+# Calculate code coverage
+./scripts/run_coverage.sh
+```
+
+### Docker Containerized Test Execution
+
+```bash
+./scripts/run_tests_docker.sh
+```
+
+---
+
+*Part of the wisrovi SUITE ecosystem.*

wtinydb_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+wtinydb_mcp/__init__.py,sha256=wJsh9LgxlxtTqgixgHZJarLL-jkiSRFjb4W50_LMq4A,65
+wtinydb_mcp/catalog.py,sha256=ExZDrKRvf9OjuJpasERa5axtaqy0yxjAznhiZt3zqnU,2372
+wtinydb_mcp/server.py,sha256=saNB9Wr4VsA_5AI0d13b_avsEzt-NXMAix9bEbLq3rk,9362
+wtinydb_mcp/templates.py,sha256=HAEyFuMQ6sY5uo7B56bTBP8fJq1u9aG3Y_eUbXJ-cC4,3386
+wtinydb_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=Oyqf3mzTxsLVAFwTwTpmcfEsdCeJnA4jMu5Dv-Jq_Ag,1074
+wtinydb_mcp-0.1.0.dist-info/METADATA,sha256=0NJMeaRTuU61mvllo-wAY3Q5N8Hcph7djgWz8bkHeC4,2772
+wtinydb_mcp-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wtinydb_mcp-0.1.0.dist-info/entry_points.txt,sha256=d93l9KfgOZuIoTduDhtsTLYLquem42grZxwknIfNLao,56
+wtinydb_mcp-0.1.0.dist-info/top_level.txt,sha256=-KDYh9p5VKwAAuEl4jL4_KHhl89ueOWZU07Bf1hfWgQ,12
+wtinydb_mcp-0.1.0.dist-info/RECORD,,

wtinydb_mcp-0.1.0.dist-info/WHEEL

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

wtinydb_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wtinydb-mcp = wtinydb_mcp.server:main

wtinydb_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Rodriguez
+
+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.

wtinydb_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wtinydb_mcp