feat: Initial project setup

Author: safurrier

.github/workflows/tests.yml

@@ -0,0 +1,55 @@
+name: Code Quality Checks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          
+      - name: Install uv
+        run: pip install uv
+        
+      - name: Install dependencies
+        run: |
+          uv pip compile pyproject.toml -o requirements.txt
+          uv pip compile pyproject.toml --extra dev -o requirements-dev.txt
+          uv venv
+          uv pip sync requirements.txt requirements-dev.txt
+          
+      - name: Determine module name
+        id: module
+        run: |
+          if [ -d "src" ]; then
+            echo "name=src" >> $GITHUB_OUTPUT
+          else
+            MODULE_NAME=$(basename $(find . -maxdepth 1 -type d -not -path "*/\.*" -not -path "./tests" -not -path "./scripts" -not -path "./docker" -not -path "." | sort | head -1))
+            echo "name=$MODULE_NAME" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: Run Linter
+        run: uv run -m ruff check --fix ${{ steps.module.outputs.name }}
+        
+      - name: Run Formatter
+        run: uv run -m ruff format ${{ steps.module.outputs.name }}
+        
+      - name: Run Tests
+        run: uv run -m pytest tests --cov=${{ steps.module.outputs.name }} --cov-report=term-missing --cov-report=xml
+        
+      - name: Run MyPy
+        run: uv run -m mypy ${{ steps.module.outputs.name }}
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        continue-on-error: true
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.idea/
+.venv/
+_build/
+notebooks/
+setup
+conf.py
+index.rst
+.coverage
+*.pyc
+setup_mac.sh
+docker/.env
+.vs_code/*
+.mypy_cache/*
+.pytest_cache/*
+.ruff_cache/*
+.aider*
+CLAUDE.md

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+-   repo: local
+    hooks:
+    -   id: lint
+        name: Run Linter
+        entry: make lint
+        language: system
+        always_run: true
+        pass_filenames: false
+    -   id: format
+        name: Run Formatter
+        entry: make format
+        language: system
+        always_run: true
+        pass_filenames: false
+    -   id: test
+        name: Run Tests
+        entry: make test
+        language: system
+        always_run: true
+        pass_filenames: false
+    -   id: mypy
+        name: Run MyPy
+        entry: make mypy
+        language: system
+        always_run: true
+        pass_filenames: false

CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Integration with uv for dependency management
+- Modern Python development tools:
+  - ruff for linting and formatting
+  - mypy for type checking
+  - pytest with coverage reporting
+- GitHub Actions workflow for automated testing
+- Docker development environment improvements
+
+### Changed
+- Switched from pip/venv to uv for environment management
+- Updated example code to pass mypy type checking
+- Modernized project structure and development workflow
+- Updated Python version to 3.12
+
+### Removed
+- Legacy dependency management approach
+- Outdated Docker configuration elements
+
+### Fixed
+- Type hints in example code to pass mypy checks
+- Docker environment management
+- Development workflow and quality checks
+
+## [0.1.0] - 2024-04-14
+- Initial fork from eugeneyan/python-collab-template
+- Added Docker environment management
+- Setup package installation configuration

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to Python Collab Template
+
+Thank you for your interest in contributing to this project!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone [email protected]:your-username/python-collab-template.git`
+3. Create a new branch: `git checkout -b feature-name`
+4. Make your changes
+5. Run quality checks: `make check`
+6. Commit your changes: `git commit -m "Description of changes"`
+7. Push to your fork: `git push origin feature-name`
+8. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Install dependencies and set up environment
+make setup
+
+# Run all quality checks
+make check
+```
+
+## Code Quality Standards
+
+- All code must be typed with proper type hints
+- Tests must be included for new features
+- Documentation must be updated when necessary
+- All quality checks must pass (`make check`)
+
+## Pull Request Process
+
+1. Update the README.md with details of significant changes
+2. Update the CHANGELOG.md following the existing format
+3. The PR will be merged once you have the sign-off of at least one maintainer
+
+## Questions?
+
+Feel free to open an issue for any questions or concerns.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alex Furrier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,101 @@
+.PHONY: compile-deps setup clean-pyc clean-test clean-venv clean test mypy lint format check clean-example dev-env refresh-containers rebuild-images build-image push-image
+
+# Module name - will be updated by init script
+MODULE_NAME := mcp_filesystem
+
+# Development Setup
+#################
+compile-deps:  # Compile dependencies from pyproject.toml
+	uv pip compile pyproject.toml -o requirements.txt
+	uv pip compile pyproject.toml --extra dev -o requirements-dev.txt
+
+PYTHON_VERSION ?= 3.12
+
+ensure-uv:  # Install uv if not present
+	@which uv > /dev/null || (curl -LsSf https://astral.sh/uv/install.sh | sh)
+
+setup: ensure-uv compile-deps ensure-scripts  # Install dependencies
+	UV_PYTHON_VERSION=$(PYTHON_VERSION) uv venv
+	UV_PYTHON_VERSION=$(PYTHON_VERSION) uv pip sync requirements.txt requirements-dev.txt
+	$(MAKE) install-hooks
+
+install-hooks:  # Install pre-commit hooks if in a git repo with hooks configured
+	@if [ -d .git ] && [ -f .pre-commit-config.yaml ]; then \
+		echo "Installing pre-commit hooks..."; \
+		uv run pre-commit install; \
+	fi
+
+ensure-scripts:  # Ensure scripts directory exists and files are executable
+	mkdir -p scripts
+	chmod +x scripts/*.py
+
+# Cleaning
+#########
+clean-pyc:  # Remove Python compilation artifacts
+	find . -name '*.pyc' -exec rm -f {} +
+	find . -name '*.pyo' -exec rm -f {} +
+	find . -name '*~' -exec rm -f {} +
+	find . -name '__pycache__' -exec rm -fr {} +
+
+clean-test:  # Remove test and coverage artifacts
+	rm -f .coverage
+	rm -f .coverage.*
+
+clean-venv:  # Remove virtual environment
+	rm -rf .venv
+
+clean: clean-pyc clean-test clean-venv
+
+# Testing and Quality Checks
+#########################
+test: setup  # Run pytest with coverage
+	uv run -m pytest tests --cov=$(MODULE_NAME) --cov-report=term-missing
+
+mypy: setup  # Run type checking
+	uv run -m mypy $(MODULE_NAME)
+
+lint: setup  # Run ruff linter with auto-fix
+	uv run -m ruff check --fix $(MODULE_NAME)
+
+format: setup  # Run ruff formatter
+	uv run -m ruff format $(MODULE_NAME)
+
+check: setup lint format test mypy  # Run all quality checks
+
+# Project Management
+##################
+clean-example:  # Remove example code (use this to start your own project)
+	rm -rf src/example.py tests/test_example.py
+	touch src/__init__.py tests/__init__.py
+
+init: setup  # Initialize a new project
+	uv run python scripts/init_project.py
+
+# Docker
+########
+IMAGE_NAME = container-registry.io/python-collab-template
+IMAGE_TAG = latest
+
+dev-env: refresh-containers
+	@echo "Spinning up a dev environment ."
+	@docker compose -f docker/docker-compose.yml down
+	@docker compose -f docker/docker-compose.yml up -d dev
+	@docker exec -ti composed_dev /bin/bash
+
+refresh-containers:
+	@echo "Rebuilding containers..."
+	@docker compose -f docker/docker-compose.yml build
+
+rebuild-images:
+	@echo "Rebuilding images with the --no-cache flag..."
+	@docker compose -f docker/docker-compose.yml build --no-cache
+
+build-image:
+	@echo Building dev image and tagging as ${IMAGE_NAME}:${IMAGE_TAG}
+	@docker compose -f docker/docker-compose.yml down
+	@docker compose -f docker/docker-compose.yml up -d dev
+	@docker tag dev ${IMAGE_NAME}:${IMAGE_TAG}
+
+push-image: build-image
+	@echo Pushing image to container registry
+	@docker push ${IMAGE_NAME}:${IMAGE_TAG}