Feature/mcp

Dockerfile.mcp

@@ -0,0 +1,18 @@
+FROM python:3.11.6-alpine
+LABEL maintainer="jsdgfasjkhd@proton.me"
+
+WORKDIR /root/
+ADD . /root/
+
+RUN apk add \
+    gcc \
+    musl-dev \
+    libffi-dev \
+    openssl-dev
+
+RUN pip install -r requirements.txt
+RUN pip install -r requirements/mcp.txt
+RUN chmod +x dirsearch.py
+
+ENTRYPOINT ["./dirsearch.py"]
+CMD ["--help"]

README.md

@@ -29,6 +29,7 @@ Table of Contents
 - [Options](#options)
 - [Configuration](#configuration)
 - [How to use](#how-to-use)
+- [MCP mode](#mcp-mode)
 - [Session Management](#session-management)
 - [Support Docker](#support-docker)
 - [Building from Source](#building-from-source)
@@ -674,6 +675,96 @@ python3 dirsearch.py -u https://target --header-list rate-limit-bypasses.txt
 </details>
 
 
+MCP mode
+---------------
+
+dirsearch can run as a [FastMCP](https://fastmcp.wiki/en/getting-started/welcome) server so AI agents can invoke scans through MCP tools.
+
+FastMCP v2 requires Python 3.10+. Install the optional MCP dependency first:
+
+```
+pip install -r requirements/mcp.txt
+```
+
+For packaged installs, use `pip install ".[mcp]"`.
+
+### STDIO transport
+
+STDIO is the default and recommended local mode. It does not listen on a network port and does not require a token.
+
+```
+python3 dirsearch.py --mcp
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "dirsearch": {
+      "command": "python3",
+      "args": ["/path/to/dirsearch.py", "--mcp"]
+    }
+  }
+}
+```
+
+### HTTP transport
+
+HTTP mode is optional. It runs as a local server on `127.0.0.1:8000`.
+
+```
+python3 dirsearch.py --mcp --mcp-transport http
+```
+
+### HTTP Authentication
+
+By default, HTTP mode runs without authentication. Enable bearer token protection with `--mcp-token`:
+
+```
+# Use your own token
+python3 dirsearch.py --mcp --mcp-transport http --mcp-token "your-secret-token"
+
+# Auto-generate a random token
+python3 dirsearch.py --mcp --mcp-transport http --mcp-token
+```
+
+When using `--mcp-token` without a value, a secure random token (32 bytes) is automatically generated and printed to stderr. Clients must include `Authorization: Bearer <token>` in their requests.
+
+Custom bind options:
+
+```
+python3 dirsearch.py --mcp --mcp-transport http --mcp-host 127.0.0.1 --mcp-port 8000 --mcp-path /mcp/
+```
+
+Example MCP client configuration (for clients supporting HTTP remote with auth):
+
+```json
+{
+  "mcpServers": {
+    "dirsearch": {
+      "url": "http://127.0.0.1:8000/mcp/",
+      "headers": {
+        "Authorization": "Bearer <YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+
+### MCP tools
+
+The server exposes two tools:
+
+- `dirsearch_scan`: structured common options such as `url`, `wordlists`, `extensions`, `threads`, `recursive`, `include_status`, `exclude_status`, `headers`, `timeout`, and `max_time`.
+- `dirsearch_scan_cli`: raw dirsearch CLI argument list for advanced usage, for example `["-u", "https://example.com", "-e", "php,js", "-w", "db/dicc.txt", "--recursive"]`.
+
+MCP-managed output is always JSON. The server writes a temporary report, reads it, returns the parsed result to the AI client, and deletes the temporary file. Final report formatting or long-term saving is left to the AI agent or workflow.
+
+For safety, raw CLI mode strips output/session/interactive flags such as `-o`, `--output-file`, `-O`, `--output-formats`, `--mysql-url`, `--postgres-url`, `--log`, `--stdin`, `--session`, `--session-id`, and `--list-sessions`; MCP controls JSON output internally.
+
+
 Session Management
 ---------------
 
@@ -768,11 +859,34 @@ docker build -t "dirsearch:v0.4.3" .
 > **dirsearch** is the name of the image and **v0.4.3** is the version
 
 ### Using dirsearch
+
 For using
 ```sh
 docker run -it --rm "dirsearch:v0.4.3" -u target -e php,html,js,zip
 ```
 
+### Building MCP-Supported Image
+
+For MCP mode support, build using the specific file:
+
+```sh
+docker build -f Dockerfile.mcp -t "dirsearch:mcp" .
+```
+
+### Using MCP with Docker
+
+Once the image is built, you can use it with MCP clients:
+
+**STDIO mode:**
+```sh
+docker run -it --rm "dirsearch:mcp" --mcp
+```
+
+**HTTP mode (with custom auth token):**
+```sh
+docker run -it --rm -p 8000:8000 "dirsearch:mcp" --mcp --mcp-transport http --mcp-token "your-secret-token"
+```
+
 </details>
 
 

dirsearch.py

@@ -20,15 +20,25 @@
 
 import sys
 
-from lib.core.data import options
-from lib.core.options import parse_options
-
 if sys.version_info < (3, 9):
     sys.stderr.write("Sorry, dirsearch requires Python 3.9 or higher\n")
     sys.exit(1)
 
 
 def main():
+    if "--mcp" in sys.argv:
+        from lib.mcp.server import MCPConfigurationError, main as mcp_main
+
+        try:
+            mcp_main(sys.argv[1:])
+        except MCPConfigurationError as e:
+            sys.stderr.write(f"{e}\n")
+            sys.exit(1)
+        return
+
+    from lib.core.data import options
+    from lib.core.options import parse_options
+
     options.update(parse_options())
 
     if options["session_file"]:

lib/core/settings.py

@@ -192,3 +192,9 @@ def _get_default_session_dir() -> str:
 URL_SAFE_CHARS = string.punctuation
 
 TEXT_CHARS = bytearray({7, 8, 9, 10, 12, 13, 27} | set(range(0x20, 0x100)) - {0x7F})
+
+# MCP Server Defaults
+MCP_DEFAULT_TRANSPORT = "stdio"
+MCP_DEFAULT_HOST = "127.0.0.1"
+MCP_DEFAULT_PORT = 8000
+MCP_DEFAULT_PATH = "/mcp/"

lib/mcp/__init__.py

@@ -0,0 +1 @@
+