data-filter-mcp 0.2.1__tar.gz → 0.2.4__tar.gz

data_filter_mcp-0.2.4/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: data-filter-mcp
+Version: 0.2.4
+Summary: Local MCP server for running restricted Python text filters over files
+Author: Aleksei Arakelian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/alxark/data-filter-mcp
+Project-URL: Repository, https://github.com/alxark/data-filter-mcp
+Project-URL: Issues, https://github.com/alxark/data-filter-mcp/issues
+Keywords: mcp,model-context-protocol,filter,python,server
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2.0,>=1.12
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Dynamic: license-file
+
+# data-filter-mcp
+
+Local MCP server that registers restricted Python filters and runs them against local `json`, `yaml`, and `txt` files.
+
+## What it does
+
+- `register_filter` accepts Python source code with exactly one top-level function: `def filter_item(data):`
+- `run_filter` loads a local file, passes the loaded document into `filter_item(data)`, and returns the text from `result_text`
+- `convert_file` loads a local file, passes it into `filter_item(data)`, and writes the returned text to another local file
+- Registered filters live only in memory and expire automatically based on server TTL settings
+
+### What filter code may use
+
+Filter bodies are AST-validated against a whitelist. In addition to a curated set of builtins (`len`, `sorted`, `max`, `min`, `range`, `enumerate`, `zip`, `sum`, `any`, `all`, conversions, etc.) and safe string/dict/list methods, filters may also use a curated set of standard-library modules. Modules are exposed by their canonical names (`math`, `datetime`, `hashlib`, etc.). Filesystem, process, network, and unsafe serialization modules (`os`, `pathlib`, `shutil`, `subprocess`, `socket`, `urllib`, `pickle`, etc.) are intentionally not available.
+
+- **`lambda` expressions** — typically as `key=` arguments, e.g. `sorted(data, key=lambda item: item.get("score"))`. Lambda bodies are validated by the same rules as the rest of the filter.
+- **`json`** — `json.loads`, `json.dumps`.
+- **`yaml`** — `yaml.safe_load`, `yaml.safe_dump`. The unsafe `yaml.load` / `yaml.dump` are intentionally not exposed.
+- **`re`** — `re.match`, `re.search`, `re.fullmatch`, `re.findall`, `re.sub`, `re.subn`, `re.compile`, `re.escape`, plus `Match` / `Pattern` methods (`group`, `groups`, `groupdict`, `start`, `end`, `span`).
+- **`math`** — numeric helpers such as `math.ceil`, `math.floor`, `math.sqrt`, `math.log`, `math.exp`, `math.pow`, `math.factorial`, `math.gcd`, `math.lcm`, `math.isfinite`, `math.isclose`.
+- **`statistics`** — aggregates such as `statistics.mean`, `statistics.median`, `statistics.stdev`, `statistics.variance`, `statistics.quantiles`.
+- **`datetime`** — `datetime.datetime.fromisoformat`, `datetime.datetime.now`, `datetime.timedelta`, `datetime.timezone.utc`, and instance methods such as `isoformat`, `strftime`, `timestamp`, `weekday`, `total_seconds`. General instance attribute reads such as `dt.year` and `dt.month` are not supported by the current policy.
+- **`decimal`** — `decimal.Decimal(...)`, `quantize`, `normalize`, `to_eng_string`, `to_integral_value`.
+- **`collections`** — `collections.Counter`, `collections.defaultdict`, `collections.OrderedDict`, `collections.deque`, plus methods such as `most_common`, `elements`, `popleft`, `appendleft`, `rotate`.
+- **`itertools`** — `chain`, `chain.from_iterable`, `islice`, `takewhile`, `dropwhile`, `groupby`, `starmap`, `accumulate`, `combinations`, `permutations`, `product`, `filterfalse`.
+- **`functools`** — `reduce`, `partial`, `cmp_to_key`, `wraps`. Caching decorators such as `lru_cache` and `cache` are intentionally not exposed because they can retain process-local state across filter calls.
+- **`operator`** — `itemgetter`, `methodcaller`, and arithmetic/comparison helpers such as `add`, `mul`, `lt`, `eq`, `gt`. `attrgetter` is intentionally not exposed.
+- **`textwrap`** — `fill`, `wrap`, `shorten`, `indent`, `dedent`.
+- **`html`** — `html.escape`, `html.unescape`.
+- **`base64`** — `b64encode`, `b64decode`, `urlsafe_b64encode`, `urlsafe_b64decode`, `b32encode`, `b32decode`, `b16encode`, `b16decode`.
+- **`hashlib`** — `hashlib.sha256`, `hashlib.sha1`, `hashlib.md5`, `hashlib.blake2b`, `hashlib.new`, plus hash object methods such as `hexdigest`, `digest`, `update`.
+- **`ipaddress`** — `ip_address`, `ip_network`, `ip_interface`, `IPv4Network`, `IPv6Network`, plus methods such as `supernet`, `subnets`, `hosts`, `overlaps`, `subnet_of`, `supernet_of`. General instance attribute reads such as `addr.is_private` and `addr.compressed` are not supported by the current policy.
+- **`unicodedata`** — `category`, `name`, `lookup`, `numeric`, `digit`, `decimal`, `bidirectional`, `combining`, `mirrored`.
+- **`difflib`** — `get_close_matches`, `ndiff`, `unified_diff`, `context_diff`, `SequenceMatcher`.
+
+Note: `re.compile` runs against patterns supplied by filter code, so a pathological pattern can stall the server (ReDoS). Some helpers such as `difflib.SequenceMatcher` can also be CPU-heavy on large inputs. Treat filter source as trusted-but-restricted.
+
+## Run with uvx
+
+After publishing to PyPI, start the server with:
+
+```bash
+uvx data-filter-mcp --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+```
+
+Show the available CLI flags with:
+
+```bash
+uvx data-filter-mcp --help
+```
+
+### Restricting file access with `--workdir`
+
+By default the server can read any file on the local filesystem. Use one or
+more `--workdir` flags to restrict file reads to specific directories:
+
+```bash
+uvx data-filter-mcp \
+  --filter-ttl-seconds 3600 \
+  --cleanup-interval-seconds 60 \
+  --workdir /Users/me/project \
+  --workdir /tmp/data
+```
+
+Rules:
+- Each `--workdir` value must be an **absolute path** to an existing directory.
+- `run_filter` will only accept files located inside the allowed directories.
+- If no `--workdir` flags are provided, no restrictions are applied (backward compatible).
+- `convert_file` always requires at least one `--workdir` because it writes to disk.
+- `convert_file` requires the destination path to be inside an allowed workdir.
+- `convert_file` creates missing destination parent directories automatically.
+- `convert_file` refuses to replace an existing destination file unless `overwrite` is `true`.
+
+### Writing transformed files with `convert_file`
+
+Use `convert_file` when the filtered output should be persisted instead of returned
+inline to the model. The tool accepts:
+
+- `filter_id` — an identifier returned by `register_filter`
+- `source_file_path` — absolute path to the json/yaml/txt file to load
+- `destination_file_path` — absolute path where the returned text should be saved
+- `file_type` — optional source file type override (`json`, `yaml`, or `txt`)
+- `overwrite` — optional boolean, default `false`
+
+Example flow:
+
+```python
+def filter_item(data):
+    return "\n".join(data["items"])
+```
+
+Then call `convert_file` with a source such as `/tmp/data/items.json` and a
+destination such as `/tmp/data/out/items.txt`. The result is written as UTF-8
+text. The returned metadata includes the resolved source and destination paths,
+the effective source file type, `bytes_written`, and whether an existing file was
+overwritten.
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "data-filter": {
+      "command": "uvx",
+      "args": [
+        "data-filter-mcp",
+        "--filter-ttl-seconds",
+        "3600",
+        "--cleanup-interval-seconds",
+        "60",
+        "--workdir",
+        "/Users/me/project",
+        "--workdir",
+        "/tmp/data"
+      ]
+    }
+  }
+}
+```
+
+## Run locally
+
+```bash
+python server.py --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+python -m data_filter_mcp.server --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+.venv/bin/data-filter-mcp --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+```

data_filter_mcp-0.2.4/README.md

@@ -0,0 +1,127 @@
+# data-filter-mcp
+
+Local MCP server that registers restricted Python filters and runs them against local `json`, `yaml`, and `txt` files.
+
+## What it does
+
+- `register_filter` accepts Python source code with exactly one top-level function: `def filter_item(data):`
+- `run_filter` loads a local file, passes the loaded document into `filter_item(data)`, and returns the text from `result_text`
+- `convert_file` loads a local file, passes it into `filter_item(data)`, and writes the returned text to another local file
+- Registered filters live only in memory and expire automatically based on server TTL settings
+
+### What filter code may use
+
+Filter bodies are AST-validated against a whitelist. In addition to a curated set of builtins (`len`, `sorted`, `max`, `min`, `range`, `enumerate`, `zip`, `sum`, `any`, `all`, conversions, etc.) and safe string/dict/list methods, filters may also use a curated set of standard-library modules. Modules are exposed by their canonical names (`math`, `datetime`, `hashlib`, etc.). Filesystem, process, network, and unsafe serialization modules (`os`, `pathlib`, `shutil`, `subprocess`, `socket`, `urllib`, `pickle`, etc.) are intentionally not available.
+
+- **`lambda` expressions** — typically as `key=` arguments, e.g. `sorted(data, key=lambda item: item.get("score"))`. Lambda bodies are validated by the same rules as the rest of the filter.
+- **`json`** — `json.loads`, `json.dumps`.
+- **`yaml`** — `yaml.safe_load`, `yaml.safe_dump`. The unsafe `yaml.load` / `yaml.dump` are intentionally not exposed.
+- **`re`** — `re.match`, `re.search`, `re.fullmatch`, `re.findall`, `re.sub`, `re.subn`, `re.compile`, `re.escape`, plus `Match` / `Pattern` methods (`group`, `groups`, `groupdict`, `start`, `end`, `span`).
+- **`math`** — numeric helpers such as `math.ceil`, `math.floor`, `math.sqrt`, `math.log`, `math.exp`, `math.pow`, `math.factorial`, `math.gcd`, `math.lcm`, `math.isfinite`, `math.isclose`.
+- **`statistics`** — aggregates such as `statistics.mean`, `statistics.median`, `statistics.stdev`, `statistics.variance`, `statistics.quantiles`.
+- **`datetime`** — `datetime.datetime.fromisoformat`, `datetime.datetime.now`, `datetime.timedelta`, `datetime.timezone.utc`, and instance methods such as `isoformat`, `strftime`, `timestamp`, `weekday`, `total_seconds`. General instance attribute reads such as `dt.year` and `dt.month` are not supported by the current policy.
+- **`decimal`** — `decimal.Decimal(...)`, `quantize`, `normalize`, `to_eng_string`, `to_integral_value`.
+- **`collections`** — `collections.Counter`, `collections.defaultdict`, `collections.OrderedDict`, `collections.deque`, plus methods such as `most_common`, `elements`, `popleft`, `appendleft`, `rotate`.
+- **`itertools`** — `chain`, `chain.from_iterable`, `islice`, `takewhile`, `dropwhile`, `groupby`, `starmap`, `accumulate`, `combinations`, `permutations`, `product`, `filterfalse`.
+- **`functools`** — `reduce`, `partial`, `cmp_to_key`, `wraps`. Caching decorators such as `lru_cache` and `cache` are intentionally not exposed because they can retain process-local state across filter calls.
+- **`operator`** — `itemgetter`, `methodcaller`, and arithmetic/comparison helpers such as `add`, `mul`, `lt`, `eq`, `gt`. `attrgetter` is intentionally not exposed.
+- **`textwrap`** — `fill`, `wrap`, `shorten`, `indent`, `dedent`.
+- **`html`** — `html.escape`, `html.unescape`.
+- **`base64`** — `b64encode`, `b64decode`, `urlsafe_b64encode`, `urlsafe_b64decode`, `b32encode`, `b32decode`, `b16encode`, `b16decode`.
+- **`hashlib`** — `hashlib.sha256`, `hashlib.sha1`, `hashlib.md5`, `hashlib.blake2b`, `hashlib.new`, plus hash object methods such as `hexdigest`, `digest`, `update`.
+- **`ipaddress`** — `ip_address`, `ip_network`, `ip_interface`, `IPv4Network`, `IPv6Network`, plus methods such as `supernet`, `subnets`, `hosts`, `overlaps`, `subnet_of`, `supernet_of`. General instance attribute reads such as `addr.is_private` and `addr.compressed` are not supported by the current policy.
+- **`unicodedata`** — `category`, `name`, `lookup`, `numeric`, `digit`, `decimal`, `bidirectional`, `combining`, `mirrored`.
+- **`difflib`** — `get_close_matches`, `ndiff`, `unified_diff`, `context_diff`, `SequenceMatcher`.
+
+Note: `re.compile` runs against patterns supplied by filter code, so a pathological pattern can stall the server (ReDoS). Some helpers such as `difflib.SequenceMatcher` can also be CPU-heavy on large inputs. Treat filter source as trusted-but-restricted.
+
+## Run with uvx
+
+After publishing to PyPI, start the server with:
+
+```bash
+uvx data-filter-mcp --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+```
+
+Show the available CLI flags with:
+
+```bash
+uvx data-filter-mcp --help
+```
+
+### Restricting file access with `--workdir`
+
+By default the server can read any file on the local filesystem. Use one or
+more `--workdir` flags to restrict file reads to specific directories:
+
+```bash
+uvx data-filter-mcp \
+  --filter-ttl-seconds 3600 \
+  --cleanup-interval-seconds 60 \
+  --workdir /Users/me/project \
+  --workdir /tmp/data
+```
+
+Rules:
+- Each `--workdir` value must be an **absolute path** to an existing directory.
+- `run_filter` will only accept files located inside the allowed directories.
+- If no `--workdir` flags are provided, no restrictions are applied (backward compatible).
+- `convert_file` always requires at least one `--workdir` because it writes to disk.
+- `convert_file` requires the destination path to be inside an allowed workdir.
+- `convert_file` creates missing destination parent directories automatically.
+- `convert_file` refuses to replace an existing destination file unless `overwrite` is `true`.
+
+### Writing transformed files with `convert_file`
+
+Use `convert_file` when the filtered output should be persisted instead of returned
+inline to the model. The tool accepts:
+
+- `filter_id` — an identifier returned by `register_filter`
+- `source_file_path` — absolute path to the json/yaml/txt file to load
+- `destination_file_path` — absolute path where the returned text should be saved
+- `file_type` — optional source file type override (`json`, `yaml`, or `txt`)
+- `overwrite` — optional boolean, default `false`
+
+Example flow:
+
+```python
+def filter_item(data):
+    return "\n".join(data["items"])
+```
+
+Then call `convert_file` with a source such as `/tmp/data/items.json` and a
+destination such as `/tmp/data/out/items.txt`. The result is written as UTF-8
+text. The returned metadata includes the resolved source and destination paths,
+the effective source file type, `bytes_written`, and whether an existing file was
+overwritten.
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "data-filter": {
+      "command": "uvx",
+      "args": [
+        "data-filter-mcp",
+        "--filter-ttl-seconds",
+        "3600",
+        "--cleanup-interval-seconds",
+        "60",
+        "--workdir",
+        "/Users/me/project",
+        "--workdir",
+        "/tmp/data"
+      ]
+    }
+  }
+}
+```
+
+## Run locally
+
+```bash
+python server.py --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+python -m data_filter_mcp.server --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+.venv/bin/data-filter-mcp --filter-ttl-seconds 3600 --cleanup-interval-seconds 60
+```

