syncscore-companion 0.1.0__tar.gz

syncscore_companion-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/

syncscore_companion-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: syncscore-companion
+Version: 0.1.0
+Summary: Local companion MCP server for SyncScore audits — bridges filesystem access to the SyncScore remote MCP server
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=3.4.0
+Description-Content-Type: text/markdown
+
+# syncscore-companion
+
+Local companion MCP server for [SyncScore](https://sync-score.vercel.app) audits.
+
+Bridges local filesystem access with SyncScore's remote audit tools in a single
+MCP server, so a customer's AI client (Claude Desktop, Cursor, etc.) only needs
+to configure one `mcpServers` entry to run a full audit — no separate
+filesystem MCP server required.
+
+## Usage
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "syncscore": {
+      "command": "uvx",
+      "args": ["syncscore-companion", "--project-path", "/absolute/path/to/your/project"],
+      "env": { "SYNCSCORE_API_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+## What it does
+
+- Exposes read-only, scoped filesystem tools (`read_file`, `list_directory`,
+  `search_files`) rooted at `--project-path`. Excludes `.git`, `node_modules`,
+  `.venv`, dotfiles/secrets, and files over 512KB.
+- Transparently proxies SyncScore's remote audit tools
+  (`start_audit`, `report_*`, `finalize_report`) to
+  `https://syncscore-api.onrender.com/mcp`, injecting your API key as the
+  `Authorization` header automatically.
+
+## Local development
+
+```bash
+uv pip install -e ".[dev]"
+pytest tests/
+```

syncscore_companion-0.1.0/README.md

@@ -0,0 +1,41 @@
+# syncscore-companion
+
+Local companion MCP server for [SyncScore](https://sync-score.vercel.app) audits.
+
+Bridges local filesystem access with SyncScore's remote audit tools in a single
+MCP server, so a customer's AI client (Claude Desktop, Cursor, etc.) only needs
+to configure one `mcpServers` entry to run a full audit — no separate
+filesystem MCP server required.
+
+## Usage
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "syncscore": {
+      "command": "uvx",
+      "args": ["syncscore-companion", "--project-path", "/absolute/path/to/your/project"],
+      "env": { "SYNCSCORE_API_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+## What it does
+
+- Exposes read-only, scoped filesystem tools (`read_file`, `list_directory`,
+  `search_files`) rooted at `--project-path`. Excludes `.git`, `node_modules`,
+  `.venv`, dotfiles/secrets, and files over 512KB.
+- Transparently proxies SyncScore's remote audit tools
+  (`start_audit`, `report_*`, `finalize_report`) to
+  `https://syncscore-api.onrender.com/mcp`, injecting your API key as the
+  `Authorization` header automatically.
+
+## Local development
+
+```bash
+uv pip install -e ".[dev]"
+pytest tests/
+```

syncscore_companion-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "syncscore-companion"
+version = "0.1.0"
+description = "Local companion MCP server for SyncScore audits — bridges filesystem access to the SyncScore remote MCP server"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=3.4.0",
+]
+
+[project.scripts]
+syncscore-companion = "syncscore_companion.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/syncscore_companion"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+]

syncscore_companion-0.1.0/src/syncscore_companion/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

syncscore_companion-0.1.0/src/syncscore_companion/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

syncscore_companion-0.1.0/src/syncscore_companion/cli.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .server import DEFAULT_REMOTE_URL, build_server
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="syncscore-companion")
+    parser.add_argument(
+        "--project-path",
+        required=True,
+        help="Path to the local project to audit",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="SyncScore API key (sk_live_...). Falls back to SYNCSCORE_API_KEY env var.",
+    )
+    parser.add_argument(
+        "--remote-url",
+        default=os.environ.get("SYNCSCORE_REMOTE_URL", DEFAULT_REMOTE_URL),
+        help=argparse.SUPPRESS,
+    )
+    args = parser.parse_args()
+
+    api_key = args.api_key or os.environ.get("SYNCSCORE_API_KEY", "")
+    if not api_key.startswith("sk_live_"):
+        sys.stderr.write(
+            "Error: a valid SyncScore API key (sk_live_...) is required via "
+            "--api-key or the SYNCSCORE_API_KEY environment variable\n"
+        )
+        sys.exit(1)
+
+    try:
+        mcp = build_server(args.project_path, api_key, remote_url=args.remote_url)
+    except ValueError as e:
+        sys.stderr.write(f"Error: {e}\n")
+        sys.exit(1)
+
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

syncscore_companion-0.1.0/src/syncscore_companion/fs_tools.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+EXCLUDED_DIRS = {
+    ".git",
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".next",
+    "dist",
+    "build",
+    ".idea",
+    ".vscode",
+}
+ALLOWED_DOTFILES = {".env.example", ".env.template"}
+BLOCKED_EXACT_NAMES = {".env"}
+MAX_FILE_SIZE_BYTES = 512 * 1024
+MAX_SEARCH_RESULTS = 200
+
+
+def resolve_scoped(root: Path, relative_path: str) -> Path:
+    """Resolve relative_path under root, rejecting traversal and symlink escapes.
+
+    Path.resolve() dereferences symlinks, so checking the resolved path's
+    containment covers both "../" traversal and a symlink pointing outside
+    root in one check.
+    """
+    candidate = (root / relative_path).resolve()
+    if candidate != root and not candidate.is_relative_to(root):
+        raise ValueError(f"Path '{relative_path}' escapes the project root")
+    return candidate
+
+
+def is_excluded(path: Path, root: Path) -> bool:
+    rel_parts = path.relative_to(root).parts
+    if any(part in EXCLUDED_DIRS for part in rel_parts):
+        return True
+    if path.name in BLOCKED_EXACT_NAMES:
+        return True
+    if path.name.startswith(".") and path.name not in ALLOWED_DOTFILES:
+        return True
+    return False
+
+
+def _looks_binary(data: bytes) -> bool:
+    return b"\x00" in data[:8192]
+
+
+def read_file(root: Path, relative_path: str) -> str:
+    path = resolve_scoped(root, relative_path)
+    if is_excluded(path, root):
+        raise ValueError(f"Path '{relative_path}' is excluded from access")
+    if not path.is_file():
+        raise ValueError(f"'{relative_path}' is not a file")
+
+    size = path.stat().st_size
+    if size > MAX_FILE_SIZE_BYTES:
+        raise ValueError(
+            f"File '{relative_path}' exceeds the {MAX_FILE_SIZE_BYTES // 1024}KB limit"
+        )
+
+    raw = path.read_bytes()
+    if _looks_binary(raw):
+        raise ValueError(f"File '{relative_path}' appears to be binary — skip it")
+
+    return raw.decode("utf-8", errors="replace")
+
+
+def list_directory(root: Path, relative_path: str = ".") -> list[str]:
+    path = resolve_scoped(root, relative_path)
+    if not path.is_dir():
+        raise ValueError(f"'{relative_path}' is not a directory")
+
+    entries = []
+    for entry in sorted(path.iterdir(), key=lambda e: e.name):
+        if is_excluded(entry, root):
+            continue
+        entries.append(entry.name + "/" if entry.is_dir() else entry.name)
+    return entries
+
+
+def search_files(root: Path, relative_path: str, pattern: str) -> list[str]:
+    base = resolve_scoped(root, relative_path)
+    if not base.is_dir():
+        raise ValueError(f"'{relative_path}' is not a directory")
+
+    results: list[str] = []
+    for match in base.rglob(pattern):
+        if len(results) >= MAX_SEARCH_RESULTS:
+            break
+        # Skip anything under an excluded/symlinked directory in its path chain.
+        try:
+            rel = match.relative_to(root)
+        except ValueError:
+            continue
+        if any(part in EXCLUDED_DIRS for part in rel.parts):
+            continue
+        if any((root / Path(*rel.parts[:i])).is_symlink() for i in range(1, len(rel.parts))):
+            continue
+        if match.is_file() and not is_excluded(match, root):
+            results.append(rel.as_posix())
+
+    return results

syncscore_companion-0.1.0/src/syncscore_companion/server.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.server import create_proxy
+
+from . import fs_tools
+
+DEFAULT_REMOTE_URL = "https://syncscore-api.onrender.com/mcp"
+
+
+def build_server(project_path: str, api_key: str, remote_url: str = DEFAULT_REMOTE_URL) -> FastMCP:
+    root = Path(project_path).expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError(f"--project-path '{project_path}' is not a directory")
+
+    mcp = FastMCP("SyncScore Companion")
+
+    @mcp.tool
+    def read_file(relative_path: str) -> str:
+        """Read a text file within the scoped project directory (read-only, max 512KB)."""
+        return fs_tools.read_file(root, relative_path)
+
+    @mcp.tool
+    def list_directory(relative_path: str = ".") -> list[str]:
+        """List entries in a directory within the scoped project directory.
+
+        Excludes .git, node_modules, .venv, and dotfiles/secrets. Directory
+        entries are suffixed with '/'.
+        """
+        return fs_tools.list_directory(root, relative_path)
+
+    @mcp.tool
+    def search_files(pattern: str, relative_path: str = ".") -> list[str]:
+        """Glob-search for files matching a pattern within the scoped project directory."""
+        return fs_tools.search_files(root, relative_path, pattern)
+
+    remote = Client(
+        StreamableHttpTransport(
+            remote_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+    )
+    mcp.mount(create_proxy(remote))
+
+    return mcp

syncscore_companion-0.1.0/tests/test_cli.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from syncscore_companion.cli import main
+
+
+def test_missing_project_path_exits(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setattr(sys, "argv", ["syncscore-companion", "--api-key", "sk_live_x"])
+    with pytest.raises(SystemExit):
+        main()
+
+
+def test_invalid_api_key_prefix_exits(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        ["syncscore-companion", "--project-path", str(tmp_path), "--api-key", "not-a-real-key"],
+    )
+    with pytest.raises(SystemExit) as exc_info:
+        main()
+    assert exc_info.value.code == 1
+
+
+def test_api_key_falls_back_to_env_but_still_requires_prefix(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+):
+    monkeypatch.setattr(sys, "argv", ["syncscore-companion", "--project-path", str(tmp_path)])
+    monkeypatch.delenv("SYNCSCORE_API_KEY", raising=False)
+    with pytest.raises(SystemExit) as exc_info:
+        main()
+    assert exc_info.value.code == 1
+
+
+def test_nonexistent_project_path_exits(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+    missing = tmp_path / "does-not-exist"
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        ["syncscore-companion", "--project-path", str(missing), "--api-key", "sk_live_x"],
+    )
+    with pytest.raises(SystemExit) as exc_info:
+        main()
+    assert exc_info.value.code == 1

syncscore_companion-0.1.0/tests/test_fs_tools.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from syncscore_companion import fs_tools
+
+
+@pytest.fixture
+def project(tmp_path: Path) -> Path:
+    (tmp_path / "README.md").write_text("hello world")
+    (tmp_path / ".env").write_text("SECRET=1")
+    (tmp_path / ".env.example").write_text("SECRET=")
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "main.py").write_text("print('hi')")
+    (tmp_path / "node_modules").mkdir()
+    (tmp_path / "node_modules" / "pkg.js").write_text("module.exports = {}")
+    (tmp_path / ".git").mkdir()
+    (tmp_path / ".git" / "config").write_text("[core]")
+    return tmp_path
+
+
+def test_read_file_within_root(project: Path):
+    assert fs_tools.read_file(project, "README.md") == "hello world"
+    assert fs_tools.read_file(project, "src/main.py") == "print('hi')"
+
+
+def test_read_file_allows_env_example(project: Path):
+    assert fs_tools.read_file(project, ".env.example") == "SECRET="
+
+
+def test_read_file_blocks_env(project: Path):
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, ".env")
+
+
+def test_read_file_blocks_traversal(project: Path):
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, "../../../etc/passwd")
+
+
+def test_read_file_blocks_excluded_dirs(project: Path):
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, "node_modules/pkg.js")
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, ".git/config")
+
+
+def test_read_file_blocks_symlink_escape(project: Path, tmp_path_factory: pytest.TempPathFactory):
+    outside = tmp_path_factory.mktemp("outside")
+    secret = outside / "secret.txt"
+    secret.write_text("top secret")
+
+    link = project / "escape"
+    os.symlink(outside, link)
+
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, "escape/secret.txt")
+
+
+def test_read_file_size_limit(project: Path):
+    big = project / "big.txt"
+    big.write_text("x" * (fs_tools.MAX_FILE_SIZE_BYTES + 1))
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, "big.txt")
+
+
+def test_read_file_binary_rejected(project: Path):
+    binary = project / "binary.dat"
+    binary.write_bytes(b"\x00\x01\x02\x03")
+    with pytest.raises(ValueError):
+        fs_tools.read_file(project, "binary.dat")
+
+
+def test_list_directory_excludes_dot_dirs(project: Path):
+    entries = fs_tools.list_directory(project, ".")
+    assert "node_modules/" not in entries
+    assert ".git/" not in entries
+    assert ".env" not in entries
+    assert ".env.example" in entries
+    assert "README.md" in entries
+    assert "src/" in entries
+
+
+def test_list_directory_blocks_traversal(project: Path):
+    with pytest.raises(ValueError):
+        fs_tools.list_directory(project, "..")
+
+
+def test_search_files_finds_matches(project: Path):
+    results = fs_tools.search_files(project, ".", "*.py")
+    assert "src/main.py" in results
+
+
+def test_search_files_skips_excluded_dirs(project: Path):
+    results = fs_tools.search_files(project, ".", "*")
+    assert not any(r.startswith("node_modules/") for r in results)
+    assert not any(r.startswith(".git/") for r in results)