Directory Intelligence Tool

A comprehensive toolkit for analyzing directory structures and executing code in secure sandboxes. This project combines intelligent directory analysis with a secure execution environment for Programmatic Tool Calling (PTC).

Project Overview

This project consists of three main components:

1. Directory Intelligence Tool - Analyzes directory structures and generates XML representations
2. FastMCP Server - Exposes the directory tool as a FastMCP service
3. Sandbox Execution Engine - Securely executes Python code with Daytona/Docker backends

Components

1. Directory Intelligence Tool (src/directory_tool.py)

A .gitignore-aware directory structure analyzer that generates XML hierarchies with intelligent summarization for large directories.

Key Features:

• Respects .gitignore patterns using pathspec library
• Generates structured XML output with <dir>, <file>, and <summary> tags
• Automatically summarizes directories with more than 50 files
• Handles edge cases: symlink loops, permission errors, malformed .gitignore
• Provides both FastMCP tool interface and command-line usage

Main Function:

def get_codebase_structure(root_path: str = ".", expand_large: bool = False) -> str:
    """Analyze directory structure and return XML representation."""

2. FastMCP Server (src/mcp_server.py)

Exposes the Directory Intelligence Tool as a FastMCP service with HTTP transport.

Key Features:

• Configurable server settings via config/config.json
• Automatic Daytona/Docker backend detection
• HTTP transport for network accessibility
• Comprehensive error handling and logging
• Graceful shutdown handling

Usage:

python src/mcp_server.py

3. Sandbox Execution Engine (src/execute_code.py)

Secure Python code execution environment with Daytona primary backend and Docker fallback.

Key Features:

• Sequential execution with threading locks
• Persistent workspace maintains state between calls
• Dependency installation support
• Complete host filesystem isolation
• Comprehensive error handling

Main Function:

def execute_python(script: str, requirements: List[str] = None) -> Dict[str, Any]:
    """Execute Python code in sandboxed environment."""

4. Development Environment (.devcontainer/devcontainer.json)

Pre-configured development environment with:

• Python 3.11 with required dependencies
• Docker-in-Docker support
• VS Code extensions for Python development
• Port forwarding for FastMCP server
• Reproducible environment setup

5. Test Suite (test/test.py)

Comprehensive test suite covering:

• Basic script execution and output capture
• Persistent workspace behavior
• Error handling and edge cases
• Sequential execution verification
• Dependency installation testing

Installation

Prerequisites

• Python 3.11+
• Either Daytona SDK or Docker SDK (for sandbox execution)
• Git (for directory analysis)

Setup Steps

1. Clone the repository:

git clone <repository-url>
cd directory-intelligence-tool

2. Install dependencies:

pip install -r requirements.txt

3. Optional: Install Daytona SDK for primary sandbox backend:

pip install daytona-sdk
# Configure Daytona API key in environment
export DAYTONA_API_KEY="your-api-key"

4. Optional: Install Docker SDK for fallback sandbox backend:

pip install docker
# Ensure Docker daemon is running

Usage

Running the FastMCP Server

python src/mcp_server.py

The server will start and print:

FastMCP server running on 127.0.0.1:8000

Using the Directory Intelligence Tool

As a Python module:

from src.directory_tool import get_codebase_structure

# Analyze current directory
xml_result = get_codebase_structure(".")
print(xml_result)

# Analyze with large directories expanded
xml_result = get_codebase_structure(".", expand_large=True)
print(xml_result)

Command line usage:

python src/directory_tool.py /path/to/analyze --expand-large

Using the Sandbox Execution Engine

from src.execute_code import execute_python

# Simple execution
result = execute_python("""
print("Hello from sandbox!")
for i in range(3):
    print(f"Count: {i}")
""")

print(f"Exit code: {result['exit_code']}")
print(f"Output: {result['stdout']}")

# With dependencies
result = execute_python("""
import requests
response = requests.get('https://api.example.com')
print(f'Status: {response.status_code}')
""", requirements=["requests"])

Development Environment

Using VS Code DevContainer:

1. Open project in VS Code
2. Install DevContainer extension
3. Click "Reopen in Container" when prompted
4. Environment will be set up automatically

Manual development setup:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install optional backends
pip install daytona-sdk docker

End-to-End Example

Here's a complete example combining both tools:

import os
import tempfile
from src.directory_tool import get_codebase_structure
from src.execute_code import execute_python

# Step 1: Create a test directory structure
test_dir = tempfile.mkdtemp()
os.makedirs(f"{test_dir}/src")
os.makedirs(f"{test_dir}/tests")

with open(f"{test_dir}/README.md", "w") as f:
    f.write("# Test Project\n")

with open(f"{test_dir}/src/app.py", "w") as f:
    f.write("print('Hello World')\n")

# Step 2: Analyze the directory structure
print("=== Directory Analysis ===")
xml_structure = get_codebase_structure(test_dir)
print(xml_structure)

# Step 3: Process the structure in sandbox
print("\\n=== Processing in Sandbox ===")
result = execute_python(f"""
import xml.etree.ElementTree as ET
import os

# Parse the XML structure
xml_data = """{xml_structure.replace('"', '\\"')}"""
root = ET.fromstring(xml_data)

# Count directories and files
def count_items(element, depth=0):
    dirs = 0
    files = 0
    
    for child in element:
        if child.tag == 'dir':
            dirs += 1
            d, f = count_items(child, depth + 1)
            dirs += d
            files += f
        elif child.tag == 'file':
            files += 1
    
    return dirs, files

total_dirs, total_files = count_items(root)
print(f"Total directories: {{total_dirs}}")
print(f"Total files: {{total_files}}")
print(f"Total items: {{total_dirs + total_files}}")
""")

print(f"Processing result: {{result['stdout']}}")

# Step 4: Clean up
import shutil
shutil.rmtree(test_dir)

Testing

Run the test suite:

# Using unittest
python -m unittest test.test -v

# Using pytest (if installed)
pytest test/test.py -v

Troubleshooting

Common Issues

1. "No sandbox backend available"

   • Install Daytona SDK: pip install daytona-sdk
   • Or install Docker SDK: pip install docker
   • Ensure Docker daemon is running

2. "FastMCP server won't start"

   • Check if port 8000 is already in use
   • Verify all dependencies are installed
   • Check FastMCP version compatibility

3. "Directory analysis fails"

   • Ensure you have read permissions for the target directory
   • Check that the path exists and is accessible
   • Verify .gitignore file format if present

4. "Tests fail with import errors"

   • Ensure PYTHONPATH includes the src directory
   • Check that all dependencies are installed
   • Verify you're running tests from the project root

Debug Mode

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

# Run your code - detailed logs will be shown

Project Structure

directory-intelligence-tool/
├── src/
│   ├── directory_tool.py      # Directory analysis tool
│   ├── mcp_server.py          # FastMCP server
│   └── execute_code.py        # Sandbox execution engine
├── config/
│   └── config.json            # Server configuration
├── test/
│   └── test.py                # Test suite
├── docs/
│   └── execution_README.md    # Sandbox engine documentation
├── .devcontainer/
│   └── devcontainer.json      # Development environment
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite
5. Submit a pull request

License

This project is part of the Directory Intelligence Tool suite.