{data_filter_mcp-0.2.1 → data_filter_mcp-0.2.4}/data_filter_mcp/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)
 
-__commit_id__ = commit_id = 'ge560d71c2'
+__commit_id__ = commit_id = 'gd2ae7c43f'

{data_filter_mcp-0.2.1 → data_filter_mcp-0.2.4}/data_filter_mcp/models.py

@@ -41,6 +41,30 @@ class RunFilterResult(BaseModel):
     result_text: str = Field(description="Exact text returned by filter_item(data).")
 
 
+class ConvertFileResult(BaseModel):
+    filter_id: str = Field(
+        description="Identifier of the registered filter that produced this file."
+    )
+    source_file_path: str = Field(
+        description="Resolved absolute path of the processed source file."
+    )
+    destination_file_path: str = Field(
+        description="Resolved absolute path where the result text was written."
+    )
+    file_type: str = Field(
+        description="Effective loader type used for the source file. One of: json, yaml, txt."
+    )
+    expires_at: str = Field(
+        description="UTC timestamp in ISO 8601 format when this filter expires."
+    )
+    bytes_written: int = Field(
+        description="Number of UTF-8 bytes written to the destination file."
+    )
+    overwritten: bool = Field(
+        description="Whether an existing destination file was replaced."
+    )
+
+
 @dataclass(slots=True)
 class RegisteredFilter:
     filter_id: str

