refactor: simplify CLI interface and add direct script entry point

Author: safurrier

CONTRIBUTING.md

@@ -1,11 +1,11 @@
-# Contributing to Python Collab Template
+# Contributing to MCP Filesystem
 
 Thank you for your interest in contributing to this project!
 
 ## Getting Started
 
 1. Fork the repository
-2. Clone your fork: `git clone [email protected]:your-username/python-collab-template.git`
+2. Clone your fork: `git clone [email protected]:your-username/mcp-filesystem.git`
 3. Create a new branch: `git checkout -b feature-name`
 4. Make your changes
 5. Run quality checks: `make check`

README.md

@@ -42,10 +42,10 @@ Run the server with access to specific directories:
 
 ```bash
 # Using uv (recommended)
-uv run -m mcp_filesystem run /path/to/dir1 /path/to/dir2
+uv run run_server.py /path/to/dir1 /path/to/dir2
 
 # Or using standard Python
-python -m mcp_filesystem run /path/to/dir1 /path/to/dir2
+python run_server.py /path/to/dir1 /path/to/dir2
 ```
 
 #### Options
@@ -60,13 +60,13 @@ For interactive testing and debugging with the MCP Inspector:
 
 ```bash
 # Basic usage
-npx @modelcontextprotocol/inspector uv run -m mcp_filesystem run /path/to/directory
+npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory
 
 # With SSE transport
-npx @modelcontextprotocol/inspector uv run -m mcp_filesystem run /path/to/directory --transport sse --port 8080
+npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080
 
 # With debug output
-npx @modelcontextprotocol/inspector uv run -m mcp_filesystem run /path/to/directory --debug
+npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug
 ```
 
 This server has been built with the FastMCP SDK for better alignment with current MCP best practices. It uses an efficient component caching system and direct decorator pattern.
@@ -85,10 +85,10 @@ Edit your Claude Desktop config file to integrate MCP-Filesystem:
     "mcp-filesystem": {
       "command": "uv",
       "args": [
+        "--directory",
+        "/path/to/mcp-filesystem/repo",
         "run",
-        "-m",
-        "mcp_filesystem",
-        "run"
+        "run_server.py"
       ]
     }
   }
