crowdsec-local-mcp 0.1.0__py3-none-any.whl → 0.7.0.post1.dev0__py3-none-any.whl

crowdsec_local_mcp/prompts/prompt-waf-tests.txt

@@ -0,0 +1,101 @@
+You are an expert in generating automated test assets for the CrowdSec WAF harness. Given a Nuclei template and the name of the rule under test, produce the artifacts required by the docker-based test workflow. Focus exclusively on generating the test configuration (`config.yaml`) and the adapted Nuclei template that validates the rule blocks the attack with a `403` status code.
+
+## Test Artifact Guidelines
+
+1. **config.yaml**  
+   - Must be valid YAML with the keys `appsec-rules:` and `nuclei_template`.  
+   - `appsec-rules:` is a YAML list that always includes:  
+     - `./appsec-rules/crowdsecurity/base-config.yaml`  
+     - The path to the generated rule (e.g. `./appsec-rules/crowdsecurity/vpatch-CVE-2020-17496.yaml`).  
+   - `nuclei_template` is the filename of the adapted Nuclei template (e.g. `CVE-2020-17496.yaml`).
+
+2. **Adapted Nuclei Template**  
+   - Preserve the original request structure that exercises the vulnerability.  
+   - Normalise metadata so the template identifies itself as a test:  
+     - `info.name` matches the CVE identifier.  
+     - `info.author` is `crowdsec`.  
+     - `info.severity` is `info`.  
+     - `info.description` briefly states it is for testing (e.g. `CVE-2020-17496 testing`).  
+     - `info.tags` includes `appsec-testing`.  
+   - Keep payloads, raw requests, and helper fields that are required for the exploit to function.  
+   - Force the rule-under-test to respond with a block by ensuring the only matcher checks for HTTP status code `403`. Remove every other matcher from the original template.  
+   - When the original template lacks an explicit matcher, add a `matchers` block with a single status matcher for `403`.  
+   - If the template requires `cookie-reuse` or other execution flags, keep them intact.
+
+3. **General Expectations**  
+   - Do not attempt to regenerate the detection rule—only produce the two testing artifacts.  
+   - Respect YAML indentation (two spaces) and quote strings that contain special characters.  
+   - Mirror the case and structure of URIs, headers, and payloads from the input template.  
+   - Provide helpful inline comments only when strictly necessary to explain intentional failures.
+
+## Output Format
+
+Always return exactly two sections separated by delimiters:
+
+```
+===TEST_CONFIG===
+<config.yaml content>
+
+===TEST_NUCLEI===
+<adapted nuclei template content>
+```
+
+No additional sections or commentary should be emitted.
+
+## Example Input
+
+```yaml
+id: CVE-2020-17496
+
+info:
+  name: vBulletin 5.5.4 - 5.6.2- Remote Command Execution
+  author: pussycat0x
+  severity: critical
+  description: 'vBulletin versions 5.5.4 through 5.6.2 allow remote command execution via crafted subWidgets data in an ajax/render/widget_tabbedcontainer_tab_panel request. NOTE: this issue exists because of an incomplete fix for CVE-2019-16759.'
+
+http:
+  - raw:
+      - |
+        POST /ajax/render/widget_tabbedcontainer_tab_panel HTTP/1.1
+        Host: {{Hostname}}
+        Content-Type: application/x-www-form-urlencoded
+
+        subWidgets[0][template]=widget_php&subWidgets[0][config][code]=echo shell_exec('cat ../../../../../../../../../../../../etc/passwd'); exit;
+
+    matchers-condition: and
+    matchers:
+      - type: status
+        status:
+          - 200
+```
+
+## Example Output
+
+===TEST_CONFIG===
+appsec-rules:
+  - ./appsec-rules/crowdsecurity/base-config.yaml
+  - ./appsec-rules/crowdsecurity/vpatch-CVE-2020-17496.yaml
+nuclei_template: CVE-2020-17496.yaml
+
+===TEST_NUCLEI===
+id: CVE-2020-17496
+info:
+  name: CVE-2020-17496
+  author: crowdsec
+  severity: info
+  description: CVE-2020-17496 testing
+  tags: appsec-testing
+http:
+  - raw:
+      - |
+        POST /ajax/render/widget_tabbedcontainer_tab_panel HTTP/1.1
+        Host: {{Hostname}}
+        Content-Type: application/x-www-form-urlencoded
+
+        subWidgets[0][template]=widget_php&subWidgets[0][config][code]=echo shell_exec('cat ../../../../../../../../../../../../etc/passwd'); exit;
+
+    cookie-reuse: true
+    matchers:
+      - type: status
+        status:
+          - 403

