fs-mcp 0.1.0__tar.gz

fs_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

fs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: fs-mcp
+Version: 0.1.0
+Summary: A secure MCP filesystem server with Stdio and Web UI modes.
+Author-email: Your Name <you@example.com>
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: streamlit>=1.30.0

fs_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "fs-mcp"
+version = "0.1.0"
+description = "A secure MCP filesystem server with Stdio and Web UI modes."
+authors = [{name = "Your Name", email = "you@example.com"}]
+requires-python = ">=3.10"
+readme = "README.md"
+dependencies = [
+    "fastmcp>=0.1.0",
+    "streamlit>=1.30.0",
+]
+
+[project.scripts]
+fs-mcp = "fs_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fs_mcp"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+]

fs_mcp-0.1.0/src/fs_mcp/__main__.py

@@ -0,0 +1,53 @@
+import argparse
+import sys
+import subprocess
+from pathlib import Path
+from fs_mcp import server
+
+def main():
+    parser = argparse.ArgumentParser(description="fs-mcp server")
+    parser.add_argument("--ui", action="store_true", help="Launch Web UI")
+    parser.add_argument("--host", default="0.0.0.0", help="UI Host")
+    parser.add_argument("--port", default="8501", help="UI Port")
+    parser.add_argument("dirs", nargs="*", help="Allowed directories")
+    
+    # Parse known args to allow Streamlit to handle its own flags if needed
+    args, unknown = parser.parse_known_args()
+    
+    # Initialize Core Logic for Stdio mode
+    dirs = args.dirs or [str(Path.cwd())]
+    try:
+        server.initialize(dirs)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.ui:
+        # Launch Streamlit as a subprocess
+        # FIX: Find the file without importing it
+        current_dir = Path(__file__).parent
+        ui_path = (current_dir / "web_ui.py").resolve()
+        
+        if not ui_path.exists():
+            print(f"Error: Could not find web_ui.py at {ui_path}", file=sys.stderr)
+            sys.exit(1)
+            
+        cmd = [
+            sys.executable, "-m", "streamlit", "run", str(ui_path),
+            "--server.address", args.host,
+            "--server.port", args.port,
+            "--",  # Separator: args after this are passed to the script
+            *dirs
+        ]
+        print(f"🚀 Launching UI on http://{args.host}:{args.port}", file=sys.stderr)
+        # Use simple run, Streamlit handles the rest
+        try:
+            subprocess.run(cmd)
+        except KeyboardInterrupt:
+            pass
+    else:
+        # Run Standard MCP Server
+        server.mcp.run()
+
+if __name__ == "__main__":
+    main()

fs_mcp-0.1.0/src/fs_mcp/server.py