{data_filter_mcp-0.2.1 → data_filter_mcp-0.2.4}/data_filter_mcp/server.py

@@ -9,7 +9,7 @@ from mcp.server.fastmcp import FastMCP
 from pydantic import Field
 
 from .loaders.factory import load_document
-from .models import RegisterFilterResult, RunFilterResult
+from .models import ConvertFileResult, RegisterFilterResult, RunFilterResult
 from .registry import FilterExpiredError, FilterNotFoundError, FilterRegistry
 from .validator import POLICY_VERSION, FilterValidationError, compile_filter
 
@@ -88,6 +88,47 @@ class FilterService:
 
         return resolved
 
+    def _resolve_destination_file_path(self, file_path: str) -> Path:
+        candidate = Path(file_path)
+        if not candidate.is_absolute():
+            raise ValueError(
+                f"destination_file_path must be an absolute path: {file_path}"
+            )
+
+        if not self._workdirs:
+            raise ValueError(
+                "convert_file requires at least one --workdir to be configured"
+            )
+
+        try:
+            resolved = candidate.expanduser().resolve(strict=False)
+        except OSError as exc:
+            raise ValueError(f"Cannot resolve destination path: {file_path}") from exc
+
+        if not any(resolved == wd or wd in resolved.parents for wd in self._workdirs):
+            raise ValueError(f"Destination path is outside allowed workdirs: {resolved}")
+
+        if resolved.exists() and resolved.is_dir():
+            raise ValueError(f"Destination path is a directory: {resolved}")
+
+        return resolved
+
+    def _ensure_destination_parent_allowed(self, destination: Path) -> None:
+        try:
+            resolved_parent = destination.parent.resolve(strict=True)
+        except OSError as exc:
+            raise ValueError(
+                f"Cannot resolve destination parent directory: {destination.parent}"
+            ) from exc
+
+        if not any(
+            resolved_parent == wd or wd in resolved_parent.parents
+            for wd in self._workdirs
+        ):
+            raise ValueError(
+                f"Destination parent is outside allowed workdirs: {resolved_parent}"
+            )
+
     def run_filter(
         self,
         filter_id: str,
@@ -114,6 +155,52 @@ class FilterService:
             result_text=result,
         )
 
