scaffold-ca-python 0.1.4__py3-none-any.whl → 0.2.0__py3-none-any.whl

scaffold_ca_python/commands/generate_entry_point.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ast
 import json
 import tomllib
 from pathlib import Path
@@ -11,11 +12,13 @@ import typer
 import yaml
 from rich.console import Console
 from rich.markup import escape
+from rich.syntax import Syntax
 from rich.tree import Tree
 
+from scaffold_ca_python.core import mcp_tool_spec
 from scaffold_ca_python.core.module_builder import ModuleBuilder
 from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case
-from scaffold_ca_python.core.project_detector import find_project_root
+from scaffold_ca_python.core.project_detector import find_project_root, resolve_tests_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.entry_points.ep_agent import EntryPointAgent
 from scaffold_ca_python.factory.entry_points.ep_generic import EntryPointGeneric
@@ -45,12 +48,11 @@ _GEP_EPILOG = (
     "  * mcp        MCP server entry point\n\n"
     "  * generic    Plain entry point\n\n"
     " ==================================================\n\n"
-    "Notes: --enable-kafka and --enable-mcp-client are agent type only.\n\n"
-    " ==================================================\n\n"
     "Examples:\n\n"
     "  * scaffold gep --type restapi\n\n"
     "  * scaffold gep --type agent --enable-kafka\n\n"
     "  * scaffold gep --type mcp\n\n"
+    "  * scaffold gep --type mcp --add-tool --name create_file --param path:str --returns str\n\n"
     "  * scaffold generate-entry-point --type generic\n"
 )
 
@@ -64,6 +66,235 @@ def _load_project_context(project_root: Path) -> ProjectContext:
     return ProjectContext(name=project_name)
 
 
