fsAPId

GauteR/fsAPId

3.2

If you are the rightful owner of fsAPId and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Fileserver API for Docker (fsAPId) is a FastAPI REST API and Model Context Protocol (MCP) server designed for efficient file operations on Docker volumes.

Tools
6
Resources
0
Prompts
0

Fileserver API for Docker (fsAPId)

A FastAPI REST API and Model Context Protocol (MCP) server for handling file operations on Docker volumes.

Features

  • MCP Server: Model Context Protocol server for AI tool integration
  • REST API: FastAPI-based RESTful API with JSON responses
  • File Operations: List, read, write, delete files and directories
  • Binary File Support: Handle all file types including images, videos, executables
  • File Type Detection: Automatic MIME type detection and binary classification
  • Security: Path validation to prevent directory traversal attacks
  • Docker Ready: Containerized deployment support

Configuration

The servers can be configured using environment variables:

  • DOCKER_VOLUMES_PATH - Path to the Docker volumes directory (default: /var/lib/docker/volumes)
  • LOG_LEVEL - Logging level (default: INFO)

For Docker Compose, copy env.example to .env and modify as needed:

cp env.example .env
# Edit .env file with your preferred settings

Usage

Using Docker Compose (Recommended)

The easiest way to run the servers is with Docker Compose, which sets up a proper Docker volume:

# Start both API and MCP servers (default)
docker-compose up -d

# Start only the API server
docker-compose up -d file-api-server

# Start only the MCP server
docker-compose up -d file-mcp-server

# View logs
docker-compose logs -f

# Stop services
docker-compose down

The docker-compose setup:

  • Runs both servers by default - API server and MCP server in parallel
  • Creates a Docker volume (file-volume) for persistent file storage
  • Mounts volume to /app/data inside the container
  • Sets environment variables for proper configuration
  • Includes health checks for the API server
  • Creates local directory ./data for volume data

MCP Server

The MCP server provides the following tools with universal file type support:

  • list_files: List files and directories (includes MIME types and binary classification)
  • read_file: Read contents of any file (auto-detects text vs binary, returns base64 for binary)
  • write_file: Write content to any file (auto-detects base64 vs text content)
  • delete_file: Delete a file or directory from Docker volumes
  • create_directory: Create a directory in Docker volumes
  • get_file_info: Get detailed information including MIME type and binary classification

REST API

The FastAPI server provides the following endpoints:

File Operations

  • GET /files - List files and directories (with MIME types)
  • GET /files/{path} - Read file contents (auto-detects text/binary)
  • GET /files/{path}/binary - Read binary files as raw data
  • POST /files/{path} - Write content to file (auto-detects base64/text)
  • POST /files/{path}/binary - Upload binary files
  • DELETE /files/{path} - Delete file or directory
  • GET /files/{path}/info - Get file information (includes MIME type)

Directory Operations

  • POST /directories/{path} - Create directory

System

  • GET / - API information
  • GET /health - Health check
  • GET /stats - Volume statistics

API Documentation

  • Interactive docs: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

Example API Usage

# List files (shows MIME types and binary classification)
curl http://localhost:8000/files

# Read text files (XML, HTML, etc.)
curl http://localhost:8000/files/document.xml

# Read binary files (EPUB, images, etc.) - returns base64 encoded
curl http://localhost:8000/files/book.epub

# Read binary files as raw data
curl http://localhost:8000/files/image.jpg/binary

# Write text content
curl -X POST http://localhost:8000/files/page.html \
  -H "Content-Type: application/json" \
  -d '{"content": "<html><body>Hello World</body></html>"}'

# Write binary content (base64 encoded)
curl -X POST http://localhost:8000/files/image.jpg \
  -H "Content-Type: application/json" \
  -d '{"content": "base64_encoded_image_data"}'

# Upload binary files
curl -X POST http://localhost:8000/files/document.pdf/binary \
  -F "file=@document.pdf"

# Create directory
curl -X POST http://localhost:8000/directories/newdir

# Get file info (includes MIME type and binary classification)
curl http://localhost:8000/files/book.epub/info

# Delete file
curl -X DELETE http://localhost:8000/files/test.txt

Supported File Types

The servers handle all file types including:

Documents:

  • EPUB (.epub) - application/epub+zip
  • PDF (.pdf) - application/pdf
  • DOCX (.docx) - application/vnd.openxmlformats-officedocument.wordprocessingml.document

Web Files:

  • HTML (.html) - text/html
  • XML (.xml) - text/xml
  • CSS (.css) - text/css
  • JavaScript (.js) - application/javascript

Images:

  • JPEG (.jpg, .jpeg) - image/jpeg
  • PNG (.png) - image/png
  • GIF (.gif) - image/gif
  • SVG (.svg) - image/svg+xml

Archives:

  • ZIP (.zip) - application/zip
  • TAR (.tar) - application/x-tar
  • RAR (.rar) - application/vnd.rar

And any other file type - automatic MIME type detection

Security

Both servers include path validation to prevent directory traversal attacks and ensure all operations are contained within the specified Docker volumes directory.

Testing

Run the test suite:

python -m pytest tests/

Or run individual test files:

python tests/test_file_mcp_server.py
python tests/test_file_api_server.py