+    def convert_file(
+        self,
+        filter_id: str,
+        source_file_path: str,
+        destination_file_path: str,
+        file_type: Literal["json", "yaml", "txt"] | None = None,
+        overwrite: bool = False,
+    ) -> ConvertFileResult:
+        try:
+            entry = self._registry.get(filter_id)
+        except (FilterNotFoundError, FilterExpiredError) as exc:
+            raise ValueError(str(exc)) from exc
+
+        resolved_source = self._resolve_allowed_file_path(source_file_path)
+        resolved_destination = self._resolve_destination_file_path(destination_file_path)
+
+        if resolved_source == resolved_destination:
+            raise ValueError("source and destination paths must differ")
+
+        will_overwrite = resolved_destination.exists()
+        if will_overwrite and not overwrite:
+            raise ValueError(
+                "Destination file already exists (set overwrite=true to replace): "
+                f"{resolved_destination}"
+            )
+
+        document, resolved_file_type = load_document(resolved_source, file_type)
+        result = entry.function(document)
+        if not isinstance(result, str):
+            raise ValueError("filter_item(data) must return a string")
+
+        encoded = result.encode("utf-8")
+        resolved_destination.parent.mkdir(parents=True, exist_ok=True)
+        self._ensure_destination_parent_allowed(resolved_destination)
+        resolved_destination.write_bytes(encoded)
+
+        return ConvertFileResult(
+            expires_at=_to_isoformat(entry.expires_at),
+            filter_id=entry.filter_id,
+            source_file_path=str(resolved_source),
+            destination_file_path=str(resolved_destination),
+            file_type=resolved_file_type,
+            bytes_written=len(encoded),
+            overwritten=will_overwrite,
+        )
+
 
 def create_mcp_server(service: FilterService | None = None) -> FastMCP:
     active_service = service or FilterService()