crowdsec_local_mcp/prompts/prompt-waf-top-level.txt

@@ -0,0 +1,31 @@
+You are the top-level cyber security assistant for orchestrating CrowdSec AppSec WAF tasks. Treat this prompt as the first step whenever the user asks about creating, reviewing, testing, or deploying WAF rules so you can decide which specialized tool or prompt to invoke next.
+
+The process is the following, and it's CRITICAL to follow it unless asked otherwise by the user:
+
+1. **Validate User Intent**: Ensure that you understand user objective and that your rule will follow his directives.
+    - If the user provides a CVE, use `fetch_nuclei_exploit` to get a working nuclei template / exploit.
+    - If the user provides a natural language description, ask further question if necessary to be sure the rule will be specific enough.
+2. **Generate Initial Rule**: Refer to `get_waf_prompt` tool and prompt for syntax and guidelines. If you want everything bundled (main prompt + examples), call `generate_waf_rule` instead.
+3. **Validate Syntax**: Use the `validate_waf_rule` tool to check YAML syntax
+4. **Lint for Quality**: Use the `lint_waf_rule` tool to check for warnings and improvement hints
+5. **Iterate if Needed**: If validation fails or linter shows warnings, fix the issues and repeat steps 2-3
+6. **Final Output**: Only provide final output when both validation passes and linting shows no critical issues. Summarize results and link the user to next-step tooling options below.
+
+⚠️ Final Validation Checklist (REQUIRED before output ends):
+ - Confirm validation tool returns "✅ VALIDATION PASSED"
+ - Address all warnings from linting tool
+
+**IMPORTANT**: If validation or linting fails, you MUST iterate and fix the issues before providing the final output. Do not output rules that fail validation or have critical linting warnings.
+
+### After presenting **Final Output** to the user:
+
+Once you have successfully generated and validated a WAF rule, propose the user the next steps:
+ - Deploy the rule on a live instance:
+    - Use tool `manage_waf_stack`
+    - Allows you and the user to manually tests for false-positives and false-negatives
+ - Create and validate a test for the rule - allows contribution to the hub:
+    - Use tool `generate_waf_tests` to get instructions on test creation
+    - Use tool `run_waf_tests` to run and validate the tests
+    - Once done, you can suggest the user to open a PR to https://github.com/crowdsecurity/hub/
+ - Help the user to deploy the rule on his setup:
+    - Use tool `deploy_waf_rule` to get detailed instructions and  guide the user.

crowdsec_local_mcp/prompts/prompt-waf.txt

@@ -227,15 +227,6 @@ You are an expert in cybersecurity and threat detection, specializing in automat
               value: '/src/options.php'
 ```
 
-### Validation and Quality Assurance Process:
-**CRITICAL: You MUST follow this iterative validation process:**
-
-1. **Generate Initial Rule**: Create the detection rule following all guidelines above
-2. **Validate Syntax**: Use the `validate_waf_rule` tool to check YAML syntax
-3. **Lint for Quality**: Use the `lint_waf_rule` tool to check for warnings and improvement hints
-4. **Iterate if Needed**: If validation fails or linter shows warnings, fix the issues and repeat steps 2-3
-5. **Final Output**: Only provide final output when both validation passes and linting shows no critical issues
-
 ### Output Format with Delimiters:
 
 Output format (use the exact delimiters):
@@ -262,25 +253,8 @@ Output format (use the exact delimiters):
 
   - <verbatim output from linter tool>
 
-## Next Steps
-- Do you want me to test the WAF rule
-- Do you want some deployment guidance
 ```
 
