evryth-mcp 0.1.1__tar.gz

evryth_mcp-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.uv-cache/
+__pycache__/
+dist/
+.ruff_cache/
+*.egg-info/
+build/

evryth_mcp-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Development
+
+## Layout
+
+- src/everything_mcp/server.py: MCP registration and application entry point.
+- src/everything_mcp/service.py: search use cases and result assembly.
+- src/everything_mcp/es.py: subprocess and IPC error boundary.
+- src/everything_mcp/query.py: ES argument validation and expressions.
+- src/everything_mcp/models.py: validated public filters and parameter types.
+- src/everything_mcp/matching.py: pinyin matching algorithm.
+- tests/: offline unit/contract tests and opt-in live integration.
+
+## Checks
+
+```powershell
+uv sync --locked
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run python -m unittest discover -v
+uv build
+```
+
+The src layout requires installing the project before importing it. Both
+`evryth-mcp` and `python -m everything_mcp` start the STDIO server.
+
+Live integration requires Windows, an accessible Everything IPC instance,
+and the sample file asserted in tests/integration.py:
+
+```powershell
+uv run python -m tests.integration
+```
+
+Live integration is excluded from normal discovery. Adjust the fixed sample
+before using a different machine. Never emit diagnostics on protocol stdout.
+Changes to public tool names or schemas require explicit compatibility review.
+
+## GitHub Actions and PyPI
+
+`.github/workflows/publish.yml` runs offline tests, Ruff, and distribution checks
+on Windows for branch pushes and pull requests. A push to `master` in the original
+repository also publishes the checked artifacts to PyPI if the version's `v*`
+tag does not exist. After publishing succeeds, it creates that tag at the tested
+commit and a GitHub Release with generated notes and the wheel/source archives.
+PRs and other branches never publish. Only stable public versions are automated.
+The separate Linux publishing job uploads artifacts; it does not run Everything.
+No local publishing script or long-lived PyPI token is required.
+
+One-time setup:
+
+1. In the GitHub repository settings, create an environment named `pypi`.
+   Allow deployment from the `master` branch (not only `v*` tags); enable required
+   reviewers if available. Update this rule if you used the old tag workflow.
+2. In PyPI, configure a GitHub Trusted Publisher. For a new project, use a pending
+   publisher at https://pypi.org/manage/account/publishing/ with:
+   - PyPI project: `evryth-mcp`
+   - Owner: `dengbojing`
+   - Repository: `everything-mcp`
+   - Workflow filename: `publish.yml`
+   - Environment: `pypi`
+   For an existing project, add the publisher in its publishing settings.
+3. Protect `master` and release tags. Ensure repository rules permit the workflow's
+   `GITHUB_TOKEN` to create release tags; only the release job has `contents: write`.
+
+To release, update `project.version` in `pyproject.toml`, run `uv lock`, and commit
+and push the changes to `master`:
+
+```powershell
+git push origin master
+```
+
+Use a new version for each release; published distribution filenames cannot be
+reused. Configure the PyPI publisher before pushing an untagged version to master.
+Do not create tags manually: an existing version tag skips automatic publishing.
+If PyPI succeeds but the release job fails, rerun only the failed job in the same
+Actions run; do not rebuild and re-upload the published version. If a partial
+GitHub Release already exists, inspect and complete it manually before retrying.
+Branch runs are serialized; GitHub may replace older pending runs with newer ones.
+If the repository is renamed, update both the workflow repository guard and PyPI
+publisher settings.
+
+Reference: https://docs.pypi.org/trusted-publishers/using-a-publisher/

