pip install -r requirements.txt

export MCP_BASE_DIR="/path/to/your/projects"
# or on Windows:
# set MCP_BASE_DIR=C:\Users\YourName\Projects

python server_v3.py

# Clone or download the repository
cd mcp-fs-agent

# Install dependencies
pip install -r requirements.txt

# Set your base directory (optional, defaults to ~/Data/Repos)
export MCP_BASE_DIR="$HOME/projects"

# Start the server
python server_v3.py

$ python server_v3.py
==============================================================================
🚀 TOKEN-OPTIMIZED MCP FILESYSTEM AGENT v3 (PRODUCTION-READY)
==============================================================================
📁 BASE_DIR: /home/user/projects
✨ Features:
  ✅ 25+ file operations (read, write, search, edit)
  ✅ Standardized Dict return types (LLM-friendly)
  ✅ Proper chunked reading with pagination
  ...
📚 Ready to use with Claude.ai or any MCP-compatible LLM
==============================================================================

ping() -> Dict
get_base_dir() -> Dict

list_directory(path: str = ".") -> Dict
get_tree(path: str = ".", max_depth: int = 2) -> Dict
create_directory(path: str) -> Dict

read_file(path: str, preview_lines: int = 0) -> Dict
read_file_chunked(path: str, chunk_index: int = 0, chunk_size_kb: int = 50) -> Dict
batch_read_files(paths: List[str]) -> Dict
file_summary(path: str) -> Dict

write_file(path: str, content: str) -> Dict
append_file(path: str, content: str) -> Dict

replace_text(path: str, old_text: str, new_text: str, count: int = -1, dry_run: bool = False) -> Dict
insert_at_line(path: str, line_number: int, text: str) -> Dict
delete_lines(path: str, start_line: int, end_line: int) -> Dict

search_files(query: str, path: str = ".", max_results: int = 20) -> Dict
search_content(query: str, path: str = ".", max_results: int = 15,
               extensions: List[str] = None, use_regex: bool = False) -> Dict
search_files_by_ext(extension: str, path: str = ".", max_results: int = 30) -> Dict

search_code_structure(path: str = ".", search_type: str = "functions", max_results: int = 25) -> Dict

User: Read the first 50 lines of app/main.py

Claude uses: read_file(path="app/main.py", preview_lines=50)

Response:
{
  "status": "success",
  "action": "read_file",
  "mode": "preview",
  "preview_lines": 50,
  "total_lines": 450,
  "content": "#!/usr/bin/env python3\n..."
}

✅ Only 50 lines loaded, not 450!

User: My app.log is huge. Read it in chunks starting from the beginning.

Claude uses: read_file_chunked(
    path="logs/app.log",
    chunk_index=0,
    chunk_size_kb=100
)

Response:
{
  "status": "success",
  "chunk_index": 0,
  "total_chunks": 25,
  "progress": "1/25",
  "file_size": "2.5MB",
  "content": "2024-01-15 10:00:00 INFO ...\n..."
}

✅ Can request chunk 5, 10, 20, etc without reloading!

User: Change all "console.log" to "logger.debug" in src/util.js - but show me first!

Claude uses: replace_text(
    path="src/util.js",
    old_text="console.log",
    new_text="logger.debug",
    dry_run=True
)

Response:
{
  "status": "success",
  "mode": "dry_run",
  "would_replace": 12,
  "preview": "const logger = require('./logger');\nlogger.debug('Debug message');\n...",
  "ready_to_commit": true
}

User: Looks good, do it!

Claude uses: replace_text(..., dry_run=False)

✅ No surprises, changes committed safely!

User: Show me all functions in the project

Claude uses: search_code_structure(search_type="functions", max_results=30)

Response:
{
  "status": "success",
  "found": 8,
  "results": [
    {
      "type": "function",
      "name": "handle_request",
      "file": "app/handlers.py",
      "line": 45,
      "signature": "def handle_request(req, resp)",
      "args": 2
    },
    ...
  ]
}

✅ Understand entire codebase structure without reading any files!

User: Find all TODO comments in Python files

Claude uses: search_content(
    query=r"#\s*TODO",
    extensions=[".py"],
    use_regex=True
)