@@ -152,6 +239,12 @@ def create_mcp_server(service: FilterService | None = None) -> FastMCP:
         The function must return a text result (str). The returned text may contain any
         format you want, such as plain text, YAML, CSV-like text, or a custom report.
 
+        Preloaded standard-library modules:
+        - json, yaml, re
+        - math, statistics, datetime, decimal
+        - collections, itertools, functools, operator
+        - textwrap, html, base64, hashlib, ipaddress, unicodedata, difflib
+
         Safety rules:
         - The code is validated against a restricted Python subset
         - Imports, network access, dynamic execution, and unsafe attribute access are rejected
@@ -238,6 +331,86 @@ def create_mcp_server(service: FilterService | None = None) -> FastMCP:
 
         return active_service.run_filter(filter_id, file_path, file_type)
 
+    @mcp.tool()
+    def convert_file(
+        filter_id: Annotated[
+            str,
+            Field(description="Identifier previously returned by register_filter."),
+        ],
+        source_file_path: Annotated[
+            str,
+            Field(
+                description=(
+                    "Absolute path to the source file. Must be inside an allowed "
+                    "--workdir if any are configured."
+                )
+            ),
+        ],
+        destination_file_path: Annotated[
+            str,
+            Field(
+                description=(
+                    "Absolute path to the destination file. Must be inside an "
+                    "allowed --workdir. Missing parent directories are created "
+                    "automatically."
+                )
+            ),
+        ],
+        file_type: Annotated[
+            Literal["json", "yaml", "txt"] | None,
+            Field(
+                description=(
+                    "Optional explicit file type override for the source file. "
+                    "If omitted, detected from the source extension."
+                )
+            ),
+        ] = None,
+        overwrite: Annotated[
+            bool,
+            Field(
+                description=(
+                    "If false (default), fail when destination exists. If true, "
+                    "overwrite the existing destination file."
+                )
+            ),
+        ] = False,
+    ) -> ConvertFileResult:
+        """
+        Apply a registered filter to a source file and save the text output.
+
+        Use this tool after register_filter when you want to transform a local
+        json, yaml, or txt file and persist the returned string as UTF-8 text.
+        The destination path must be inside a configured --workdir; unlike
+        run_filter, convert_file refuses to write when no --workdir is configured.
+
+        Missing destination parent directories are created automatically. Existing
+        destination files are rejected unless overwrite is true.
+
+        Args:
+            filter_id: Identifier returned earlier by register_filter.
+            source_file_path: Absolute path to the source file to load.
+            destination_file_path: Absolute path where result text is saved.
+            file_type: Optional explicit source file type override.
+            overwrite: Whether to replace an existing destination file.
+
+        Returns:
+            A structured object describing the written file and filter metadata.
+
+        Raises:
+            ValueError: If paths are invalid, workdir is missing, the filter is
+                unknown or expired, destination exists without overwrite, or the
+                filter returns a non-string result.
+            FileNotFoundError: If the source file does not exist.
+        """
+
+        return active_service.convert_file(
+            filter_id,
+            source_file_path,
+            destination_file_path,
+            file_type,
+            overwrite,
+        )
+
     return mcp