+def _add_tool_impl(
+    type_: str,
+    swagger: str | None,
+    enable_kafka: bool,
+    enable_mcp_client: bool,
+    with_resources: bool,
+    with_prompts: bool,
+    name: str | None,
+    param: list[str] | None,
+    returns: str,
+    description: str | None,
+    dry_run: bool,
+) -> None:
+    """Add a tool to an existing MCP entry point (T018-T021, T027-T030a).
+
+    Implements User Story 1 and 2: appends a tool stub to tools.py and a registration
+    test to test_tools.py in an existing MCP project, with comprehensive guard rails.
+    """
+    # T028: Flag/type incompatibility guards (FR-011, FR-012) - before project access
+    # Check creation-only flags
+    creation_flags = []
+    if swagger is not None:
+        creation_flags.append("--swagger")
+    if enable_kafka:
+        creation_flags.append("--enable-kafka")
+    if enable_mcp_client:
+        creation_flags.append("--enable-mcp-client")
+    if with_resources:
+        creation_flags.append("--with-resources")
+    if with_prompts:
+        creation_flags.append("--with-prompts")
+
+    if creation_flags:
+        flag = creation_flags[0]
+        console.print(f"[red]Error:[/red] --add-tool is incompatible with {flag}.")
+        raise typer.Exit(code=1)
+
+    # Check type compatibility (FR-012) - handled by T016(a) for --type omitted
+    # Here we check non-mcp types
+    if type_ != "mcp":
+        console.print("[red]Error:[/red] --add-tool is only valid with --type mcp.")
+        raise typer.Exit(code=1)
+
+    # T018: Format-only validation (no filesystem access yet)
+    if name is None:
+        console.print("[red]Error:[/red] --name is required with --add-tool.")
+        raise typer.Exit(code=1)
+
+    try:
+        tool_spec = mcp_tool_spec.build_tool_spec(name, param, returns, description)
+    except (ValueError, ScaffoldError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+
+    # T019: Resolve project root and check entry point exists
+    try:
+        project_root = find_project_root()
+    except ScaffoldError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+
+    project_ctx = _load_project_context(project_root)
+
+    tools_py_path = (
+        project_root
+        / "src"
+        / project_ctx.python_package
+        / "infrastructure"
+        / "entry_points"
+        / "mcp_server"
+        / "tools.py"
+    )
+    test_tools_py_path = (
+        resolve_tests_root(project_root) / "infrastructure" / "entry_points" / "mcp_server" / "test_tools.py"
+    )
+
+    if not tools_py_path.exists():
+        console.print(
+            "[red]Error:[/red] No MCP entry point found at infrastructure/entry_points/mcp_server/.\n"
+            "[dim]Hint:[/dim] Run [cyan]scaffold gep --type mcp[/cyan] first to create one."
+        )
+        raise typer.Exit(code=1)
+
+    # T020: Read files and check structure
+    try:
+        original_tools_py = tools_py_path.read_text(encoding="utf-8")
+    except OSError as e:
+        console.print(f"[red]Error:[/red] Cannot read {tools_py_path}: {e}")
+        raise typer.Exit(code=1) from None
+
+    try:
+        original_test_tools_py = test_tools_py_path.read_text(encoding="utf-8")
+    except OSError:
+        console.print(
+            "[red]Error:[/red] tests/infrastructure/entry_points/mcp_server/test_tools.py is missing or "
+            "does not have\n"
+            "the structure --add-tool needs to append a registration test.\n"
+            "[dim]Hint:[/dim] Restore test_tools.py, or regenerate the entry point with "
+            "[cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # Check bind_tools is last top-level statement
+    if not mcp_tool_spec.has_bind_tools_function(original_tools_py):
+        console.print(
+            "[red]Error:[/red] infrastructure/entry_points/mcp_server/tools.py was generated by an older "
+            "scaffold\n"
+            "version and does not support --add-tool.\n"
+            "[dim]Hint:[/dim] Make [cyan]async def bind_tools[/cyan] the last function in tools.py, or "
+            "regenerate the entry point\n"
+            "(back up any custom tools first) with [cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # Check test file has required structure
+    if not mcp_tool_spec.has_test_registration_structure(original_test_tools_py):
+        console.print(
+            "[red]Error:[/red] tests/infrastructure/entry_points/mcp_server/test_tools.py is missing or "
+            "does not have\n"
+            "the structure --add-tool needs to append a registration test.\n"
+            "[dim]Hint:[/dim] Restore test_tools.py, or regenerate the entry point with "
+            "[cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # Check for duplicate tool names
+    existing_names = mcp_tool_spec.find_existing_tool_names(original_tools_py)
+    if tool_spec.name in existing_names:
+        if tool_spec.name == "bind_tools":
+            console.print(
+                f"[red]Error:[/red] '{tool_spec.name}' is reserved by the tool-binding function and "
+                "cannot be used as a tool name."
+            )
+        else:
+            console.print(f"[red]Error:[/red] A tool named '{tool_spec.name}' already exists in tools.py.")
+        raise typer.Exit(code=1)
+
+    # T021: Render templates and append
+    builder = ModuleBuilder(
+        project_root=project_root,
+        project_ctx=project_ctx,
+        dry_run=dry_run,
+    )
+
+    # Render tool stub (4-space-indented nested function)
+    tool_stub_content = builder.render(
+        "entry_point/mcp/tool_stub.py.jinja2",
+        {
+            "name": tool_spec.name,
+            "params": [{"name": p.name, "type": p.type} for p in tool_spec.params],
+            "returns": tool_spec.returns,
+            "docstring": tool_spec.docstring,
+        },
+    )
+
+    # Render test stub
+    test_stub_content = builder.render(
+        "entry_point/mcp/test_tool_stub.py.jinja2",
+        {"name": tool_spec.name},
+    )
+
+    # Safety check: ensure appended content will parse
+    try:
+        ast.parse(original_tools_py + tool_stub_content)
+    except SyntaxError:
+        console.print(
+            "[red]Error:[/red] infrastructure/entry_points/mcp_server/tools.py cannot accept the new tool stub.\n"
+            "[dim]Hint:[/dim] Regenerate the entry point with [cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # T030a: Check writability before any writes (FR-019)
+    import os
+
+    if not os.access(tools_py_path, os.W_OK):
+        console.print(
+            f"[red]Error:[/red] Cannot write to {tools_py_path.relative_to(project_root)}.\n"
+            "[dim]Hint:[/dim] Check the file's permissions and re-run the command."
+        )
+        raise typer.Exit(code=1)
+
+    if not os.access(test_tools_py_path, os.W_OK):
+        console.print(
+            f"[red]Error:[/red] Cannot write to {test_tools_py_path.relative_to(project_root)}.\n"
+            "[dim]Hint:[/dim] Check the file's permissions and re-run the command."
+        )
+        raise typer.Exit(code=1)
+
+    # Queue append operations
+    builder.append_to_file(tools_py_path, tool_stub_content)
+    builder.append_to_file(test_tools_py_path, test_stub_content)
+
+    # T030a: Persist changes with restore-on-failure (FR-019)
+    try:
+        modified_paths = builder.persist()
+    except OSError as e:
+        # Restore original content
+        try:
+            tools_py_path.write_text(original_tools_py, encoding="utf-8")
+            test_tools_py_path.write_text(original_test_tools_py, encoding="utf-8")
+        except OSError:
+            pass  # Best effort restore
+
+        # Determine which file failed
+        error_str = str(e).lower()
+        if "test_tools" in error_str or str(test_tools_py_path) in str(e):
+            failed_file = "test_tools.py"
+        else:
+            failed_file = "tools.py"
+
+        console.print(
+            f"[red]Error:[/red] Failed to write {failed_file} ({e}). "
+            "tools.py was restored; no changes were made.\n"
+            "[dim]Hint:[/dim] Fix the underlying problem (permissions, disk space) and re-run the command."
+        )
+        raise typer.Exit(code=1) from None
+
+    if dry_run:
+        console.print("\n[yellow]Dry run:[/yellow] Would modify:\n")
+        for path in modified_paths:
+            console.print(f"  • {path.relative_to(project_root)}")
+        console.print("\n[yellow]Tool stub preview:[/yellow]")
+        console.print(Syntax(tool_stub_content, "python", theme="monokai", line_numbers=False))
+        console.print("\n[yellow]Test stub preview:[/yellow]")
+        console.print(Syntax(test_stub_content, "python", theme="monokai", line_numbers=False))
+    else:
+        console.print(f"[green]✓[/green] Added tool '{tool_spec.name}' to MCP entry point.")
+
+
 def _generate_entry_point_impl(
     type_: str,
     swagger: str | None,
@@ -71,8 +302,30 @@ def _generate_entry_point_impl(
     enable_mcp_client: bool,
     with_resources: bool,
     with_prompts: bool,
+    add_tool: bool,
+    name: str | None,
+    param: list[str] | None,
+    returns: str,
+    description: str | None,
     dry_run: bool,
 ) -> None:
+    # T016(b): Dispatch to --add-tool implementation if flag is set
+    if add_tool:
+        _add_tool_impl(
+            type_,
+            swagger,
+            enable_kafka,
+            enable_mcp_client,
+            with_resources,
+            with_prompts,
+            name,
+            param,
+            returns,
+            description,
+            dry_run,
+        )
+        return
+
     # --- Validate type ---
     if type_ not in _REGISTRY:
         console.print(f"[red]Error:[/red] Unknown type '{type_}'. Allowed: {', '.join(_REGISTRY.keys())}.")
@@ -287,6 +540,24 @@ def register(app: typer.Typer) -> None:
                 show_default=True,
             ),
         ] = False,
+        add_tool: Annotated[
+            bool,
+            typer.Option(
+                "--add-tool/--no-add-tool",
+                help="Add a tool to an existing MCP entry point (mcp only).",
+                rich_help_panel="Options",
+                show_default=True,
+            ),
+        ] = False,
+        name: Annotated[str | None, typer.Option("--name", help="Tool name (required with --add-tool).")] = None,
+        param: Annotated[
+            list[str] | None,
+            typer.Option("--param", help="Tool parameter in 'name:type' format (repeatable)."),
+        ] = None,
+        returns: Annotated[str, typer.Option("--returns", help="Tool return type.")] = "str",
+        description: Annotated[
+            str | None, typer.Option("--description", help="Tool description for docstring.")
+        ] = None,
         dry_run: Annotated[
             bool,
             typer.Option(
@@ -298,9 +569,25 @@ def register(app: typer.Typer) -> None:
         ] = False,
     ) -> None:
         """Scaffold an entry point inside infrastructure/entry_points/."""
+        # T016(a): Check --add-tool without --type before the help shortcut
+        if add_tool and type_ is None:
+            console.print("[red]Error:[/red] --add-tool is only valid with --type mcp.")
+            raise typer.Exit(code=1)
+
         if type_ is None:
             typer.echo(ctx.get_help())
             raise typer.Exit(0)
         _generate_entry_point_impl(
-            type_, swagger, enable_kafka, enable_mcp_client, with_resources, with_prompts, dry_run
+            type_,
+            swagger,
+            enable_kafka,
+            enable_mcp_client,
+            with_resources,
+            with_prompts,
+            add_tool,
+            name,
+            param,
+            returns,
+            description,
+            dry_run,
         )

scaffold_ca_python/core/file_writer.py

@@ -7,7 +7,7 @@ import tempfile
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from scaffold_ca_python.models.file_operation import CreateFile, DeleteFile, FileOperation, InsertAfter
+from scaffold_ca_python.models.file_operation import AppendToFile, CreateFile, DeleteFile, FileOperation, InsertAfter
 
 if TYPE_CHECKING:
     pass
@@ -60,7 +60,7 @@ class FileWriter:
         for op in operations:
             if isinstance(op, CreateFile):
                 result.append(op.file.path)
-            elif isinstance(op, (DeleteFile, InsertAfter)):
+            elif isinstance(op, (DeleteFile, InsertAfter, AppendToFile)):
                 result.append(op.path)
         return result
 
@@ -110,6 +110,11 @@ class FileWriter:
         for op in inserts:
             self._apply_insert_after(op)
 
+        # Process append_to_file mutations in declaration order
+        appends: list[AppendToFile] = [op for op in operations if isinstance(op, AppendToFile)]
+        for op in appends:
+            self._apply_append_to_file(op)
+
         return committed
 
     @staticmethod
@@ -126,3 +131,23 @@ class FileWriter:
                 op.path.write_text("".join(lines), encoding="utf-8")
                 return
         raise ValueError(f"insert_after anchor {op.anchor!r} not found in {op.path}")
+
+    @staticmethod
+    def _apply_append_to_file(op: AppendToFile) -> None:
+        """Append *op.content* to the end of *op.path*, or create the file.
+
+        When the file exists, trailing blank lines are normalized to a single newline
+        before appending. When it doesn't exist, it's created with *op.content* as
+        initial contents (leading blank lines stripped).
+        """
+        if op.path.exists():
+            # File exists - normalize trailing newlines and append
+            original = op.path.read_text(encoding="utf-8")
+            # Strip all trailing newlines, then ensure exactly one
+            normalized = original.rstrip("\n") + "\n"
+            op.path.write_text(normalized + op.content, encoding="utf-8")
+        else:
+            # File doesn't exist - create it with content (strip leading blank lines)
+            op.path.parent.mkdir(parents=True, exist_ok=True)
+            content = op.content.lstrip("\n")
+            op.path.write_text(content, encoding="utf-8")

scaffold_ca_python/core/mcp_tool_spec.py

@@ -0,0 +1,325 @@
+"""MCP tool specification parsing and validation (T012).
+
+This module provides utilities for parsing and validating --add-tool CLI arguments,
+including tool names, parameters, type expressions, and duplicate-name detection.
+"""
+
+from __future__ import annotations
+
+import ast
+import keyword
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from scaffold_ca_python.core.name_utils import ScaffoldError, validate_module_name
+
+
+class ParamSpec(BaseModel):
+    """A single parsed --param name:type value."""
+
+    name: str
+    type: str
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate parameter name is snake_case and not a hard keyword."""
+        # Reuse validate_module_name for snake_case check
+        validate_module_name(v)
+
+        # Check for hard keywords
+        if keyword.iskeyword(v):
+            msg = f"'{v}' is a Python keyword and cannot be used as a parameter name."
+            raise ValueError(msg)
+
+        return v
+
+
+class ToolSpec(BaseModel):
+    """Parsed, fully-validated representation of a single --add-tool invocation."""
+
+    name: str
+    params: list[ParamSpec]
+    returns: str
+    docstring: str
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate tool name is snake_case and not a hard keyword."""
+        validate_module_name(v)
+
+        if keyword.iskeyword(v):
+            msg = f"'{v}' is a Python keyword and cannot be used as a tool name."
+            raise ValueError(msg)
+
+        return v
+
+    @field_validator("returns")
+    @classmethod
+    def validate_returns_type(cls, v: str) -> str:
+        """Validate returns is a valid type expression."""
+        if not validate_type_expression(v):
+            msg = f"Invalid --returns '{v}'. Not a recognizable type-expression."
+            raise ValueError(msg)
+        return v
+
+    @model_validator(mode="after")
+    def check_no_duplicate_param_names(self) -> ToolSpec:
+        """Reject duplicate parameter names."""
+        names = [p.name for p in self.params]
+        seen = set()
+        for name in names:
+            if name in seen:
+                msg = f"Duplicate --param name '{name}'. Each parameter name must be unique."
+                raise ValueError(msg)
+            seen.add(name)
+        return self
+
+
+def parse_param(param_str: str) -> tuple[str, str]:
+    """Parse a --param 'name:type' string.
+
+    Args:
+        param_str: String in format 'name:type'
+
+    Returns:
+        Tuple of (name, type)
+
+    Raises:
+        ValueError: If format is invalid, name is not snake_case, name is a hard
+                    keyword, or type is not a recognizable type-expression
+    """
+    if ":" not in param_str:
+        msg = f"Invalid --param '{param_str}'. Expected 'name:type' format."
+        raise ValueError(msg)
+
+    # Split on first colon only
+    name, type_str = param_str.split(":", 1)
+
+    # Validate name (snake_case)
+    try:
+        validate_module_name(name)
+    except (ValueError, ScaffoldError) as e:
+        msg = f"Invalid --param '{param_str}'. Parameter name must be snake_case (e.g., 'path:str')."
+        raise ValueError(msg) from e
+
+    # Check for hard keywords
+    if keyword.iskeyword(name):
+        msg = f"Invalid --param '{param_str}'. '{name}' is a Python keyword and cannot be used as a parameter name."
+        raise ValueError(msg)
+
+    # Validate type expression
+    if not validate_type_expression(type_str):
+        msg = f"Invalid --param '{param_str}'. '{type_str}' is not a recognizable type-expression."
+        raise ValueError(msg)
+
+    return name, type_str
+
+
+def validate_type_expression(type_str: str) -> bool:
+    """Check if type_str is a recognizable Python type expression.
+
+    Uses AST parsing to verify the type string is a valid type expression
+    (Name, Subscript, BinOp with |, Attribute, etc.) and not a function call,
+    string literal, arithmetic expression, lambda, or comprehension.
+
+    Args:
+        type_str: Type expression string to validate
+
+    Returns:
+        True if valid type expression, False otherwise
+    """
+    try:
+        node = ast.parse(type_str, mode="eval").body
+    except SyntaxError:
+        return False
+
+    # Allowed: Name (str, int), Subscript (list[str]), BinOp (str | None),
+    # Attribute (typing.Optional), Constant (for Literal values inside [...])
+    # Not allowed: Call, Str/Constant at top level, Lambda, comprehensions, arithmetic
+    return _is_type_expression_node(node)
+
+
+def _is_type_expression_node(node: ast.expr) -> bool:
+    """Recursively check if AST node represents a valid type expression."""
+    if isinstance(node, ast.Name):
+        return True
+    if isinstance(node, ast.Constant):
+        # Allow None and Ellipsis in type expressions
+        return node.value is None or node.value is ...
+    if isinstance(node, ast.Attribute):
+        return True
+    if isinstance(node, ast.Subscript):
+        # Allow Constant in subscript (for Literal["a", "b"])
+        return _is_type_expression_node(node.value) and _is_subscript_arg_valid(node.slice)
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        return _is_type_expression_node(node.left) and _is_type_expression_node(node.right)
+    if isinstance(node, ast.Tuple):
+        # For tuple[int, ...] syntax
+        return all(_is_type_expression_node(elt) if not isinstance(elt, ast.Constant) else True for elt in node.elts)
+    return False
+
+
+def _is_subscript_arg_valid(node: ast.expr) -> bool:
+    """Check if subscript argument is valid (Name, Tuple, or Constant for Literal)."""
+    if isinstance(node, ast.Constant):
+        return True  # Allow string literals inside Literal[...]
+    if isinstance(node, ast.Tuple):
+        return all(_is_subscript_arg_valid(elt) for elt in node.elts)
+    return _is_type_expression_node(node)
+
+
+def find_existing_tool_names(tools_py_source: str) -> set[str]:
+    """Find all existing tool names in tools.py.
+
+    Returns the union of:
+    - Every @<x>.tool("name") registered name
+    - Every function name defined directly inside bind_tools
+    - The reserved name "bind_tools"
+
+    Args:
+        tools_py_source: Source code of tools.py
+
+    Returns:
+        Set of existing tool names
+    """
+    names: set[str] = {"bind_tools"}  # Always reserved
+
+    try:
+        module = ast.parse(tools_py_source)
+    except SyntaxError:
+        return names
+
+    # Find @<x>.tool("name") decorators
+    for node in ast.walk(module):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                # Match @mcp.tool("name") or @x.tool("name")
+                if (
+                    isinstance(decorator, ast.Call)
+                    and isinstance(decorator.func, ast.Attribute)
+                    and decorator.func.attr == "tool"
+                    and decorator.args
+                    and isinstance(decorator.args[0], ast.Constant)
+                    and isinstance(decorator.args[0].value, str)
+                ):
+                    names.add(decorator.args[0].value)
+
+    # Find function names inside bind_tools
+    for node in ast.walk(module):
+        if isinstance(node, ast.AsyncFunctionDef) and node.name == "bind_tools":
+            for child in ast.walk(node):
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)) and child != node:
+                    names.add(child.name)
+
+    return names
+
+
+def has_bind_tools_function(tools_py_source: str) -> bool:
+    """Check if tools.py has async def bind_tools as the last top-level statement.
+
+    Args:
+        tools_py_source: Source code of tools.py
+
+    Returns:
+        True if last top-level statement is async def bind_tools, False otherwise
+    """
+    try:
+        module = ast.parse(tools_py_source)
+    except SyntaxError:
+        return False
+
+    if not module.body:
+        return False
+
+    last_stmt = module.body[-1]
+    return isinstance(last_stmt, ast.AsyncFunctionDef) and last_stmt.name == "bind_tools"
+
+
+def has_test_registration_structure(test_tools_py_source: str) -> bool:
+    """Check if test_tools.py can host an appended registration test.
+
+    Returns True only if it defines a top-level _make_mock_mcp function and
+    imports both bind_tools and asyncio.
+
+    Args:
+        test_tools_py_source: Source code of test_tools.py
+
+    Returns:
+        True if structure is compatible, False otherwise
+    """
+    try:
+        module = ast.parse(test_tools_py_source)
+    except SyntaxError:
+        return False
+
+    # Check for _make_mock_mcp function
+    has_helper = any(isinstance(node, ast.FunctionDef) and node.name == "_make_mock_mcp" for node in module.body)
+
+    # Check for required imports
+    imported = set()
+    for node in module.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                imported.add(alias.asname or alias.name)
+
+    has_required_imports = {"bind_tools", "asyncio"} <= imported
+
+    return has_helper and has_required_imports
+
+
+def validate_description(description: str | None) -> str:
+    """Validate description is safe for docstring embedding.
+
+    Args:
+        description: User-provided description or None
+
+    Returns:
+        Validated description or generic placeholder
+
+    Raises:
+        ValueError: If description contains embedded triple-quote sequence
+    """
+    if not description or not description.strip():
+        return "TODO: describe this tool."
+
+    if '"""' in description or "'''" in description:
+        msg = "--description contains an embedded triple-quote sequence and cannot be used as a docstring."
+        raise ValueError(msg)
+
+    return description
+
+
+def build_tool_spec(
+    name: str,
+    param: list[str] | None,
+    returns: str | None,
+    description: str | None,
+) -> ToolSpec:
+    """Build a validated ToolSpec from CLI arguments.
+
+    Args:
+        name: Tool name (required)
+        param: List of 'name:type' strings or None
+        returns: Return type expression or None (defaults to "str")
+        description: Tool description or None (defaults to placeholder)
+
+    Returns:
+        Validated ToolSpec
+
+    Raises:
+        ValueError: If any validation fails
+    """
+    params = []
+    if param:
+        for p in param:
+            param_name, param_type = parse_param(p)
+            params.append(ParamSpec(name=param_name, type=param_type))
+
+    return ToolSpec(
+        name=name,
+        params=params,
+        returns=returns or "str",
+        docstring=validate_description(description),
+    )

scaffold_ca_python/core/module_builder.py

@@ -17,7 +17,14 @@ from scaffold_ca_python.core.pyproject_writer import (
     update_project_scripts,
 )
 from scaffold_ca_python.core.template_renderer import TemplateRenderer
-from scaffold_ca_python.models.file_operation import CreateFile, DeleteFile, FileOperation, GeneratedFile, InsertAfter
+from scaffold_ca_python.models.file_operation import (
+    AppendToFile,
+    CreateFile,
+    DeleteFile,
+    FileOperation,
+    GeneratedFile,
+    InsertAfter,
+)
 
 if TYPE_CHECKING:
     from scaffold_ca_python.models.context import ModuleContext, ProjectContext
@@ -88,6 +95,16 @@ class ModuleBuilder:
         """
         self._operations.append(InsertAfter(path=path, anchor=anchor, content=content))
 
+    def append_to_file(self, path: Path, content: str) -> None:
+        """Queue an append-to-file operation.
+
+        *content* will be appended to the end of *path*. If *path* does not exist,
+        it will be created. When the file exists, its trailing blank lines are
+        normalized to a single newline before appending. In dry-run mode the path
+        is included in the preview list without modifying the file.
+        """
+        self._operations.append(AppendToFile(path=path, content=content))
+
     def render(self, template_name: str, context: BaseModel | dict[str, Any]) -> str:
         """Render a template through the shared renderer."""
         return self._renderer.render(template_name, context)

scaffold_ca_python/models/file_operation.py

@@ -44,4 +44,22 @@ class InsertAfter(BaseModel):
     content: str
 
 
-FileOperation = Annotated[CreateFile | DeleteFile | InsertAfter, "FileOperation"]
+class AppendToFile(BaseModel):
+    """Append *content* to the end of an existing file, or create the file.
+
+    When *path* exists, its trailing blank lines are normalized to a single
+    newline before *content* is appended. When *path* does not exist, it is
+    created (including parent directories) with *content* as initial contents.
+
+    Raises
+    ------
+    OSError
+        When file operations fail (permissions, disk space, etc.)
+    """
+
+    kind: Literal["append_to_file"] = "append_to_file"
+    path: Path
+    content: str
+
+
+FileOperation = Annotated[CreateFile | DeleteFile | InsertAfter | AppendToFile, "FileOperation"]

scaffold_ca_python/templates/entry_point/mcp/test_tool_stub.py.jinja2

@@ -0,0 +1,8 @@
+
+
+def test_bind_tools_registers_{{ name }}() -> None:
+    """Calling bind_tools registers '{{ name }}' on the mcp instance."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_tools, "__wrapped__", bind_tools)
+    asyncio.run(fn(mock_mcp))
+    assert "{{ name }}" in registered

scaffold_ca_python/templates/entry_point/mcp/tool_stub.py.jinja2

@@ -0,0 +1,5 @@
+
+    @mcp.tool("{{ name }}")
+    async def {{ name }}({% for param in params %}{{ param.name }}: {{ param.type }}{% if not loop.last %}, {% endif %}{% endfor %}) -> {{ returns }}:
+        """{{ docstring }}"""
+        raise NotImplementedError("Tool '{{ name }}' is not yet implemented.")

scaffold_ca_python/templates/project/pyproject_toml.jinja2

@@ -64,7 +64,7 @@ exclude_also = [
 ]
 
 [tool.pytest.ini_options]
-addopts = "--cov={{ python_package }} --cov-fail-under=80 --import-mode=importlib"
+addopts = "--cov={{ python_package }} --cov-fail-under=75 --import-mode=importlib"
 testpaths = ["src/tests"]
 asyncio_default_fixture_loop_scope = "function"
 filterwarnings = [

{scaffold_ca_python-0.1.4.dist-info → scaffold_ca_python-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scaffold-ca-python
-Version: 0.1.4
+Version: 0.2.0
 Summary: Scaffolder to generate Clean Architecture apps
 Project-URL: Homepage, https://github.com/bancolombia/scaffold-clean-architecture-py
 Project-URL: Repository, https://github.com/bancolombia/scaffold-clean-architecture-py
@@ -151,6 +151,10 @@ scaffold gep --type restapi
 scaffold gep --type mcp --with-resources --with-prompts --dry-run
 ```
 
+```bash
+scaffold gep --type mcp --add-tool --name create_file --param path:str --param content:str --returns str --description "Creates a file on disk"
+```
+
 ### scaffold gh
 
 Scaffold a helper utility module and its test stub.

{scaffold_ca_python-0.1.4.dist-info → scaffold_ca_python-0.2.0.dist-info}/RECORD

@@ -3,7 +3,7 @@ scaffold_ca_python/cli.py,sha256=A0h0pkoNPy3EE55lApnjRuevhWb_Aa-IB7jekaaiAcM,971
 scaffold_ca_python/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 scaffold_ca_python/commands/delete_module.py,sha256=DZa4rTVhPpt5-HV6dCZY-qWOV18K9qns6gKCsgjDepg,7124
 scaffold_ca_python/commands/generate_driven_adapter.py,sha256=ckHdHVUV5T3SSvLwPp_jQYdp-Av9j2AV836So6tMODk,6938
-scaffold_ca_python/commands/generate_entry_point.py,sha256=nSEz218Ar3WzkzOZOU_7DJ5KzEwGa7w6h9XVV2WQmOw,11943
+scaffold_ca_python/commands/generate_entry_point.py,sha256=iGO0sqq9B4XGRCgXLe0D3YfTzgeDBqZVXThSylPN05E,22665
 scaffold_ca_python/commands/generate_helper.py,sha256=i5zaqGvTO6nEvVOGVdOsZoDpJf1cWX7GbGaNcEYLSWY,4470
 scaffold_ca_python/commands/generate_model.py,sha256=I1dMNoVMNytdMZ5mzBAF1WzJDIHMacxwLOmhH29nTIc,4546
 scaffold_ca_python/commands/generate_pipeline.py,sha256=EYPM9csDnrYB3bpnC4YSycqI3bAE8bYy1283OEEC5Ts,5537
@@ -12,8 +12,9 @@ scaffold_ca_python/commands/generate_use_case.py,sha256=w6BUdF3uXeo3dNsLN76oSYvQ
 scaffold_ca_python/commands/update_project.py,sha256=cW9IuAF1yIFkAkzOJdioFv97wr7mRiid08KkqOlFmrM,2845
 scaffold_ca_python/commands/validate_structure.py,sha256=JF6Cb3IQ9d6VcjaReSHHzoXGSmqyoyMWNFplqSCFCOQ,2846
 scaffold_ca_python/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scaffold_ca_python/core/file_writer.py,sha256=DdgD6h4lx6FhKtc0AJvOIBryHgfTE4d4ZCMOfrEAuAI,5030
-scaffold_ca_python/core/module_builder.py,sha256=rcWSWxRX4bsaWLCtCHNTAcVFZiHABA5zTn9rilUojKE,5965
+scaffold_ca_python/core/file_writer.py,sha256=ff_5_UEB6vjzYwr6iLiIF3BWbSwNlZmvlnJVmYsRV8Q,6296
+scaffold_ca_python/core/mcp_tool_spec.py,sha256=1APkvaF-PX-wy5sMXtdU9Areha8h-mlQSXtWzPl1wBU,10609
+scaffold_ca_python/core/module_builder.py,sha256=oRUSpmZA3Q_Xno6e3R3e26eoK3REnuLMYJq8kQVyqz8,6518
 scaffold_ca_python/core/name_utils.py,sha256=OAMl4YrgvaZgulemcqYpUp8iHNvR8ieTrccNVc_zQB4,2765
 scaffold_ca_python/core/project_detector.py,sha256=G-n9domRQp65uzUbb7CXJk1nFMCTb347RMvfiVoYAxI,3321
 scaffold_ca_python/core/pyproject_writer.py,sha256=zpxgubt-XSZR5domgL4LG_9AWD9b_cNrDM8fuHmZRzE,7792
@@ -36,7 +37,7 @@ scaffold_ca_python/factory/simple/model_factory.py,sha256=HFIPO_B8UZco972rnoLYMw
 scaffold_ca_python/factory/simple/use_case_factory.py,sha256=-m1oFPbwfEGwiFJTf1RHIvw1WG7tG0IBuVfdpUYCbgQ,1961
 scaffold_ca_python/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 scaffold_ca_python/models/context.py,sha256=H-PuANo8Z8nSCcbnM9L6ATC6Ikuqt_SfYvI5Gsqo3F4,1916
-scaffold_ca_python/models/file_operation.py,sha256=Wy1rDdllw4j7RwFMgRE-xFlCwnJkmI6dQj3r-x4CSOk,1145
+scaffold_ca_python/models/file_operation.py,sha256=R5Tu3KBvUnSmH5QZXBQTPoQjvr4YdH1YOKsKS9ICH_Q,1698
 scaffold_ca_python/models/layer.py,sha256=5e11596xVV22HZnRv4r4TvEv-U6UKD08wATAh_UXXQU,1082
 scaffold_ca_python/models/violation.py,sha256=1FCNkfezEhmQ_ANn4KdAVAzLxYj8v4gwNuXH0FQPHmw,546
 scaffold_ca_python/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -66,7 +67,9 @@ scaffold_ca_python/templates/entry_point/mcp/server.py.jinja2,sha256=gVzJm_ugY9E
 scaffold_ca_python/templates/entry_point/mcp/test_app.py.jinja2,sha256=MjVDhAXTz35HcCOVTsaWA--qvD_Qyn2SNG99CF6wctk,967
 scaffold_ca_python/templates/entry_point/mcp/test_prompts.py.jinja2,sha256=Y9C7z7jpjoTKANlFB6hNJUUw2abt5qF2C4Nm7MkvDvA,1566
 scaffold_ca_python/templates/entry_point/mcp/test_resources.py.jinja2,sha256=2jHfPqyJ4TJZJupxe8T7gVz2ysaqZHcAog6186ie2CI,1763
+scaffold_ca_python/templates/entry_point/mcp/test_tool_stub.py.jinja2,sha256=Tq4uDcZc77bCC9gCVidmM5HmtjPfACaHBoQW0qEhIWo,295
 scaffold_ca_python/templates/entry_point/mcp/test_tools.py.jinja2,sha256=bd_8nvLuqPApKIYQoBhEokMYZrPYFUn1pnDEIOVxwCo,1550
+scaffold_ca_python/templates/entry_point/mcp/tool_stub.py.jinja2,sha256=VaGWAUF-BFQ7EeOHXUHQ2H-Mzr1UfbfziDsS7EVWUCc,289
 scaffold_ca_python/templates/entry_point/mcp/tools.py.jinja2,sha256=Eqxa-pc_Mf4L0QvWMefKeg43bnjxwYuaNXRg6I9H1pQ,753
 scaffold_ca_python/templates/entry_point/restapi/__init__.py.jinja2,sha256=BrpLExG7nc6cEOYWpJKymUXEvGVc1lU9sb_kBw_HPYg,36
 scaffold_ca_python/templates/entry_point/restapi/app.py.jinja2,sha256=HQQqi8ZiLTaNIt9g9_iJyjxAGt6KXj4lqGcJLI1Qx9s,2626
@@ -92,7 +95,7 @@ scaffold_ca_python/templates/project/gitignore.jinja2,sha256=ZRf2cRtqbe2d48RfWJW
 scaffold_ca_python/templates/project/layer_init.jinja2,sha256=oIlTSrce4ozqEKUU_1TB4473ufiE0SiGG_PJmEkT4FA,25
 scaffold_ca_python/templates/project/main.py.jinja2,sha256=di_ujhkFafXqJUymSdVjEF0tihQ_0xKbKSIyV91rPpk,161
 scaffold_ca_python/templates/project/mypy_ini.jinja2,sha256=SJ_UiLRZ8wBJ7hqSo3QDeMSsempBfaGvqiR_ASyIxR0,93
-scaffold_ca_python/templates/project/pyproject_toml.jinja2,sha256=O8G8S3f7rmRzQkjuRj2n_445bGD8fBDZu6S0QkwSzi0,1574
+scaffold_ca_python/templates/project/pyproject_toml.jinja2,sha256=7c2fpOc7lHxuItmW1NXdoCkYHp_lnswgx6NtHstk1Vw,1574
 scaffold_ca_python/templates/project/python_version.jinja2,sha256=Auc1s9_hwygz61ULf_j_oX9fK8P6HnuuYaj1o4g845g,5
 scaffold_ca_python/templates/project/application/config/__init__.py.jinja2,sha256=L9xWIW2Gd3VhRdx1RfUf7efBrIuFf3ft54eLQT1tG9g,32
 scaffold_ca_python/templates/project/application/config/config.py.jinja2,sha256=218sZQ1115odJcoI7W6-1kiFjkWjO56d80fqQXk4dyM,323
@@ -102,8 +105,8 @@ scaffold_ca_python/templates/project/application/config/resource_container.py.ji
 scaffold_ca_python/templates/project/application/config/usecases_container.py.jinja2,sha256=3fEHe6mkXkDHlfO5nhLqzLB7ccTpqwtjHZfLyfysbro,527
 scaffold_ca_python/templates/use_case/test_use_case.py.jinja2,sha256=3K1bNKDBQc29rcv8UHUZnROCUmcFSCwJhbm0xP9Uako,364
 scaffold_ca_python/templates/use_case/use_case.py.jinja2,sha256=KPtaK1wvZ-7qHdDZyuVfqXTPYwJdNUMPXQZGuKZFA7Y,217
-scaffold_ca_python-0.1.4.dist-info/METADATA,sha256=Uk7rsmYTy1wNQRZZVXquueaB2t-KUqrLpFJx52hIvLM,6803
-scaffold_ca_python-0.1.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-scaffold_ca_python-0.1.4.dist-info/entry_points.txt,sha256=4PyYg6mNCvAlt2yF_o1-QR2CBXiowYGpNyqcP88tu6I,104
-scaffold_ca_python-0.1.4.dist-info/licenses/LICENSE,sha256=3ZZEP7DK_h3lEjS8r-DvQCec2q7zAqqq7HmSq6cuL0E,1068
-scaffold_ca_python-0.1.4.dist-info/RECORD,,
+scaffold_ca_python-0.2.0.dist-info/METADATA,sha256=PKj8CVbANvsRzv3Ly7SelKv4krAlFbBRkXnv2NmTOnM,6960
+scaffold_ca_python-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+scaffold_ca_python-0.2.0.dist-info/entry_points.txt,sha256=4PyYg6mNCvAlt2yF_o1-QR2CBXiowYGpNyqcP88tu6I,104
+scaffold_ca_python-0.2.0.dist-info/licenses/LICENSE,sha256=3ZZEP7DK_h3lEjS8r-DvQCec2q7zAqqq7HmSq6cuL0E,1068
+scaffold_ca_python-0.2.0.dist-info/RECORD,,