Response:
{
  "status": "success",
  "found": 5,
  "results": [
    {
      "file": "app/main.py",
      "line": 127,
      "match": "# TODO: Refactor authentication logic"
    },
    ...
  ]
}

✅ Powerful pattern matching without manual code review!

User: Analyze my Flask app's structure

Claude: I'll examine your Flask app...
[Uses search_code_structure to find routes, models, handlers]
[Uses file_summary to check file sizes]
[Uses read_file with preview_lines on key files]

Here's what I found:
- 3 route handlers in app/routes.py
- 2 database models in app/models.py
- Configuration in config.py (45 lines)
...

{
    "status": "success|error|info",    # Always present
    "action": "tool_name",              # What was called
    "path": "relative/path",            # If applicable
    # ... tool-specific fields ...
}

# Base directory (default: ~/Data/Repos, override with MCP_BASE_DIR env var)
BASE_DIR = Path(os.getenv("MCP_BASE_DIR", str(Path.home() / "Data/Repos"))).resolve()

# Token optimization settings
MAX_FILE_SIZE_KB = 2000          # Max single file (2MB)
MAX_RESULTS = 50                 # Max search results
DEFAULT_CHUNK_SIZE_KB = 50       # Chunk size for large files
TOTAL_BATCH_SIZE_KB = 5000       # Max total for batch_read_files (5MB)
CONTEXT_WIDTH = 80               # Chars around search match
MAX_LINES_TO_SEARCH = 10000      # Stop after this many lines

# Ignore directories
IGNORE_DIRS = {".git", "node_modules", "__pycache__", "venv", ...}

# Ignore binary files
BINARY_EXTENSIONS = {".exe", ".pdf", ".zip", ".so", ...}

export MCP_BASE_DIR="$HOME/projects"
python server_v3.py
# Leave running, connect from Claude

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server_v3.py .
ENV MCP_BASE_DIR=/workspace
CMD ["python", "server_v3.py"]

docker build -t mcp-fs-agent .
docker run -e MCP_BASE_DIR=/projects -v ~/projects:/projects mcp-fs-agent

[Unit]
Description=MCP Filesystem Agent
After=network.target

[Service]
Type=simple
User=yourusername
Environment="MCP_BASE_DIR=/home/yourusername/projects"
ExecStart=/usr/bin/python3 /home/yourusername/server_v3.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable mcp-fs
sudo systemctl start mcp-fs
sudo systemctl status mcp-fs

# ✅ These work (within BASE_DIR)
"/projects/my_app/main.py"
"./src/app.py"
"config/settings.json"

# ❌ These are blocked (outside BASE_DIR)
"../../etc/passwd"
"/etc/passwd"
"/home/other_user/file.txt"

# Symlinks are resolved and validated
# Even if they point outside BASE_DIR, they're rejected

# Automatically skipped for:
.exe, .dll, .so, .pdf, .zip, .jpg, .png, etc.
# Prevents text decode errors and token waste

# ✅ Good: Narrow down with file type first
search_files_by_ext(".py")

# ✅ Good: Limit search scope
search_content(query="TODO", extensions=[".py", ".txt"])

# ✅ Good: Preview first, full read later
read_file(path="large_file.py", preview_lines=50)

# ✅ Only way to handle huge files
read_file_chunked(path="huge.log", chunk_index=0, chunk_size_kb=500)

# ❌ Never use read_file() on huge files

# ✅ Use regex for complex patterns
search_content(query=r"def [a-z_]+_handler", use_regex=True)

# ✅ Limit max_results to avoid token waste
search_content(query="import", max_results=10)

# Create test directory
mkdir -p ~/test_mcp/{src,tests}
echo "def hello(): pass" > ~/test_mcp/src/app.py

# Set and run
export MCP_BASE_DIR="$HOME/test_mcp"
python server_v3.py

# In another terminal, test with Claude or manually:
curl -X POST http://localhost:8000/search_files \
  -H "Content-Type: application/json" \
  -d '{"query": ".py"}'

# Add to imports
import re

# Add to search_code_structure() function
elif file.endswith(".js"):
    # Use regex to find function definitions
    matches = re.findall(r'(?:function|const|async)\s+(\w+)', content)
    # Convert to same format as Python