data-filter-mcp 0.1.0__tar.gz

data_filter_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Arakelyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data_filter_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: data-filter-mcp
+Version: 0.1.0
+Summary: Local MCP server for running restricted Python text filters over files
+Author: Alex Arakelyan
+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`
+- Registered filters live only in memory and expire automatically based on server TTL settings
+
+## 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
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "data-filter": {
+      "command": "uvx",
+      "args": [
+        "data-filter-mcp",
+        "--filter-ttl-seconds",
+        "3600",
+        "--cleanup-interval-seconds",
+        "60"
+      ]
+    }
+  }
+}
+```
+
+## 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.1.0/README.md

@@ -0,0 +1,50 @@
+# 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`
+- Registered filters live only in memory and expire automatically based on server TTL settings
+
+## 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
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "data-filter": {
+      "command": "uvx",
+      "args": [
+        "data-filter-mcp",
+        "--filter-ttl-seconds",
+        "3600",
+        "--cleanup-interval-seconds",
+        "60"
+      ]
+    }
+  }
+}
+```
+
+## 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.1.0/data_filter_mcp/__init__.py

@@ -0,0 +1 @@
+"""Local MCP server for running restricted text filters."""

data_filter_mcp-0.1.0/data_filter_mcp/loaders/__init__.py

@@ -0,0 +1 @@
+"""Document loaders for supported input file types."""

data_filter_mcp-0.1.0/data_filter_mcp/loaders/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..models import LoadedDocument
+
+
+class DocumentLoader(Protocol):
+    file_type: str
+    extensions: tuple[str, ...]
+
+    def load(self, file_path: Path) -> LoadedDocument: ...

data_filter_mcp-0.1.0/data_filter_mcp/loaders/factory.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import LoadedDocument
+from .base import DocumentLoader
+from .json_loader import JsonLoader
+from .txt_loader import TxtLoader
+from .yaml_loader import YamlLoader
+
+LOADERS: dict[str, DocumentLoader] = {
+    "json": JsonLoader(),
+    "txt": TxtLoader(),
+    "yaml": YamlLoader(),
+}
+
+EXTENSION_TO_FILE_TYPE = {
+    ".json": "json",
+    ".txt": "txt",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+}
+
+
+def normalize_file_type(file_type: str) -> str:
+    normalized = file_type.strip().lower()
+    if normalized not in LOADERS:
+        raise ValueError(f"Unsupported file type: {file_type}")
+    return normalized
+
+
+def resolve_file_type(file_path: Path, file_type: str | None = None) -> str:
+    if file_type is not None:
+        return normalize_file_type(file_type)
+
+    suffix = file_path.suffix.lower()
+    resolved = EXTENSION_TO_FILE_TYPE.get(suffix)
+    if resolved is None:
+        raise ValueError(f"Could not detect file type from extension: {file_path.name}")
+    return resolved
+
+
+def load_document(
+    file_path: Path,
+    file_type: str | None = None,
+) -> tuple[LoadedDocument, str]:
+    resolved_file_type = resolve_file_type(file_path, file_type)
+    loader = LOADERS[resolved_file_type]
+    return loader.load(file_path), resolved_file_type

data_filter_mcp-0.1.0/data_filter_mcp/loaders/json_loader.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..models import LoadedDocument
+
+
+class JsonLoader:
+    file_type = "json"
+    extensions = (".json",)
+
+    def load(self, file_path: Path) -> LoadedDocument:
+        with file_path.open("r", encoding="utf-8") as handle:
+            return json.load(handle)

data_filter_mcp-0.1.0/data_filter_mcp/loaders/txt_loader.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import LoadedDocument
+
+
+class TxtLoader:
+    file_type = "txt"
+    extensions = (".txt",)
+
+    def load(self, file_path: Path) -> LoadedDocument:
+        return file_path.read_text(encoding="utf-8").splitlines()

data_filter_mcp-0.1.0/data_filter_mcp/loaders/yaml_loader.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from ..models import LoadedDocument
+
+
+class YamlLoader:
+    file_type = "yaml"
+    extensions = (".yaml", ".yml")
+
+    def load(self, file_path: Path) -> LoadedDocument:
+        with file_path.open("r", encoding="utf-8") as handle:
+            return yaml.safe_load(handle)

data_filter_mcp-0.1.0/data_filter_mcp/models.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Callable
+
+from pydantic import BaseModel, Field
+
+LoadedDocument = Any
+FilterCallable = Callable[[LoadedDocument], str]
+
+
+class RegisterFilterResult(BaseModel):
+    filter_id: str = Field(
+        description="Unique filter identifier to pass into run_filter."
+    )
+    expires_at: str = Field(
+        description="UTC timestamp in ISO 8601 format when the filter expires."
+    )
+    ttl_seconds: int = Field(
+        description="Server-side lifetime of the registered filter in seconds."
+    )
+    policy_version: str = Field(
+        description="Validation policy version used for the submitted filter code."
+    )
+
+
+class RunFilterResult(BaseModel):
+    filter_id: str = Field(
+        description="Identifier of the registered filter that produced this result."
+    )
+    file_path: str = Field(
+        description="Resolved absolute path of the processed local file."
+    )
+    file_type: str = Field(
+        description="Effective loader type used for the file. One of: json, yaml, txt."
+    )
+    expires_at: str = Field(
+        description="UTC timestamp in ISO 8601 format when this filter expires."
+    )
+    result_text: str = Field(description="Exact text returned by filter_item(data).")
+
+
+@dataclass(slots=True)
+class RegisteredFilter:
+    filter_id: str
+    function: FilterCallable
+    source_code: str
+    created_at: datetime
+    expires_at: datetime
+    policy_version: str
+
+    def is_expired(self, now: datetime) -> bool:
+        return now >= self.expires_at

data_filter_mcp-0.1.0/data_filter_mcp/registry.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from threading import Event, RLock, Thread
+from typing import Callable
+from uuid import uuid4
+
+from .models import FilterCallable, RegisteredFilter
+
+
+class FilterRegistryError(RuntimeError):
+    """Base registry error."""
+
+
+class FilterNotFoundError(FilterRegistryError):
+    """Raised when a filter id does not exist."""
+
+
+class FilterExpiredError(FilterRegistryError):
+    """Raised when a filter has passed its TTL."""
+
+
+class FilterRegistry:
+    def __init__(
+        self,
+        filter_ttl_seconds: int,
+        cleanup_interval_seconds: float = 60.0,
+        now_provider: Callable[[], datetime] | None = None,
+    ) -> None:
+        if filter_ttl_seconds <= 0:
+            raise ValueError("filter_ttl_seconds must be greater than zero")
+        if cleanup_interval_seconds <= 0:
+            raise ValueError("cleanup_interval_seconds must be greater than zero")
+
+        self._filter_ttl_seconds = filter_ttl_seconds
+        self._cleanup_interval_seconds = cleanup_interval_seconds
+        self._now_provider = now_provider or (lambda: datetime.now(timezone.utc))
+        self._filters: dict[str, RegisteredFilter] = {}
+        self._lock = RLock()
+        self._stop_event = Event()
+        self._cleanup_thread: Thread | None = None
+
+    @property
+    def filter_ttl_seconds(self) -> int:
+        return self._filter_ttl_seconds
+
+    def register(
+        self,
+        source_code: str,
+        function: FilterCallable,
+        policy_version: str,
+    ) -> RegisteredFilter:
+        now = self._now_provider()
+        filter_id = str(uuid4())
+        entry = RegisteredFilter(
+            filter_id=filter_id,
+            function=function,
+            source_code=source_code,
+            created_at=now,
+            expires_at=now + timedelta(seconds=self._filter_ttl_seconds),
+            policy_version=policy_version,
+        )
+        with self._lock:
+            self._filters[filter_id] = entry
+        return entry
+
+    def get(self, filter_id: str) -> RegisteredFilter:
+        now = self._now_provider()
+        with self._lock:
+            entry = self._filters.get(filter_id)
+            if entry is None:
+                raise FilterNotFoundError(f"Unknown filter_id: {filter_id}")
+            if entry.is_expired(now):
+                del self._filters[filter_id]
+                raise FilterExpiredError(f"Filter has expired: {filter_id}")
+            return entry
+
+    def cleanup_expired(self) -> int:
+        now = self._now_provider()
+        with self._lock:
+            expired_ids = [
+                filter_id
+                for filter_id, entry in self._filters.items()
+                if entry.is_expired(now)
+            ]
+            for filter_id in expired_ids:
+                del self._filters[filter_id]
+            return len(expired_ids)
+
+    def start_cleanup_thread(self) -> None:
+        with self._lock:
+            if self._cleanup_thread is not None and self._cleanup_thread.is_alive():
+                return
+            self._stop_event.clear()
+            self._cleanup_thread = Thread(
+                target=self._cleanup_loop,
+                name="filter-registry-cleanup",
+                daemon=True,
+            )
+            self._cleanup_thread.start()
+
+    def stop_cleanup_thread(self) -> None:
+        self._stop_event.set()
+        thread = self._cleanup_thread
+        if thread is not None:
+            thread.join(timeout=self._cleanup_interval_seconds + 1.0)
+        self._cleanup_thread = None
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._filters)
+
+    def _cleanup_loop(self) -> None:
+        while not self._stop_event.wait(self._cleanup_interval_seconds):
+            self.cleanup_expired()

data_filter_mcp-0.1.0/data_filter_mcp/server.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Literal, Sequence
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from .loaders.factory import load_document
+from .models import RegisterFilterResult, RunFilterResult
+from .registry import FilterExpiredError, FilterNotFoundError, FilterRegistry
+from .validator import POLICY_VERSION, FilterValidationError, compile_filter
+
+
+def _to_isoformat(value: datetime) -> str:
+    return value.isoformat().replace("+00:00", "Z")
+
+
+class FilterService:
+    def __init__(
+        self,
+        filter_ttl_seconds: int = 3600,
+        cleanup_interval_seconds: float = 60.0,
+        now_provider=None,
+    ) -> None:
+        self._registry = FilterRegistry(
+            filter_ttl_seconds=filter_ttl_seconds,
+            cleanup_interval_seconds=cleanup_interval_seconds,
+            now_provider=now_provider,
+        )
+
+    def start(self) -> None:
+        self._registry.start_cleanup_thread()
+
+    def stop(self) -> None:
+        self._registry.stop_cleanup_thread()
+
+    def register_filter(self, code: str) -> RegisterFilterResult:
+        try:
+            filter_fn = compile_filter(code)
+        except FilterValidationError:
+            raise
+
+        entry = self._registry.register(
+            source_code=code,
+            function=filter_fn,
+            policy_version=POLICY_VERSION,
+        )
+        return RegisterFilterResult(
+            filter_id=entry.filter_id,
+            expires_at=_to_isoformat(entry.expires_at),
+            policy_version=entry.policy_version,
+            ttl_seconds=self._registry.filter_ttl_seconds,
+        )
+
+    def run_filter(
+        self,
+        filter_id: str,
+        file_path: str,
+        file_type: Literal["json", "yaml", "txt"] | None = None,
+    ) -> RunFilterResult:
+        try:
+            entry = self._registry.get(filter_id)
+        except (FilterNotFoundError, FilterExpiredError) as exc:
+            raise ValueError(str(exc)) from exc
+
+        resolved_path = Path(file_path).expanduser().resolve()
+        if not resolved_path.exists():
+            raise FileNotFoundError(f"File not found: {resolved_path}")
+        if not resolved_path.is_file():
+            raise ValueError(f"Path is not a file: {resolved_path}")
+
+        document, resolved_file_type = load_document(resolved_path, file_type)
+        result = entry.function(document)
+        if not isinstance(result, str):
+            raise ValueError("filter_item(data) must return a string")
+
+        return RunFilterResult(
+            expires_at=_to_isoformat(entry.expires_at),
+            file_path=str(resolved_path),
+            file_type=resolved_file_type,
+            filter_id=entry.filter_id,
+            result_text=result,
+        )
+
+
+def create_mcp_server(service: FilterService | None = None) -> FastMCP:
+    active_service = service or FilterService()
+    mcp = FastMCP("data-filter-mcp")
+
+    @mcp.tool()
+    def register_filter(
+        code: Annotated[
+            str,
+            Field(
+                description=(
+                    "Python source code that defines exactly one top-level function "
+                    "named filter_item(data). The function receives the loaded "
+                    "document and must return a text result."
+                )
+            ),
+        ],
+    ) -> RegisterFilterResult:
+        """
+        Validate and register a restricted Python filter for later execution on a local file.
+
+        Use this tool first when you want to run custom filtering or transformation logic
+        against a local document. The submitted source code must define exactly one
+        top-level function with this exact signature:
+
+            def filter_item(data):
+
+        The server loads the target file before execution and passes the loaded document
+        into filter_item(data).
+
+        Input document types:
+        - JSON files -> parsed JSON value such as dict, list, string, number, boolean, or null
+        - YAML files -> parsed YAML value such as dict, list, string, number, boolean, or null
+        - TXT files -> list of text lines
+
+        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.
+
+        Safety rules:
+        - The code is validated against a restricted Python subset
+        - Imports, file I/O, network access, dynamic execution, and unsafe attribute access are rejected
+        - Registered filters are stored in memory only and expire automatically after a server-side TTL
+
+        Args:
+            code: Python source code that defines exactly one function named filter_item(data).
+
+        Returns:
+            A structured object containing the new filter identifier, expiration timestamp,
+            TTL in seconds, and validation policy version.
+
+        Raises:
+            ValueError: If the code is invalid, unsafe, or does not match the required function signature.
+        """
+
+        return active_service.register_filter(code)
+
+    @mcp.tool()
+    def run_filter(
+        filter_id: Annotated[
+            str,
+            Field(description="Identifier previously returned by register_filter."),
+        ],
+        file_path: Annotated[
+            str,
+            Field(
+                description=(
+                    "Path to the local file that should be loaded and passed into "
+                    "filter_item(data)."
+                )
+            ),
+        ],
+        file_type: Annotated[
+            Literal["json", "yaml", "txt"] | None,
+            Field(
+                description=(
+                    "Optional explicit file type override. If omitted, the server "
+                    "detects the type from the file extension."
+                )
+            ),
+        ] = None,
+    ) -> RunFilterResult:
+        """
+        Run a previously registered filter on a local file and return its text output.
+
+        Use this tool after register_filter. The server resolves the registered filter,
+        loads the file from the local filesystem, converts it into an in-memory document,
+        calls filter_item(data), and returns the exact text produced by the filter.
+
+        Supported file types:
+        - json
+        - yaml
+        - txt
+
+        If file_type is omitted, the server tries to detect the type from the file extension.
+
+        File loading behavior:
+        - json -> parsed JSON value
+        - yaml -> parsed YAML value
+        - txt -> list of lines
+
+        Args:
+            filter_id: Identifier returned earlier by register_filter.
+            file_path: Path to the local file that should be loaded and passed into the filter.
+            file_type: Optional explicit file type override. Use this when extension-based detection
+                is missing or ambiguous.
+
+        Returns:
+            A structured object containing the filter identifier, resolved file path,
+            effective file type, filter expiration time, and result_text.
+
+        Raises:
+            ValueError: If the filter does not exist, has expired, returns a non-string result,
+                or the file type is unsupported.
+            FileNotFoundError: If the file does not exist.
+        """
+
+        return active_service.run_filter(filter_id, file_path, file_type)
+
+    return mcp
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run the local data filter MCP server")
+    parser.add_argument(
+        "--filter-ttl-seconds",
+        type=int,
+        default=3600,
+        help="How long registered filters stay available in memory",
+    )
+    parser.add_argument(
+        "--cleanup-interval-seconds",
+        type=float,
+        default=60.0,
+        help="How often expired filters are swept from the registry",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    args = parse_args(argv)
+    service = FilterService(
+        filter_ttl_seconds=args.filter_ttl_seconds,
+        cleanup_interval_seconds=args.cleanup_interval_seconds,
+    )
+    service.start()
+    try:
+        create_mcp_server(service).run()
+    finally:
+        service.stop()
+
+
+if __name__ == "__main__":
+    main()