GauteR/fsAPId
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.
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 volumescreate_directory
: Create a directory in Docker volumesget_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 dataPOST /files/{path}
- Write content to file (auto-detects base64/text)POST /files/{path}/binary
- Upload binary filesDELETE /files/{path}
- Delete file or directoryGET /files/{path}/info
- Get file information (includes MIME type)
Directory Operations
POST /directories/{path}
- Create directory
System
GET /
- API informationGET /health
- Health checkGET /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