@@ -103,10 +103,10 @@ To allow access to specific directories, add them as additional arguments:
     "mcp-filesystem": {
       "command": "uv",
       "args": [
+        "--directory",
+        "/path/to/mcp-filesystem/repo",
         "run",
-        "-m",
-        "mcp_filesystem",
-        "run",
+        "run_server.py",
         "/Users/yourusername/Projects",
         "/Users/yourusername/Documents"
       ]
@@ -115,7 +115,7 @@ To allow access to specific directories, add them as additional arguments:
 }
 ```
 
-Note: The `run` command at the end is required as it specifies the subcommand to execute.
+> Note: The `--directory` flag is important as it tells uv where to find the repository containing run_server.py. Replace `/path/to/mcp-filesystem/repo` with the actual path to where you cloned the repository on your system.
 
 ## Development
 

mcp_filesystem/__init__.py

@@ -7,4 +7,21 @@
 
 from .server import mcp
 
-__all__ = ["mcp"]
+
+def main() -> None:
+    """Main entry point for the package."""
+    try:
+        mcp.run()
+    except KeyboardInterrupt:
+        import sys
+
+        print("\nShutting down...", file=sys.stderr)
+        sys.exit(0)
+    except Exception as e:
+        import sys
+
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+__all__ = ["mcp", "main"]

mcp_filesystem/__main__.py

@@ -16,9 +16,9 @@
 )
 
 
-@app.command()
-def run(
-    directory: Annotated[
+@app.callback(invoke_without_command=True)
+def main(
+    directories: Annotated[
         Optional[List[str]],
         typer.Argument(
             help="Allowed directories (defaults to current directory if none provided)",
@@ -49,33 +49,32 @@ def run(
             help="Enable debug logging",
         ),
     ] = False,
-    name: Annotated[
-        Optional[str],
+    version: Annotated[
+        bool,
         typer.Option(
-            "--name",
-            "-n",
-            help="Server name",
+            "--version",
+            "-v",
+            help="Show version information",
         ),
-    ] = None,
+    ] = False,
 ) -> None:
     """Run the MCP Filesystem Server.
 
     By default, the server will only allow access to the current directory.
     You can specify one or more allowed directories as arguments.
     """
+    if version:
+        show_version()
+        return
+
     # Set allowed directories in environment for the server to pick up
-    if directory:
-        os.environ["MCP_ALLOWED_DIRS"] = os.pathsep.join(directory)
+    if directories:
+        os.environ["MCP_ALLOWED_DIRS"] = os.pathsep.join(directories)
 
     # Set debug mode if requested
     if debug:
         os.environ["FASTMCP_LOG_LEVEL"] = "DEBUG"
 
-    # Setting custom name is not supported with FastMCP
-    # Just log the name for now
-    if name:
-        print(f"Using server name: {name}")
-
     try:
         if transport.lower() == "sse":
             os.environ["FASTMCP_PORT"] = str(port)
@@ -90,8 +89,7 @@ def run(
         sys.exit(1)
 
 
-@app.command()
-def version() -> None:
+def show_version() -> None:
     """Show version information."""
     try:
         from importlib.metadata import version as get_version

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
 
 [project.scripts]
 mcp-filesystem = "mcp_filesystem.__main__:app"
+mcp-fs = "mcp_filesystem:main"
 
 [project.optional-dependencies]
 dev = [

run_server.py

@@ -1,17 +1,113 @@
 #!/usr/bin/env python
 """
-Simple entry point to run the MCP filesystem server.
-Usage: uv run run_server.py [dir1] [dir2] ...
+Primary entry point to run the MCP filesystem server.
+Usage: uv run run_server.py [dir1] [dir2] ... [options]
 
 For use with MCP Inspector or Claude Desktop:
 - Command: uv
-- Arguments: --directory /path/to/mcp-filesystem run mcp-filesystem run
+- Arguments: --directory /path/to/mcp-filesystem run run_server.py [dir1] [dir2]
 
-Note: The trailing 'run' is required as it specifies the subcommand to execute.
+This simplified approach eliminates the need for module invocation with -m flag.
 """
 
 import sys
-from mcp_filesystem.__main__ import app
+import os
+import typer
+from typing import List, Optional
+from typing_extensions import Annotated
+
+from mcp_filesystem.server import mcp
+
+app = typer.Typer(
+    name="mcp-filesystem",
+    help="MCP Filesystem Server",
+    add_completion=False,
+)
+
+@app.callback(invoke_without_command=True)
+def main(
+    directories: Annotated[
+        Optional[List[str]],
+        typer.Argument(
+            help="Allowed directories (defaults to current directory if none provided)",
+            show_default=False,
+        ),
+    ] = None,
+    transport: Annotated[
+        str,
+        typer.Option(
+            "--transport",
+            "-t",
+            help="Transport protocol to use",
+        ),
+    ] = "stdio",
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            "-p",
+            help="Port for SSE transport",
+        ),
+    ] = 8000,
+    debug: Annotated[
+        bool,
+        typer.Option(
+            "--debug",
+            "-d",
+            help="Enable debug logging",
+        ),
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-v",
+            help="Show version information",
+        ),
+    ] = False,
+) -> None:
+    """Run the MCP Filesystem Server.
+
+    By default, the server will only allow access to the current directory.
+    You can specify one or more allowed directories as arguments.
+    """
+    if version:
+        show_version()
+        return
+
+    # Set allowed directories in environment for the server to pick up
+    if directories:
+        os.environ["MCP_ALLOWED_DIRS"] = os.pathsep.join(directories)
+
+    # Set debug mode if requested
+    if debug:
+        os.environ["FASTMCP_LOG_LEVEL"] = "DEBUG"
+
+    try:
+        if transport.lower() == "sse":
+            os.environ["FASTMCP_PORT"] = str(port)
+            mcp.run(transport="sse")
+        else:
+            mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        print("\nShutting down...", file=sys.stderr)
+        sys.exit(0)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def show_version() -> None:
+    """Show version information."""
+    try:
+        from importlib.metadata import version as get_version
+        version = get_version("mcp-filesystem")
+    except ImportError:
+        version = "unknown"
+
+    print(f"MCP Filesystem Server v{version}")
+    print("A Model Context Protocol server for filesystem operations")
+
 
 if __name__ == "__main__":
-    sys.exit(app())
+    app()