Contributing to MCP File System Server

Thank you for your interest in contributing to the MCP File System Server! This guide will help you set up your development environment and understand the contribution process.

Development Setup

Setting up the development environment

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp-workspace.git
cd mcp-workspace

# Create and activate a virtual environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev,config]"

Running from Source (Development Mode)

For development and testing, you can run the server directly from source without installation:

Method 1: Module execution

python -m src.main --project-dir /path/to/project [--log-level LEVEL] [--log-file PATH]

Method 2: Direct script execution

# On Windows:
set PYTHONPATH=%PYTHONPATH%;.
python .\src\main.py --project-dir /path/to/project

# On macOS/Linux:
export PYTHONPATH=$PYTHONPATH:.
python ./src/main.py --project-dir /path/to/project

Testing with MCP Inspector

MCP Inspector is excellent for debugging and testing during development:

# Start MCP Inspector
npx @modelcontextprotocol/inspector \
  uv \
  --directory C:\path\to\mcp_workspace \
  run \
  src\main.py

In the MCP Inspector web UI, configure:

• Python interpreter: C:\path\to\mcp_workspace\.venv\Scripts\python.exe
• Arguments: C:\path\to\mcp_workspace\src\main.py --project-dir C:\path\to\your\test\project --log-level DEBUG
• Environment variables:
  • Name: PYTHONPATH
  • Value: C:\path\to\mcp_workspace\

Testing

The project includes comprehensive pytest-based unit tests.

Test Structure

• tests/ - Main test directory
• tests/file_tools/ - Tests for file operation tools
• tests/testdata/ - Test data files
• See tests/README.md for detailed test documentation

LLM Testing

For LLM-based testing, see tests/LLM_Test.md - this contains test instructions you can paste directly to an LLM to verify server functionality.

Development Tools

The project includes several development utility scripts in the tools/ directory:

• format_all.bat - Format code with Black and isort
• pylint_check_for_errors.bat - Run pylint checks
• reinstall.bat - Reinstall the package in development mode
• update_packages.bat - Update dependencies

Code Style

The project uses:

• Black for code formatting (line length: 88)
• isort for import sorting
• pylint for code quality checks

Troubleshooting Development Setup

Common Issues

1. Import errors: Ensure PYTHONPATH includes the repository root
2. Python path issues: Verify your virtual environment is activated
3. Missing dependencies: Run pip install -e ".[dev]" to ensure dev dependencies are installed

Development Logs

• Server logs are written to project_dir/logs/mcp_workspace_*.log
• Use --log-level DEBUG for detailed development logging
• Check console output for immediate feedback

Contribution Guidelines

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Follow code style guidelines (Black, isort, pylint)
4. Update documentation as needed
5. Test thoroughly including edge cases
6. Submit a pull request with a clear description

Project Structure

mcp-workspace/
├── src/                    # Main source code
│   ├── main.py            # Entry point and CLI
│   ├── server.py          # MCP server implementation
│   ├── log_utils.py       # Logging utilities
│   └── file_tools/        # File operation tools
├── tests/                 # Test suite
├── tools/                 # Development utilities
├── pyproject.toml         # Project configuration
└── README.md              # User documentation

Questions or Issues?

• Open an issue on GitHub for bugs or feature requests
• Check existing issues before creating new ones
• Include detailed information about your development environment