evryth_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: evryth-mcp
+Version: 0.1.1
+Summary: Read-only Windows Everything search over MCP stdio
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.10.1
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pypinyin<1,>=0.55
+Description-Content-Type: text/markdown
+
+# evryth-mcp
+
+通过 MCP 调用 Windows 本机 Everything 索引，查找文件和目录。提供 12 个搜索及辅助工具，支持路径、扩展名、大小和修改日期筛选，返回完整路径及文件元数据。
+
+## 安装准备
+
+当前版本仅支持在 Windows 上运行，依赖本机 Everything 和 ES；macOS、Linux 及其他 Unix 类系统暂不支持原生运行。
+
+需安装 Everything、ES、uv（提供 uvx）及 Git，Python 版本要求为 3.11+。
+
+1. 从 [voidtools 下载页](https://www.voidtools.com/downloads/) 安装 Everything，并保持运行。
+2. 在同一页面下载 **Everything Command-line Interface（ES）**，解压到固定目录。
+3. 将 **es.exe 所在目录**加入 Windows 用户或系统 PATH，然后重启终端和 MCP 客户端。
+
+Everything 与 ES 是不同组件。如果已安装全局 ES，且客户端能从 PATH 找到它，**无需设置 `EVERYTHING_ES_PATH`**。
+
+验证安装：
+
+```powershell
+es -version
+```
+
+## MCP 配置
+
+适用于使用 `mcpServers` JSON 格式的客户端：
+
+```json
+{
+  "mcpServers": {
+    "everything-es": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/dengbojing/everything-mcp.git",
+        "evryth-mcp"
+      ]
+    }
+  }
+}
+```
+
+以上 GitHub 配置需要仓库已包含新的启动入口。发布到 PyPI 后，可将 `args` 简化为 `["evryth-mcp"]`，即 `uvx evryth-mcp`，届时无需 Git。
+
+如果 ES 已在客户端 PATH 中且使用默认 Everything 实例，上面的配置即可，无需添加环境变量。
+
+需要指定 ES 路径或命名实例时，在 `everything-es` 配置中添加 `env`：
+
+```json
+{
+  "mcpServers": {
+    "everything-es": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/dengbojing/everything-mcp.git",
+        "evryth-mcp"
+      ],
+      "env": {
+        "EVERYTHING_ES_PATH": "D:\\Tools\\Everything\\es.exe",
+        "EVERYTHING_INSTANCE": "Work"
+      }
+    }
+  }
+}
+```
+
+- `EVERYTHING_ES_PATH`：替换为实际 `es.exe` 的绝对路径，不是 `Everything.exe` 或目录；客户端能从 PATH 找到 ES 时可删除此项。
+- `EVERYTHING_INSTANCE`：填写已运行的 Everything 命名实例名称，示例为 `Work`；使用默认实例时删除此项。它不会自动创建或启动实例。
+
+这两项可独立使用；如果都不需要，删除整个 `env`。
+
+## 工具
+
+| 工具 | 功能 |
+| --- | --- |
+| everything_search | Everything 原生查询、排序和分页 |
+| everything_search_exact | 完整文件名匹配 |
+| everything_search_keywords | 全部/任一关键词及排除词 |
+| everything_search_wildcard | * 和 ? 通配符 |
+| everything_search_regex | 正则表达式 |
+| everything_search_fuzzy | 连续、非连续及无序关键词匹配 |
+| everything_search_pinyin | 全拼、首字母、中文混输及多音字 |
+| everything_search_by_type | 文档、图片、视频、音频、代码、压缩包 |
+| everything_search_typo | 文件名字符相似度匹配 |
+| everything_list_directory | 直属或递归目录索引项 |
+| everything_count | 匹配数量 |
+| everything_status | 版本与 IPC 状态 |
+
+例如，让客户端“查找包含合同和2025、排除草稿的 PDF”，或“按拼音 niandubaogao 搜索年度报告”。具体参数由客户端工具描述提供。
+
+## 使用说明
+
+- 默认搜索 Everything 全部索引，不额外限制目录；未索引的文件不会出现。
+- 没有专门的文件内容搜索或文件修改工具。
+- 拼音和容错按候选分页匹配，单页无结果不代表全盘不存在；容错分数仅在当前页排序。
+- IPC 不可达时，检查 Everything 是否运行，以及客户端会话和沙箱权限。
+- 终端能执行 ES 而客户端找不到时，先完全重启客户端，使其继承最新 PATH。
+
+[ES 官方文档](https://www.voidtools.com/support/everything/command_line_interface/)

evryth_mcp-0.1.1/README.md

@@ -0,0 +1,99 @@
+# evryth-mcp
+
+通过 MCP 调用 Windows 本机 Everything 索引，查找文件和目录。提供 12 个搜索及辅助工具，支持路径、扩展名、大小和修改日期筛选，返回完整路径及文件元数据。
+
+## 安装准备
+
+当前版本仅支持在 Windows 上运行，依赖本机 Everything 和 ES；macOS、Linux 及其他 Unix 类系统暂不支持原生运行。
+
+需安装 Everything、ES、uv（提供 uvx）及 Git，Python 版本要求为 3.11+。
+
+1. 从 [voidtools 下载页](https://www.voidtools.com/downloads/) 安装 Everything，并保持运行。
+2. 在同一页面下载 **Everything Command-line Interface（ES）**，解压到固定目录。
+3. 将 **es.exe 所在目录**加入 Windows 用户或系统 PATH，然后重启终端和 MCP 客户端。
+
+Everything 与 ES 是不同组件。如果已安装全局 ES，且客户端能从 PATH 找到它，**无需设置 `EVERYTHING_ES_PATH`**。
+
+验证安装：
+
+```powershell
+es -version
+```
+
+## MCP 配置
+
+适用于使用 `mcpServers` JSON 格式的客户端：
+
+```json
+{
+  "mcpServers": {
+    "everything-es": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/dengbojing/everything-mcp.git",
+        "evryth-mcp"
+      ]
+    }
+  }
+}
+```
+
+以上 GitHub 配置需要仓库已包含新的启动入口。发布到 PyPI 后，可将 `args` 简化为 `["evryth-mcp"]`，即 `uvx evryth-mcp`，届时无需 Git。
+
+如果 ES 已在客户端 PATH 中且使用默认 Everything 实例，上面的配置即可，无需添加环境变量。
+
+需要指定 ES 路径或命名实例时，在 `everything-es` 配置中添加 `env`：
+
+```json
+{
+  "mcpServers": {
+    "everything-es": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/dengbojing/everything-mcp.git",
+        "evryth-mcp"
+      ],
+      "env": {
+        "EVERYTHING_ES_PATH": "D:\\Tools\\Everything\\es.exe",
+        "EVERYTHING_INSTANCE": "Work"
+      }
+    }
+  }
+}
+```
+
+- `EVERYTHING_ES_PATH`：替换为实际 `es.exe` 的绝对路径，不是 `Everything.exe` 或目录；客户端能从 PATH 找到 ES 时可删除此项。
+- `EVERYTHING_INSTANCE`：填写已运行的 Everything 命名实例名称，示例为 `Work`；使用默认实例时删除此项。它不会自动创建或启动实例。
+
+这两项可独立使用；如果都不需要，删除整个 `env`。
+
+## 工具
+
+| 工具 | 功能 |
+| --- | --- |
+| everything_search | Everything 原生查询、排序和分页 |
+| everything_search_exact | 完整文件名匹配 |
+| everything_search_keywords | 全部/任一关键词及排除词 |
+| everything_search_wildcard | * 和 ? 通配符 |
+| everything_search_regex | 正则表达式 |
+| everything_search_fuzzy | 连续、非连续及无序关键词匹配 |
+| everything_search_pinyin | 全拼、首字母、中文混输及多音字 |
+| everything_search_by_type | 文档、图片、视频、音频、代码、压缩包 |
+| everything_search_typo | 文件名字符相似度匹配 |
+| everything_list_directory | 直属或递归目录索引项 |
+| everything_count | 匹配数量 |
+| everything_status | 版本与 IPC 状态 |
+
+例如，让客户端“查找包含合同和2025、排除草稿的 PDF”，或“按拼音 niandubaogao 搜索年度报告”。具体参数由客户端工具描述提供。
+
+## 使用说明
+
+- 默认搜索 Everything 全部索引，不额外限制目录；未索引的文件不会出现。
+- 没有专门的文件内容搜索或文件修改工具。
+- 拼音和容错按候选分页匹配，单页无结果不代表全盘不存在；容错分数仅在当前页排序。
+- IPC 不可达时，检查 Everything 是否运行，以及客户端会话和沙箱权限。
+- 终端能执行 ES 而客户端找不到时，先完全重启客户端，使其继承最新 PATH。
+
+[ES 官方文档](https://www.voidtools.com/support/everything/command_line_interface/)

evryth_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "evryth-mcp"
+version = "0.1.1"
+description = "Read-only Windows Everything search over MCP stdio"
+requires-python = ">=3.11"
+dependencies = ["mcp>=1.10.1,<2", "pypinyin>=0.55,<1", "pydantic>=2.7,<3"]
+readme = "README.md"
+
+[project.scripts]
+evryth-mcp = "everything_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everything_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/CONTRIBUTING.md", "/pyproject.toml", "/uv.lock"]
+
+[dependency-groups]
+dev = ["ruff>=0.11,<1"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]

evryth_mcp-0.1.1/src/everything_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Windows Everything search MCP package."""
+
+from .server import main
+
+__all__ = ["main"]

evryth_mcp-0.1.1/src/everything_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Support python -m everything_mcp."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

evryth_mcp-0.1.1/src/everything_mcp/es.py

@@ -0,0 +1,40 @@
+"""Execute the local ES process without a shell."""
+
+import locale
+import os
+import shutil
+import subprocess
+
+
+def run_es(args: list[str], search: bool = False) -> str:
+    executable = os.environ.get("EVERYTHING_ES_PATH") or shutil.which("es.exe")
+    if not executable:
+        raise RuntimeError("ES_NOT_FOUND: install voidtools ES or set EVERYTHING_ES_PATH")
+    instance = os.environ.get("EVERYTHING_INSTANCE")
+    command = [executable, *(["-instance", instance] if instance else []), *args]
+    # ES consumes a Windows search expression. list2cmdline would quote the
+    # entire expression containing spaces, changing AND terms into a phrase.
+    if search:
+        command = subprocess.list2cmdline(command[:-1]) + " " + command[-1]
+    try:
+        result = subprocess.run(command, capture_output=True, timeout=20, shell=False)
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError("ES_TIMEOUT: Everything did not respond within 20 seconds") from exc
+    except OSError as exc:
+        raise RuntimeError(f"ES_START_FAILED: {exc}") from exc
+
+    def decode(raw: bytes) -> str:
+        try:
+            return raw.decode("utf-8-sig")
+        except UnicodeDecodeError:
+            return raw.decode(locale.getpreferredencoding(False), errors="strict")
+
+    output, error = decode(result.stdout), decode(result.stderr)
+    if result.returncode:
+        details = (error or output).strip()
+        if "IPC not found" in details:
+            raise RuntimeError(
+                "ES_IPC_UNAVAILABLE: Everything IPC is inaccessible. Check running instance, Windows session and host sandbox permissions; this is not a zero-match result."
+            )
+        raise RuntimeError(f"ES_ERROR ({result.returncode}): {details[:2000]}")
+    return output

evryth_mcp-0.1.1/src/everything_mcp/matching.py

@@ -0,0 +1,31 @@
+"""Filename pinyin matching independent of MCP and ES."""
+
+
+def pinyin_match(name: str, needle: str, mode: str, heteronym: bool) -> bool:
+    """Bounded dynamic matching; no exponential polyphonic combinations."""
+    from pypinyin import Style, pinyin
+
+    readings = (
+        [pinyin(char, style=Style.NORMAL, heteronym=True)[0] for char in name]
+        if heteronym
+        else pinyin(name, style=Style.NORMAL, errors=lambda chars: list(chars))
+    )
+    states = {0}
+    for char, sounds in zip(name, readings):
+        choices = set()
+        if mode in ("full", "both", "mixed"):
+            choices.update(sounds)
+        if mode in ("initials", "both", "mixed"):
+            choices.update(s[0] for s in sounds if s)
+        if mode == "mixed":
+            choices.add(char)
+        next_states = {0}
+        for index in states:
+            for choice in choices:
+                if needle.startswith(choice.lower(), index):
+                    end = index + len(choice)
+                    if end == len(needle):
+                        return True
+                    next_states.add(end)
+        states = next_states
+    return False

evryth_mcp-0.1.1/src/everything_mcp/models.py

@@ -0,0 +1,59 @@
+"""Validated search filters and public parameter types."""
+
+import re
+from datetime import date, timedelta
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+Sort = Literal["name", "path", "size", "extension", "date-created", "date-modified"]
+Kind = Literal["all", "file", "folder"]
+
+
+class Filters(BaseModel):
+    """Index metadata only. Dates include the whole calendar day; size is bytes."""
+
+    model_config = ConfigDict(extra="forbid")
+    extensions: list[str] = Field(default_factory=list, max_length=30)
+    min_bytes: int | None = Field(default=None, ge=0)
+    max_bytes: int | None = Field(default=None, ge=0)
+    modified_from: date | None = None
+    modified_to: date | None = None
+    recent_days: int | None = Field(default=None, ge=1, le=36500)
+
+    @model_validator(mode="after")
+    def validate_ranges(self):
+        if (
+            self.min_bytes is not None
+            and self.max_bytes is not None
+            and self.min_bytes > self.max_bytes
+        ):
+            raise ValueError("min_bytes exceeds max_bytes")
+        if self.modified_from and self.modified_to and self.modified_from > self.modified_to:
+            raise ValueError("modified_from exceeds modified_to")
+        if self.recent_days and (self.modified_from or self.modified_to):
+            raise ValueError("use recent_days or a date range, not both")
+        for ext in self.extensions:
+            if not re.fullmatch(r"\.?[A-Za-z0-9]+", ext):
+                raise ValueError("extensions must be plain extensions, e.g. pdf or .docx")
+        return self
+
+    def expression(self):
+        terms = []
+        if self.extensions:
+            terms.append("ext:" + ";".join(e.lstrip(".") for e in self.extensions))
+        if self.min_bytes is not None:
+            terms.append(f"size:>={self.min_bytes}")
+        if self.max_bytes is not None:
+            terms.append(f"size:<={self.max_bytes}")
+        start = (
+            date.today() - timedelta(days=self.recent_days - 1)
+            if self.recent_days
+            else self.modified_from
+        )
+        end = date.today() if self.recent_days else self.modified_to
+        if start:
+            terms.append(f"dm:>={start.isoformat()}")
+        if end:
+            terms.append(f"dm:<{(end + timedelta(days=1)).isoformat()}")
+        return " ".join(terms)

evryth_mcp-0.1.1/src/everything_mcp/query.py

@@ -0,0 +1,50 @@
+"""Build and validate ES search arguments."""
+
+import os
+import re
+
+from .models import Kind
+
+
+def regex_term(pattern: str) -> str:
+    if not pattern or len(pattern) > 2048 or any(c in pattern for c in '\x00\r\n"'):
+        raise ValueError("pattern must be 1..2048 characters without quotes or line breaks")
+    return 'regex:"' + pattern + '"'
+
+
+def query_args(
+    query: str, path: str | None, kind: Kind, regex: bool, match_path: bool, case_sensitive: bool
+) -> list[str]:
+    if not query.strip() or len(query) > 4096 or any(c in query for c in "\x00\r\n"):
+        raise ValueError("query must be nonempty, single-line and at most 4096 characters")
+    # ES parses switches itself even with shell=False. Never pass a switch as a query.
+    if re.search(r"(?:^|\s)[-/]", query) or query.count('"') % 2:
+        raise ValueError(
+            "query must not start with an ES switch; use Everything syntax such as regex: or name:"
+        )
+    if kind not in ("all", "file", "folder"):
+        raise ValueError("invalid kind")
+    args = [
+        "-timeout",
+        "10000",
+        "-no-case",
+        "-no-whole-word",
+        "-no-match-path",
+        "-no-prefix",
+        "-no-suffix",
+    ]
+    if path:
+        if any(c in path for c in '\x00\r\n"') or not os.path.isabs(path):
+            raise ValueError(
+                "path must be an absolute directory path without quotes or control characters"
+            )
+        args += ["-path", path]
+    if kind != "all":
+        args += ["/a-d" if kind == "file" else "/ad"]
+    if match_path:
+        args += ["-match-path"]
+    if case_sensitive:
+        args += ["-case"]
+    if regex:
+        args += ["-regex"]
+    return [*args, query]

evryth_mcp-0.1.1/src/everything_mcp/server.py

@@ -0,0 +1,32 @@
+"""MCP tool registration and STDIO entry point."""
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from . import service
+
+
+def create_server() -> FastMCP:
+    """Create an independent server with the stable public tool contract."""
+    server = FastMCP("everything-es")
+    annotations = ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False)
+    for tool in (
+        service.everything_search,
+        service.everything_count,
+        service.everything_status,
+        service.everything_search_regex,
+        service.everything_search_fuzzy,
+        service.everything_search_pinyin,
+        service.everything_search_exact,
+        service.everything_search_keywords,
+        service.everything_search_wildcard,
+        service.everything_search_by_type,
+        service.everything_list_directory,
+        service.everything_search_typo,
+    ):
+        server.add_tool(tool, annotations=annotations)
+    return server
+
+
+def main() -> None:
+    create_server().run(transport="stdio")