-⚠️ Final Validation Checklist (REQUIRED before output ends):
- - Confirm validation tool returns "✅ VALIDATION PASSED"
- - Address all warnings from linting tool
- - Confirm all value: fields are lowercase
- - Confirm transform includes lowercase wherever applicable
- - Confirm no match.value contains capital letters
- - Confirm rule uses contains instead of regex when applicable
-
-**IMPORTANT**: If validation or linting fails, you MUST iterate and fix the issues before providing the final output. Do not output rules that fail validation or have critical linting warnings.
-
-### After Rule Generation and Validation:
-Once you have successfully generated and validated a WAF rule, remind the user that the next step is to deploy it. Use the `deploy_waf_rule` tool to provide comprehensive deployment instructions.
-
-
 ### Example Input (Nuclei Template):
 ```yaml
 id: CVE-2025-24893

crowdsec_local_mcp/setup_cli.py

@@ -0,0 +1,375 @@
+import argparse
+import json
+import os
+import platform
+import shlex
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Iterable
+
+SERVER_KEY = "crowdsec-local-mcp"
+SERVER_LABEL = "CrowdSecMCP"
+
+@dataclass
+class CLIArgs:
+    target: str
+    config_path: Path | None
+    dry_run: bool
+    force: bool
+    command_override: str | None
+    cwd_override: Path | None
+
+
+def main(argv: Iterable[str] | None = None) -> None:
+    args = _parse_args(argv)
+    command, cmd_args = _resolve_runner(args.command_override)
+    server_payload = {
+        "command": command,
+        "args": cmd_args,
+        "metadata": {
+            "label": SERVER_LABEL,
+            "description": "CrowdSec local MCP server",
+        },
+    }
+    if args.cwd_override:
+        server_payload["cwd"] = str(args.cwd_override)
+
+    if args.target == "stdio":
+        _print_stdio(server_payload)
+        return
+
+    if args.target == "claude-desktop":
+        _configure_claude(args, server_payload)
+    elif args.target == "claude-code":
+        _configure_claude_code(args, server_payload)
+    elif args.target == "chatgpt":
+        _configure_chatgpt(args, server_payload)
+    elif args.target == "vscode":
+        _configure_vscode(args, server_payload)
+    else:
+        raise ValueError(f"Unsupported target '{args.target}'")
+
+
+def _parse_args(argv: Iterable[str] | None) -> CLIArgs:
+    parser = argparse.ArgumentParser(
+        prog="init",
+        description=(
+            "Initialize CrowdSec MCP integration for supported clients "
+            "(Claude Desktop, Claude Code, ChatGPT Desktop, Visual Studio Code, or stdio)."
+        ),
+    )
+    parser.add_argument(
+        "target",
+        choices=("claude-desktop", "claude-code", "chatgpt", "vscode", "stdio"),
+        help="Client to configure.",
+    )
+    parser.add_argument(
+        "--config-path",
+        type=Path,
+        help="Override the configuration file path to update.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the resulting configuration instead of writing it.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Create configuration even if the file is missing.",
+    )
+    parser.add_argument(
+        "--command",
+        dest="command_override",
+        help=(
+            "Override the command used to launch the MCP server. "
+            "Defaults to 'uvx run --from crowdsec-local-mcp crowdsec-mcp' or "
+            "falls back to the current Python interpreter."
+        ),
+    )
+    parser.add_argument(
+        "--cwd",
+        dest="cwd_override",
+        type=Path,
+        help="Set the working directory used when launching the server.",
+    )
+
+    parsed = parser.parse_args(argv)
+    return CLIArgs(
+        target=parsed.target,
+        config_path=parsed.config_path,
+        dry_run=parsed.dry_run,
+        force=parsed.force,
+        command_override=parsed.command_override,
+        cwd_override=parsed.cwd_override,
+    )
+
+
+def _resolve_runner(command_override: str | None) -> tuple[str, list[str]]:
+    if command_override:
+        command_parts = command_override.strip().split()
+        if not command_parts:
+            raise ValueError("Command override cannot be empty.")
+        return command_parts[0], command_parts[1:]
+
+    for executable in ("uvx", "uv"):
+        resolved = shutil.which(executable)
+        if resolved:
+            return resolved, [
+                "--from",
+                "crowdsec-local-mcp",
+                "crowdsec-mcp",
+            ]
+
+    python_executable = sys.executable
+    if not python_executable:
+        raise RuntimeError(
+            "Unable to determine a Python interpreter to launch the MCP server."
+        )
+    return python_executable, ["-m", "crowdsec_local_mcp"]
+
+
+def _configure_claude(args: CLIArgs, server_payload: dict[str, object]) -> None:
+    config_path = _resolve_path(args.config_path, _claude_candidates())
+    _write_mcp_config(
+        config_path,
+        server_payload,
+        args,
+        client_name="Claude Desktop",
+    )
+
+
+def _configure_claude_code(args: CLIArgs, server_payload: dict[str, object]) -> None:
+    runner_command = server_payload["command"]
+    if not isinstance(runner_command, str):
+        raise TypeError("Server payload 'command' must be a string.")
+    runner_args = server_payload.get("args", [])
+    if not isinstance(runner_args, list):
+        raise TypeError("Server payload 'args' must be a list.")
+
+    claude_invocation = [
+        "claude",
+        "mcp",
+        "add",
+        "--transport",
+        "stdio",
+        "--scope",
+        "user",
+        SERVER_LABEL,
+        "--",
+        runner_command,
+        *runner_args,
+    ]
+    quoted_command = " ".join(shlex.quote(part) for part in claude_invocation)
+
+    if args.dry_run:
+        print(
+            "Run the following command to register CrowdSec MCP with Claude Code:\n"
+            f"{quoted_command}"
+        )
+        return
+
+    if shutil.which("claude") is None:
+        raise FileNotFoundError(
+            "The 'claude' CLI is not available on PATH. Install Claude Code CLI and "
+            f"run:\n{quoted_command}"
+        )
+
+    result = subprocess.run(claude_invocation, check=False)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"'claude mcp add' failed with exit code {result.returncode}. "
+            f"Run manually:\n{quoted_command}"
+        )
+    print("Registered CrowdSec MCP with Claude Code CLI.")
+
+
+def _configure_chatgpt(args: CLIArgs, server_payload: dict[str, object]) -> None:
+    config_path = _resolve_path(args.config_path, _chatgpt_candidates())
+    _write_mcp_config(
+        config_path,
+        server_payload,
+        args,
+        client_name="ChatGPT Desktop",
+    )
+
+
+def _configure_vscode(args: CLIArgs, server_payload: dict[str, object]) -> None:
+    config_path = _resolve_path(args.config_path, _vscode_candidates())
+    vscode_payload: dict[str, object] = {
+        "command": server_payload["command"],
+        "args": server_payload["args"],
+    }
+    if "cwd" in server_payload:
+        vscode_payload["cwd"] = server_payload["cwd"]
+    metadata = server_payload.get("metadata")
+    if isinstance(metadata, dict):
+        vscode_payload["metadata"] = metadata
+    _write_mcp_config(
+        config_path,
+        vscode_payload,
+        args,
+        client_name="Visual Studio Code",
+        servers_key="servers",
+    )
+
+
+def _write_mcp_config(
+    config_path: Path,
+    server_payload: dict[str, object],
+    args: CLIArgs,
+    *,
+    client_name: str,
+    servers_key: str = "mcpServers",
+) -> None:
+    manual_snippet = json.dumps(
+        {servers_key: {SERVER_KEY: server_payload}}, indent=2
+    )
+    config, existed = _load_json(
+        config_path,
+        allow_missing=True,
+        fallback_snippet=manual_snippet,
+    )
+    if config is None:
+        return
+    if not existed and not (args.force or args.dry_run):
+        raise FileNotFoundError(
+            f"{config_path} does not exist. Re-run with --force to create it "
+            "or provide --config-path pointing to an existing configuration file."
+        )
+    server_collection = config.setdefault(servers_key, {})
+    if not isinstance(server_collection, dict):
+        raise ValueError(f"Expected '{servers_key}' to be an object in {config_path}")
+
+    server_collection[SERVER_KEY] = server_payload
+
+    if args.dry_run:
+        print(json.dumps(config, indent=2))
+        return
+
+    _ensure_directory(config_path)
+    _backup_file_if_exists(config_path)
+    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    print(f"Configured {client_name} at {config_path}")
+
+
+def _print_stdio(server_payload: dict[str, object]) -> None:
+    snippet = {
+        "server": SERVER_KEY,
+        "command": server_payload["command"],
+        "args": server_payload["args"],
+    }
+    cwd = server_payload.get("cwd")
+    if cwd is not None:
+        snippet["cwd"] = cwd
+
+    snippet_json = json.dumps(snippet, indent=2)
+    print(
+        "Use the following configuration with stdio-compatible MCP clients:\n"
+        f"{snippet_json}"
+    )
+
+
+def _load_json(
+    path: Path,
+    *,
+    allow_missing: bool,
+    fallback_snippet: str | None = None,
+) -> tuple[dict[str, object] | None, bool]:
+    if not path.exists():
+        if allow_missing:
+            return {}, False
+        raise FileNotFoundError(f"Configuration file {path} does not exist.")
+
+    content = path.read_text(encoding="utf-8")
+    if not content.strip():
+        return {}, True
+
+    try:
+        return json.loads(content), True
+    except json.JSONDecodeError as exc:
+        manual_msg = (
+            f"Couldn't parse {path}: {exc}.\n"
+            "Edit it manually to add:\n\n"
+            f"{fallback_snippet or '<no snippet available>'}"
+        )
+        print(manual_msg)
+        return None, True
+
+
+def _resolve_path(explicit: Path | None, candidates: list[Path]) -> Path:
+    if explicit:
+        return explicit.expanduser()
+
+    expanded = [candidate.expanduser() for candidate in candidates]
+    for candidate in expanded:
+        if candidate.exists():
+            return candidate
+
+    if expanded:
+        return expanded[0]
+
+    raise ValueError("No configuration path candidates were provided.")
+
+
+def _ensure_directory(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _backup_file_if_exists(path: Path) -> None:
+    if not path.exists():
+        return
+    backup_path = path.with_suffix(path.suffix + ".bak")
+    shutil.copy2(path, backup_path)
+    print(f"Existing configuration backed up to {backup_path}")
+
+
+def _claude_candidates() -> list[Path]:
+    system = platform.system()
+    if system == "Darwin":
+        return [
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "Claude"
+            / "claude_desktop_config.json"
+        ]
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home()))
+        return [base / "Claude" / "claude_desktop_config.json"]
+    return [Path.home() / ".config" / "Claude" / "claude_desktop_config.json"]
+
+
+def _chatgpt_candidates() -> list[Path]:
+    system = platform.system()
+    if system == "Darwin":
+        return [
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "ChatGPT"
+            / "config.json"
+        ]
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home()))
+        return [base / "ChatGPT" / "config.json"]
+    return [Path.home() / ".config" / "ChatGPT" / "config.json"]
+
+
+def _vscode_candidates() -> list[Path]:
+    system = platform.system()
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home()))
+        return [base / "Code" / "User" / "mcp.json", base / "Code - Insiders" / "User" / "mcp.json"]
+    if system == "Darwin":
+        base = Path.home() / "Library" / "Application Support"
+        return [base / "Code" / "User" / "mcp.json", base / "Code - Insiders" / "User" / "mcp.json"]
+    # Linux and others
+    base = Path.home() / ".config"
+    return [base / "Code" / "User" / "mcp.json", base / "Code - Insiders" / "User" / "mcp.json"]
+
+if __name__ == "__main__":
+    main()

crowdsec_local_mcp-0.7.0.post1.dev0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: crowdsec-local-mcp
+Version: 0.7.0.post1.dev0
+Summary: An MCP exposing prompts and tools to help users write WAF rules, scenarios etc.
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.25.1
+Requires-Dist: mcp>=1.15.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.32.5
+Dynamic: license-file
+
+<p align="center">
+<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/crowdsec_logo.png" alt="CrowdSec" title="CrowdSec" width="400" height="260"/>
+</p>
+
+
+**Life is too short to write YAML, just ask nicely!**
+
+> A Model Context Protocol (MCP) server to generate, validate, and deploy CrowdSec WAF rules & Scenarios.
+
+
+## Features
+
+### WAF Rules Features
+
+- **WAF Rule Generation**: Generate CrowdSec WAF rules from user input or a CVE reference
+- **Validation**: Validate syntaxical correctness of WAF rules
+- **Linting**: Get warnings and hints to improve your WAF rules
+- **Deployment Guide**: Step-by-step deployment instructions
+- **Docker Test Harness**: Spin up CrowdSec + nginx + bouncer to exercise rules for false positives/negatives
+- **Nuclei Lookup**: Quickly jump to existing templates in the official `projectdiscovery/nuclei-templates` repository for a given CVE
+
+### Scenarios Features
+
+- **CrowdSec Scenarios Generation**: Generate CrowdSec scenarios
+- **Validation**: Validate syntaxical correctness of scenarios
+- **Linting**: Get warnings and hints to improve your scenarios
+- **Deployment Guide**: Step-by-step deployment instructions
+- **Docker Test Harness**: Spin up CrowdSec to test scenario behavior
+
+## Demo
+
+### WAF Rules Creation and testing
+
+ - [Rule creation from natural language](https://claude.ai/share/f0f246b2-6b20-4d70-a16c-c6b627ab2d80)
+ - [Rule creation from CVE reference](https://claude.ai/share/b6599407-82dd-443c-a12d-9a9825ed99df)
+
+### Scenario Creation and testing
+
+ - [Rule creation on HTTP events](https://claude.ai/share/3658165a-5636-4a7e-8043-01e7a7517200)
+ - [Rule creation based on GeoLocation factors](https://claude.ai/share/ff154e66-3c1a-44e6-a464-b694f65bd67e)
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) 0.4 or newer, which provides the `uvx` runner used in the examples below.
+- Docker with the Compose plugin (Compose v2).
+
+## Installation
+
+You can install the MCP using `uvx` **or** use packaged `.mcpb` file for claude code.
+
+### Using `.mcpb` package
+
+If you're using `claude desktop`, you can configure the MCP directly by double-clicking the `.mcpb` file that accompanies the release.
+
+> [!IMPORTANT]
+> On MacOS, configure `uv` path in the extension settings if `uv` isn't installed in the standard path. 
+
+### Using `uvx`
+
+- Configure supported clients automatically with `uvx --from crowdsec-local-mcp init <client>`, where `<client>` is one of `claude-desktop`, `claude-code`, `chatgpt`, `vscode`, or `stdio`:
+
+```bash
+uvx --from crowdsec-local-mcp init --dry-run claude-code
+```
+
+Run `uvx --from crowdsec-local-mcp init --help` to see all flags and supported targets.
+
+#### What `init` configures
+
+The `init` helper writes the CrowdSec MCP server definition into the client’s JSON configuration:
+
+- `claude-desktop` → `claude_desktop_config.json` in the Claude Desktop settings directory
+- `claude-code` → invoke `claude mcp` command with needed args
+- `chatgpt` → `config.json` in the ChatGPT Desktop settings directory
+- `vscode` → `mcp.json` for VS Code (stable and insiders are both detected)
+
+If the client's configuration file already exists, a `.bak` backup is created before the MCP server block is updated. When the file is missing you can either pass `--force` to create it, or point `--config-path` to a custom location. Combine `--dry-run` with these options to preview the JSON without making any changes.
+
+By default the CLI launches the server with `uvx --from crowdsec-local-mcp crowdsec-mcp`. If neither `uvx` nor `uv` is available, it falls back to your current Python interpreter; you can override the executable with `--command` and the working directory with `--cwd`.
+
+#### Using the `stdio` target
+
+`stdio` does not modify any files. Instead, `init stdio` prints a ready-to-paste JSON snippet that you can drop into any stdio-compatible MCP client configuration. This is useful when you want to manually wire the server into tools that do not have built-in automation support yet.
+
+## Troubleshooting
+
+If you just installed the mcp extension via `.mcpb` and `uv` or `uvx` isn't in the standard path, check the extension settings to configure `uv` path.
+
+## Logging
+
+- The MCP server writes its log file to your operating system's temporary directory. On Linux/macOS this is typically `/tmp/crowdsec-mcp.log`; on Windows it resolves via `%TEMP%\crowdsec-mcp.log`.