feat: Initial release of MCP-Filesystem with comprehensive test suite

  This initial release delivers a complete filesystem server built on the Model Context
  Protocol (MCP) that enables secure file operations from AI agents:

  Core Features:
  - Secure filesystem access with path validation and allowed directory enforcement
  - Rich file operations including read, write, edit, move, and search
  - Advanced grep functionality with regex support and contextual results
  - Directory traversal with configurable depth and pattern matching
  - End-to-end API for AI agent integration

  Testing Infrastructure:
  - Comprehensive behavior-driven test suite with 75 passing tests
  - Unit, integration, and end-to-end test coverage (46% overall)
  - Real filesystem fixtures for realistic testing scenarios
  - Cross-platform compatibility for path handling
  - Resilient assertions focused on behavior, not implementation

  The codebase is structured with clean separation of concerns:
  - security.py: Path validation and safety checks
  - operations.py: Core file operations
  - grep.py: Text search capabilities
  - advanced.py: Enhanced filesystem operations
  - server.py: FastMCP API endpoints

  This implementation provides a secure and feature-rich filesystem interface
  for AI tools and agents to safely interact with local files.

Author: safurrier

.gitignore

@@ -16,3 +16,4 @@ docker/.env
 .ruff_cache/*
 .aider*
 CLAUDE.md
+docs/**

CHANGELOG.md

@@ -8,30 +8,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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
+- Grep functionality exposed through MCP
+  - Support for ripgrep with Python fallback
+  - Comprehensive search with regex, context, and pattern exclusion
+  - Enhanced context control with separate before/after line parameters (like grep's -A/-B options)
+  - Results pagination with offset/limit parameters
+- Line-targeted file operations
+  - `read_file_lines` with offset/limit paradigm for precise line access
+  - `edit_file_at_line` with content verification and relative line number support
+- Integration between grep and targeted operations for efficient workflow
+- Documentation of type safety issues and guidance in CLAUDE.md
+- Comprehensive test suite following pragmatic test-driven development approach
+  - Smoke tests for critical user paths (read, write, grep, edit)
+  - Integration tests with real temporary filesystem
+  - End-to-end tests verifying server API to filesystem flow
+  - Test data factories for sample data generation
+  - Clean fixtures with proper dependency isolation
+  - Mocks at external boundaries for faster test execution
+  - Verification of actual functionality with real files
 
 ### 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
+- Improved Python compatibility (requires 3.10+)
+- Enhanced server file operations with more granular edit capability
+- Changed line-targeting API from 1-based to 0-based indexing with offset/limit paradigm
+- Added content verification to file editing operations
+- Added relative line numbers support for more flexible line editing
+- Enhanced grep functionality with better context control and pagination
+- Improved code safety with proper null checks for Context parameters
+- Enhanced type safety with proper use of Optional types
 
 ### 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
+- Integrated targeted operations and grep functionality into the main codebase
+- Connected all components in the server implementation
+- Fixed unsafe comparison between int and None
+- Improved anyio.to_thread.run_sync usage with functools.partial
+- Fixed context_before type mismatch in grep.py
+- Properly typed transport parameter with Literal
+- Fixed all type errors in server.py, operations.py, advanced.py, and grep.py
+- Added type annotations for result variables and function parameters
+- Fixed `Dict` type incompatibility issue in advanced.py
+- Added missing imports from typing module (Any, Mapping)
+- Fixed read_file_lines bug that caused it to read beyond the requested line range
+- Fixed edit_file_at_line to properly handle content verification and relative line numbers
+- Fixed grep pagination to properly slice result sets
+- Improved test reliability by focusing on behavior rather than implementation details
+- Fixed inconsistent test expectations to match actual API semantics
+
+## [0.1.0] - 2025-03-02
+- Initial project setup
+- Basic file operations implementation
+- Security framework for file access
+- Server structure and MCP integration

PUBLISHING.md

@@ -0,0 +1,69 @@
+# Publishing Guide
+
+This document contains instructions for publishing the package to PyPI.
+
+## Prerequisites
+
+1. Create accounts on [PyPI](https://pypi.org/) and [TestPyPI](https://test.pypi.org/) (optional for testing)
+2. Install build tools:
+   ```bash
+   uv pip install --upgrade build twine
+   ```
+
+## Build the Package
+
+1. Ensure the version number is updated in `pyproject.toml`
+2. Build the distribution packages:
+   ```bash
+   python -m build
+   ```
+   This will create both source and wheel distributions in the `dist/` directory.
+
+## Test the Package (Optional)
+
+1. Upload to TestPyPI:
+   ```bash
+   twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+   ```
+2. Install and test from TestPyPI:
+   ```bash
+   uv pip install --index-url https://test.pypi.org/simple/ --no-deps mcp-filesystem
+   ```
+
+## Publish to PyPI
+
+1. Upload to PyPI:
+   ```bash
+   twine upload dist/*
+   ```
+
+## Create GitHub Release
+
+1. Create a git tag for the version:
+   ```bash
+   git tag -a v0.2.0 -m "Version 0.2.0"
+   git push origin v0.2.0
+   ```
+2. Create a new release on GitHub:
+   - Go to the repository page on GitHub
+   - Click on "Releases"
+   - Click "Create a new release"
+   - Select the tag you just created
+   - Add release notes (use the relevant section from CHANGELOG.md)
+   - Publish the release
+
+## Verify Package Installation
+
+After publishing, verify that the package can be installed:
+
+```bash
+uv pip install mcp-filesystem
+```
+
+## Troubleshooting
+
+If you encounter issues when publishing:
+
+1. **Upload errors**: Verify that the package name is not already in use on PyPI
+2. **Invalid credentials**: Check your PyPI credentials in `~/.pypirc`
+3. **Build errors**: Make sure `pyproject.toml` is correctly formatted