@@ -0,0 +1,215 @@
+import os
+import base64
+import mimetypes
+import fnmatch
+from pathlib import Path
+from typing import List, Optional, Literal, Dict
+from datetime import datetime
+from fastmcp import FastMCP
+
+# --- Global Configuration ---
+ALLOWED_DIRS: List[Path] = []
+mcp = FastMCP("filesystem")
+
+def initialize(directories: List[str]):
+    """Initialize the allowed directories configuration."""
+    global ALLOWED_DIRS
+    ALLOWED_DIRS.clear()
+    
+    # Resolve all paths to absolute
+    # If no paths provided, default to CWD
+    raw_dirs = directories or [str(Path.cwd())]
+    
+    for d in raw_dirs:
+        try:
+            p = Path(d).expanduser().resolve()
+            if not p.exists() or not p.is_dir():
+                # Just warn in logs, don't crash entire server if one dir is bad
+                print(f"Warning: Skipping invalid directory: {p}")
+                continue
+            ALLOWED_DIRS.append(p)
+        except Exception as e:
+            print(f"Warning: Could not resolve {d}: {e}")
+
+    if not ALLOWED_DIRS:
+        print("Warning: No valid directories allowed. Defaulting to CWD.")
+        ALLOWED_DIRS.append(Path.cwd())
+            
+    return ALLOWED_DIRS
+
+def validate_path(requested_path: str) -> Path:
+    """Security barrier: Ensures path is within ALLOWED_DIRS."""
+    try:
+        path_obj = Path(requested_path).expanduser().resolve()
+    except Exception:
+        # Handle new files (write ops)
+        path_obj = Path(requested_path).expanduser().absolute()
+    
+    # Check strict containment
+    is_allowed = any(
+        str(path_obj).startswith(str(allowed)) 
+        for allowed in ALLOWED_DIRS
+    )
+    
+    if not is_allowed:
+        raise ValueError(f"Access denied: {requested_path} is outside allowed directories.")
+    
+    return path_obj
+
+def format_size(size_bytes: int) -> str:
+    for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
+        if size_bytes < 1024.0:
+            return f"{size_bytes:.2f} {unit}"
+        size_bytes /= 1024.0
+    return f"{size_bytes:.2f} PB"
+
+# --- Tools ---
+
+@mcp.tool()
+def list_allowed_directories() -> str:
+    """List the directories this server is allowed to access."""
+    return "\n".join(str(d) for d in ALLOWED_DIRS)
+
+@mcp.tool()
+def read_text_file(path: str, head: Optional[int] = None, tail: Optional[int] = None) -> str:
+    """Read text file contents."""
+    if head is not None and tail is not None:
+        raise ValueError("Cannot specify both head and tail")
+
+    path_obj = validate_path(path)
+    
+    try:
+        with open(path_obj, 'r', encoding='utf-8') as f:
+            if head is not None:
+                return "".join([next(f) for _ in range(head)])
+            elif tail is not None:
+                return "".join(f.readlines()[-tail:])
+            else:
+                return f.read()
+    except UnicodeDecodeError:
+        return f"Error: File {path} appears to be binary. Use read_media_file instead."
+    except Exception as e:
+        return f"Error reading file: {str(e)}"
+
+@mcp.tool()
+def read_media_file(path: str) -> dict:
+    """Read an image or audio file as base64."""
+    path_obj = validate_path(path)
+    mime_type, _ = mimetypes.guess_type(path_obj)
+    if not mime_type: mime_type = "application/octet-stream"
+        
+    try:
+        with open(path_obj, "rb") as f:
+            data = base64.b64encode(f.read()).decode("utf-8")
+        
+        type_category = "image" if mime_type.startswith("image/") else "audio" if mime_type.startswith("audio/") else "blob"
+        return {"type": type_category, "data": data, "mimeType": mime_type}
+    except Exception as e:
+        return {"error": str(e)}
+
+@mcp.tool()
+def write_file(path: str, content: str) -> str:
+    """Create a new file or completely overwrite an existing file."""
+    path_obj = validate_path(path)
+    with open(path_obj, 'w', encoding='utf-8') as f:
+        f.write(content)
+    return f"Successfully wrote to {path}"
+
+@mcp.tool()
+def create_directory(path: str) -> str:
+    """Create a new directory or ensure it exists."""
+    path_obj = validate_path(path)
+    os.makedirs(path_obj, exist_ok=True)
+    return f"Successfully created directory {path}"
+
+@mcp.tool()
+def list_directory(path: str) -> str:
+    """Get a detailed listing of all files and directories."""
+    path_obj = validate_path(path)
+    if not path_obj.is_dir(): return f"Error: {path} is not a directory"
+    
+    entries = []
+    for entry in path_obj.iterdir():
+        prefix = "[DIR]" if entry.is_dir() else "[FILE]"
+        entries.append(f"{prefix} {entry.name}")
+    return "\n".join(sorted(entries))
+
+@mcp.tool()
+def list_directory_with_sizes(path: str) -> str:
+    """Get listing with file sizes."""
+    path_obj = validate_path(path)
+    if not path_obj.is_dir(): return f"Error: Not a directory"
+    
+    output = []
+    for entry in path_obj.iterdir():
+        try:
+            s = entry.stat().st_size if not entry.is_dir() else 0
+            prefix = "[DIR]" if entry.is_dir() else "[FILE]"
+            size_str = "" if entry.is_dir() else format_size(s)
+            output.append(f"{prefix} {entry.name.ljust(30)} {size_str}")
+        except: continue
+    return "\n".join(sorted(output))
+
+@mcp.tool()
+def move_file(source: str, destination: str) -> str:
+    """Move or rename files."""
+    src = validate_path(source)
+    dst = validate_path(destination)
+    if dst.exists(): raise ValueError(f"Destination {destination} already exists")
+    src.rename(dst)
+    return f"Moved {source} to {destination}"
+
+@mcp.tool()
+def search_files(path: str, pattern: str, exclude_patterns: List[str] = []) -> str:
+    """Recursively search for files matching glob pattern."""
+    root = validate_path(path)
+    results = []
+    for r, d, f in os.walk(root):
+        d[:] = [x for x in d if not any(fnmatch.fnmatch(x, p) for p in exclude_patterns)]
+        for name in f:
+            if any(fnmatch.fnmatch(name, p) for p in exclude_patterns): continue
+            if fnmatch.fnmatch(name, pattern):
+                results.append(str(Path(r) / name))
+    return "\n".join(results) or "No matches found"
+
+@mcp.tool()
+def get_file_info(path: str) -> str:
+    """Retrieve detailed metadata."""
+    p = validate_path(path)
+    s = p.stat()
+    return f"Path: {p}\nType: {'Dir' if p.is_dir() else 'File'}\nSize: {format_size(s.st_size)}\nModified: {datetime.fromtimestamp(s.st_mtime)}"
+
+@mcp.tool()
+def directory_tree(path: str, exclude_patterns: List[str] = []) -> str:
+    """Get recursive JSON tree."""
+    import json
+    root = validate_path(path)
+    def build(current: Path) -> Dict:
+        name = current.name or str(current)
+        if any(fnmatch.fnmatch(name, p) for p in exclude_patterns): return None
+        node = {"name": name, "type": "directory" if current.is_dir() else "file"}
+        if current.is_dir():
+            node["children"] = [c for c in [build(e) for e in sorted(current.iterdir(), key=lambda x: x.name)] if c]
+        return node
+    return json.dumps(build(root), indent=2)
+
+@mcp.tool()
+def edit_file(path: str, edits: List[Dict[str, str]], dry_run: bool = False) -> str:
+    """Line-based file editing with diff preview."""
+    import difflib
+    p = validate_path(path)
+    with open(p, 'r', encoding='utf-8') as f: original = f.read()
+    modified = original
+    for edit in edits:
+        old = edit['oldText'].replace('\r\n', '\n')
+        new = edit['newText'].replace('\r\n', '\n')
+        if old not in modified: raise ValueError(f"Text not found: {old}")
+        modified = modified.replace(old, new, 1)
+    
+    diff = "\n".join(difflib.unified_diff(
+        original.splitlines(), modified.splitlines(), 
+        fromfile="original", tofile="modified", lineterm=""
+    ))
+    if not dry_run:
+        with open(p, 'w', encoding='utf-8') as f: f.write(modified)
+    return diff

fs_mcp-0.1.0/src/fs_mcp/web_ui.py

@@ -0,0 +1,262 @@
+import streamlit as st
+import sys
+import inspect
+import json
+import base64
+from typing import Optional, Union, List, Dict, Any
+from pathlib import Path
+
+# --- 1. SETUP & CONFIG ---
+st.set_page_config(page_title="FS-MCP", layout="wide", page_icon="📂")
+
+try:
+    from fs_mcp import server
+except ImportError:
+    st.error("❌ Could not import 'fs_mcp.server'. Is the package installed?")
+    st.stop()
+
+# Initialize Config from CLI Args
+try:
+    if "--" in sys.argv:
+        raw_args = sys.argv[sys.argv.index("--") + 1:]
+    else:
+        raw_args = [a for a in sys.argv[1:] if not a.startswith("-")]
+    server.initialize(raw_args)
+except Exception as e:
+    st.error(f"❌ Configuration Error: {e}")
+    st.stop()
+
+# --- 2. HEADER ---
+st.title("📂 FS-MCP Explorer")
+if not server.ALLOWED_DIRS:
+    st.warning("⚠️ No directories configured! Defaulting to CWD.")
+
+st.sidebar.header("Active Configuration")
+st.sidebar.code("\n".join(str(d) for d in server.ALLOWED_DIRS))
+
+# --- 3. TOOL DISCOVERY & SCHEMA EXPORT ---
+KNOWN_TOOLS = [
+    "list_directory", "list_directory_with_sizes", "read_text_file", 
+    "read_media_file", "write_file", "create_directory", 
+    "move_file", "search_files", "get_file_info", 
+    "directory_tree", "edit_file", "list_allowed_directories"
+]
+
+tools = {}
+tool_schemas = []
+
+for name in KNOWN_TOOLS:
+    if hasattr(server, name):
+        wrapper = getattr(server, name)
+        fn = wrapper.fn if hasattr(wrapper, 'fn') else wrapper
+        tools[name] = fn
+        
+        # Build Schema for export
+        schema = {
+            "name": name,
+            "description": inspect.getdoc(fn) or "",
+            "inputSchema": {"type": "object", "properties": {}}
+        }
+        sig = inspect.signature(fn)
+        for param_name, param in sig.parameters.items():
+            if param_name in ['ctx', 'context']: continue
+            param_type = "string"
+            if param.annotation == int: param_type = "integer"
+            if param.annotation == bool: param_type = "boolean"
+            if param.annotation == list: param_type = "array"
+            schema["inputSchema"]["properties"][param_name] = {"type": param_type}
+        tool_schemas.append(schema)
+
+with st.sidebar.expander("🔌 Tool Schemas (JSON)", expanded=False):
+    st.caption("Copy this to agent configuration:")
+    st.code(json.dumps(tool_schemas, indent=2), language="json")
+
+# --- 4. EXECUTION HANDLER ---
+def execute_tool(func, args):
+    """Executes tool and returns both raw result and protocol view"""
+    try:
+        # Run the actual function
+        result = func(**args)
+        
+        # Simulate Protocol Response (Agent View)
+        protocol_response = {
+            "content": [],
+            "isError": False
+        }
+        
+        # Format Content Block
+        if isinstance(result, dict) and result.get("type") == "image":
+            # Image protocol format
+            protocol_response["content"].append({
+                "type": "image",
+                "data": result["data"],
+                "mimeType": result.get("mimeType", "image/png")
+            })
+            display_type = "image"
+        elif isinstance(result, (dict, list)):
+            # Structured data usually sent as embedded text JSON
+            text_content = json.dumps(result, indent=2)
+            protocol_response["content"].append({
+                "type": "text",
+                "text": text_content
+            })
+            display_type = "json"
+        else:
+            # Plain text
+            text_result = str(result)
+            protocol_response["content"].append({
+                "type": "text",
+                "text": text_result
+            })
+            display_type = "text"
+            
+        return result, protocol_response, display_type, None
+        
+    except Exception as e:
+        error_resp = {
+            "content": [{"type": "text", "text": str(e)}],
+            "isError": True
+        }
+        return None, error_resp, "error", str(e)
+
+
+# --- 5. UI LOGIC ---
+if not tools:
+    st.error("No tools found.")
+    st.stop()
+
+selected = st.sidebar.radio("Available Tools", list(tools.keys()))
+fn = tools[selected]
+sig = inspect.signature(fn)
+
+st.header(f"🔧 {selected}")
+if inspect.getdoc(fn):
+    st.info(inspect.getdoc(fn))
+
+# INPUT TABS
+tab_form, tab_raw, tab_compact = st.tabs(["📝 Interactive Form", "📄 Raw JSON", "⚡ Compact JSON"])
+
+execution_args = None
+trigger_run = False
+
+# --- TAB 1: INTERACTIVE FORM ---
+with tab_form:
+    with st.form("interactive_form"):
+        form_inputs = {}
+        for name, param in sig.parameters.items():
+            if name in ['ctx', 'context']: continue
+            
+            # Type Checking
+            annotation = param.annotation
+            is_number = (annotation in [int, float]) or (getattr(annotation, "__origin__", None) is Union and int in getattr(annotation, "__args__", []))
+            is_bool = (annotation == bool) or (getattr(annotation, "__origin__", None) is Union and bool in getattr(annotation, "__args__", []))
+            
+            if name in ['path', 'source', 'destination']:
+                def_val = str(server.ALLOWED_DIRS[0])
+                form_inputs[name] = st.text_input(name, value=def_val)
+            elif name == 'content':
+                st.caption("Literal Content (WYSIWYG - Enter creates newlines)")
+                form_inputs[name] = st.text_area(name, height=200)
+            elif name == 'edits':
+                st.write("Edits (JSON List)")
+                val = st.text_area("JSON", value='[{"oldText": "foo", "newText": "bar"}]')
+                form_inputs[name] = val # Parse later
+            elif name == 'exclude_patterns':
+                val = st.text_area(f"{name} (one per line)")
+                form_inputs[name] = val
+            elif is_bool:
+                form_inputs[name] = st.checkbox(name)
+            elif is_number:
+                form_inputs[name] = st.number_input(name, value=0)
+            else:
+                form_inputs[name] = st.text_input(name)
+        
+        if st.form_submit_button("Run Form"):
+            # Process Form Inputs
+            try:
+                processed = {}
+                for k, v in form_inputs.items():
+                    # Handle lists
+                    if k == 'exclude_patterns':
+                        processed[k] = [x.strip() for x in v.split('\n') if x.strip()]
+                    # Handle JSON fields
+                    elif k == 'edits':
+                        processed[k] = json.loads(v)
+                    # Handle Optionals
+                    elif v == 0 and k in ['head', 'tail']:
+                        processed[k] = None
+                    else:
+                        processed[k] = v
+                execution_args = processed
+                trigger_run = True
+            except Exception as e:
+                st.error(f"Form Error: {e}")
+
+# --- TAB 2 & 3: JSON INPUTS ---
+# Helper to generate template
+default_args = {}
+for name, param in sig.parameters.items():
+    if name in ['ctx', 'context']: continue
+    if name in ['path', 'source', 'destination']: default_args[name] = str(server.ALLOWED_DIRS[0])
+    elif name == 'content': default_args[name] = "Line 1\nLine 2"
+    else: default_args[name] = ""
+
+json_template = json.dumps(default_args, indent=2)
+
+with tab_raw:
+    with st.form("json_raw_form"):
+        raw_text = st.text_area("JSON Input", value=json_template, height=300)
+        if st.form_submit_button("Run Raw JSON"):
+            try:
+                execution_args = json.loads(raw_text)
+                trigger_run = True
+            except Exception as e:
+                st.error(f"Invalid JSON: {e}")
+
+with tab_compact:
+    with st.form("json_compact_form"):
+        compact_text = st.text_input("One-line JSON", value=json.dumps(default_args))
+        if st.form_submit_button("Run Compact JSON"):
+            try:
+                execution_args = json.loads(compact_text)
+                trigger_run = True
+            except Exception as e:
+                st.error(f"Invalid JSON: {e}")
+
+# --- OUTPUT DISPLAY ---
+if trigger_run and execution_args is not None:
+    st.divider()
+    
+    # 1. Run
+    with st.spinner("Running tool..."):
+        res_raw, res_proto, dtype, err = execute_tool(fn, execution_args)
+
+    # 2. Display Status
+    if err:
+        st.error("Tool Execution Failed")
+    else:
+        st.success("Tool Execution Successful")
+
+    # 3. Split View: Human vs Agent
+    col_human, col_agent = st.columns(2)
+    
+    with col_human:
+        st.subheader("👀 Human View")
+        if err:
+            st.error(err)
+        elif dtype == "image":
+            st.image(base64.b64decode(res_proto["content"][0]["data"]))
+        elif dtype == "json":
+            st.json(res_raw)
+        else:
+            # Check for diffs
+            text = str(res_raw)
+            if text.startswith("---") or text.startswith("+++"):
+                st.code(text, language="diff")
+            else:
+                st.code(text)
+
+    with col_agent:
+        st.subheader("🤖 Agent Protocol View")
+        st.caption("This is exactly what the LLM receives.")
+        st.code(json.dumps(res_proto, indent=None), language="json")

fs_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,37 @@
+import pytest
+from pathlib import Path
+from fs_mcp import server
+
+@pytest.fixture
+def temp_env(tmp_path):
+    """Sets up a safe temporary directory environment"""
+    server.initialize([str(tmp_path)])
+    return tmp_path
+
+def test_security_barrier(temp_env):
+    """Attempting to access outside the temp dir should fail"""
+    outside = Path("/etc/passwd")
+    
+    with pytest.raises(ValueError, match="Access denied"):
+        server.validate_path(str(outside))
+
+def test_write_and_read(temp_env):
+    """Test basic read/write tools"""
+    target = temp_env / "test.txt"
+    
+    # Write (Access .fn to call underlying function)
+    server.write_file.fn(str(target), "Hello MCP")
+    assert target.exists()
+    
+    # Read
+    content = server.read_text_file.fn(str(target))
+    assert content == "Hello MCP"
+
+def test_list_directory(temp_env):
+    """Test directory listing"""
+    (temp_env / "A").mkdir()
+    (temp_env / "B.txt").touch()
+    
+    res = server.list_directory.fn(str(temp_env))
+    assert "[DIR] A" in res
+    assert "[FILE] B.txt" in res