@mseep/csv-editor 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# 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).
+
+## [2.0.0] - 2026-04-20
+
+### BREAKING CHANGES
+- **Python floor raised to 3.11.** Users on Python 3.8, 3.9, or 3.10 must upgrade. Users who pinned `csv-editor>=1,<2` are unaffected.
+- **`--transport sse` CLI option removed.** Use `--transport http` (Streamable HTTP) for remote deployments. This aligns with the MCP 2025-11-25 spec and FastMCP 3 guidance that SSE is "backward compatibility only, shouldn't be used in new projects."
+- **FastMCP dependency bumped to `>=3.2,<4`.** Any code importing FastMCP APIs transitively may require updates per the [FastMCP 3 upgrade guide](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2).
+
+### Added
+- GitHub Actions `test.yml` workflow: pytest matrix on Python 3.11–3.14.
+- `tests/test_server_boot.py` regression tests for server import, tool registry size, and CLI argument handling.
+- Python 3.14 classifier and test coverage.
+- Contributing guide: local virtualenv rebuild instructions.
+- Design spec and implementation plan for the v2.0.0 migration under `specs/` and `plans/`.
+
+### Changed
+- Python floor: `>=3.10` → `>=3.11`.
+- `fastmcp`: `>=2.11.3` → `>=3.2,<4` (resolved to 3.2.4).
+- `pydantic`: `>=2.10.4` → `>=2.13`.
+- `pydantic-settings`: `>=2.10.1` → `>=2.13`.
+- `pyarrow`: `>=17.0.0` → `>=23`.
+- `httpx`: `>=0.27.0` → `>=0.28`.
+- `aiofiles`: `>=24.1.0` → `>=25`.
+- `tabulate`: `>=0.9.0` → `>=0.10`.
+- `black` target-version: `["py38", "py39", "py310", "py311", "py312", "py313"]` → `["py311", "py312", "py313"]` (black stable does not yet support `py314` as a target).
+- `ruff` target-version: `py38` → `py311`.
+- `mypy` python_version: `3.8` → `3.11`.
+- Applied ruff `--fix` and `black` formatting across `src/` and `tests/` now that Python 3.11+ is the floor (large diff, no behavior change).
+- Dockerfile base image pinned to `python:3.11-slim-bookworm`.
+- `main()` signature: now accepts optional `argv: list[str] | None` for testability.
+- README Python badge updated from `3.8+` to `3.11+`.
+
+### Removed
+- `--transport sse` CLI option.
+- Python 3.8, 3.9, 3.10 classifier entries.
+
+### Unchanged (deferred to follow-up release)
+- `pandas>=2.2.3` and `numpy>=2.1.3`. Upgrading to pandas 3.0 (Copy-on-Write mandatory, Arrow-backed default string dtype) is deferred to a focused sub-project because the behavioral changes deserve dedicated test coverage.
+
+## [1.0.1] - 2025-08-13
+
+### Changed
+- **Publishing strategy**: Switched to GitHub-based distribution due to PyPI naming conflicts
+- **Installation method**: Primary installation now via `pip install git+https://github.com/santoshray02/csv-editor.git`
+- **Package name**: Kept original `csv-editor` name
+
+### Added
+- Alternative publishing guide (ALTERNATIVE_PUBLISHING.md)
+- GitHub Packages publishing workflow
+- GitHub Releases automation
+- Multiple installation methods for users
+
+## [1.0.0] - 2025-08-13
+
+### Added
+- Initial release of CSV Editor MCP Server
+- Core CSV operations: read, write, filter, transform
+- Data validation and quality checks
+- Statistical analysis and profiling capabilities
+- Outlier detection and handling
+- Support for multiple file formats (CSV, Excel, Parquet)
+- Async operations for high performance
+- Comprehensive error handling and logging
+- FastMCP integration for seamless AI assistant integration
+- Pandas-powered data manipulation
+- Full test coverage with pytest
+- Documentation with examples
+- Type hints and mypy compatibility
+
+### Features
+- **File Operations**: Read/write CSV, Excel, Parquet files
+- **Data Filtering**: Advanced filtering with multiple conditions
+- **Data Transformation**: Column operations, data type conversions
+- **Data Validation**: Schema validation, data quality checks
+- **Statistical Analysis**: Descriptive statistics, correlation analysis
+- **Outlier Detection**: Multiple algorithms (IQR, Z-score, Isolation Forest)
+- **Data Profiling**: Comprehensive data profiling reports
+- **Performance**: Optimized for large datasets with chunking support
+- **AI Integration**: Seamless integration with Claude, ChatGPT, and other AI assistants
+
+### Technical Details
+- Python 3.10+ support
+- Built with FastMCP framework
+- Pandas and NumPy for data operations
+- Pydantic for data validation
+- Async/await support for non-blocking operations
+- Comprehensive error handling
+- Type-safe with mypy
+- 100% test coverage
+
+[2.0.0]: https://github.com/santoshray02/csv-editor/releases/tag/v2.0.0
+[1.0.1]: https://github.com/santoshray02/csv-editor/releases/tag/v1.0.1
+[1.0.0]: https://github.com/santoshray02/csv-editor/releases/tag/v1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at rayskumar02@gmail.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,427 @@
+# Contributing to CSV Editor
+
+Thank you for your interest in contributing to CSV Editor! This guide will help you get started with contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Development Workflow](#development-workflow)
+- [Code Standards](#code-standards)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [Submitting Changes](#submitting-changes)
+- [Release Process](#release-process)
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our Code of Conduct:
+
+- Be respectful and inclusive
+- Welcome newcomers and help them get started
+- Focus on constructive criticism
+- Accept feedback gracefully
+- Put the project's best interests first
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/santoshray02/csv-editor.git
+   cd csv-editor
+   ```
+3. **Add upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/santoshray02/csv-editor.git
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11 or higher (3.14 recommended)
+- Git
+- [uv](https://github.com/astral-sh/uv) - Ultra-fast package manager (required)
+
+### Installation
+
+#### Using uv (Required - 10-100x faster than pip)
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Or on macOS: brew install uv
+# Or with pip: pip install uv
+
+# Clone and setup in one command!
+uv sync --all-extras
+
+# Install pre-commit hooks
+uv run pre-commit install
+
+# That's it! You're ready to go in seconds!
+```
+
+#### Alternative: Using pip (slower, not recommended)
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode
+pip install -e ".[dev,test,docs]"
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+**Note**: We standardize on `uv` for all development. It's significantly faster and handles everything pip does plus more.
+
+### Verify Installation
+
+```bash
+# All commands use uv
+uv run server --help
+uv run test
+uv run lint
+
+# Or use the shortcuts defined in uv.toml
+uv run all-checks  # Runs all quality checks
+```
+
+### Rebuilding the local virtualenv
+
+If your `.venv/` points at a missing Python interpreter (common after upgrading Python or removing a conda env), rebuild it:
+
+```bash
+rm -rf .venv
+uv sync --all-extras
+```
+
+This requires Python 3.11+ available on your PATH (3.14 recommended).
+
+## Development Workflow
+
+### 1. Create a Feature Branch
+
+```bash
+# Update main branch
+git checkout main
+git pull upstream main
+
+# Create feature branch
+git checkout -b feature/your-feature-name
+```
+
+### 2. Make Your Changes
+
+Follow these guidelines:
+
+- **One feature per PR** - Keep pull requests focused
+- **Write tests** - All new features must have tests
+- **Update docs** - Update README and docstrings as needed
+- **Follow style guide** - Use Black, Ruff, and MyPy
+
+### 3. Run Quality Checks
+
+```bash
+# All commands use uv for speed and consistency
+uv run fmt         # Format code with Black
+uv run lint        # Lint with Ruff
+uv run type-check  # Type check with MyPy
+uv run all-checks  # Run everything at once
+```
+
+### 4. Test Your Changes
+
+```bash
+# Testing with uv
+uv run test                              # Run all tests
+uv run test-cov                          # Run with coverage report
+uv run pytest tests/test_transformations.py  # Run specific file
+uv run pytest -k "test_filter"          # Run tests matching pattern
+uv run pytest -x                         # Stop on first failure
+```
+
+## Code Standards
+
+### Python Style
+
+We use modern Python tooling for code quality:
+
+- **Black** for code formatting (line length: 100)
+- **Ruff** for linting (replaces flake8, isort, and more)
+- **MyPy** for type checking
+- **Pre-commit** for automated checks
+
+### Code Guidelines
+
+1. **Type Hints**: All functions must have type hints
+   ```python
+   async def process_data(
+       session_id: str,
+       options: Dict[str, Any],
+       ctx: Optional[Context] = None
+   ) -> Dict[str, Any]:
+       """Process data with given options."""
+       ...
+   ```
+
+2. **Docstrings**: Use Google-style docstrings
+   ```python
+   def analyze_data(df: pd.DataFrame) -> Dict[str, Any]:
+       """Analyze DataFrame and return statistics.
+       
+       Args:
+           df: Input DataFrame to analyze
+           
+       Returns:
+           Dictionary containing analysis results
+           
+       Raises:
+           ValueError: If DataFrame is empty
+       """
+   ```
+
+3. **Error Handling**: Use specific exceptions
+   ```python
+   if not session:
+       raise ValueError(f"Session {session_id} not found")
+   ```
+
+4. **Async/Await**: Use async for all tool functions
+   ```python
+   @mcp.tool
+   async def my_tool(param: str, ctx: Context) -> Dict[str, Any]:
+       result = await async_operation(param)
+       return {"success": True, "data": result}
+   ```
+
+5. **Logging**: Use appropriate log levels
+   ```python
+   logger.debug("Processing row %d", row_num)
+   logger.info("Session %s created", session_id)
+   logger.warning("Large dataset: %d rows", row_count)
+   logger.error("Failed to load file: %s", error)
+   ```
+
+### File Structure
+
+```
+src/csv_editor/
+├── __init__.py          # Package initialization
+├── server.py            # Main server entry point
+├── models/              # Data models and schemas
+│   ├── __init__.py
+│   ├── csv_session.py   # Session management
+│   └── data_models.py   # Pydantic models
+├── tools/               # MCP tool implementations
+│   ├── __init__.py
+│   ├── io_operations.py
+│   ├── transformations.py
+│   ├── analytics.py
+│   └── validation.py
+├── resources/           # MCP resources
+├── prompts/            # MCP prompts
+└── utils/              # Utility functions
+```
+
+## Testing
+
+### Test Structure
+
+```
+tests/
+├── unit/               # Unit tests
+│   ├── test_models.py
+│   ├── test_transformations.py
+│   └── test_analytics.py
+├── integration/        # Integration tests
+│   ├── test_server.py
+│   └── test_workflows.py
+├── benchmark/          # Performance tests
+│   └── test_performance.py
+└── fixtures/           # Test data
+    └── sample_data.csv
+```
+
+### Writing Tests
+
+1. **Use pytest fixtures**:
+   ```python
+   @pytest.fixture
+   async def session_with_data():
+       """Create a session with sample data."""
+       manager = get_session_manager()
+       session_id = manager.create_session()
+       # ... setup
+       yield session_id
+       # ... cleanup
+       manager.remove_session(session_id)
+   ```
+
+2. **Test async functions**:
+   ```python
+   @pytest.mark.asyncio
+   async def test_filter_rows(session_with_data):
+       result = await filter_rows(
+           session_id=session_with_data,
+           conditions=[{"column": "age", "operator": ">", "value": 18}]
+       )
+       assert result["success"]
+       assert result["rows_after"] < result["rows_before"]
+   ```
+
+3. **Use parametrize for multiple cases**:
+   ```python
+   @pytest.mark.parametrize("dtype,expected", [
+       ("int", True),
+       ("float", True),
+       ("str", False),
+   ])
+   def test_is_numeric(dtype, expected):
+       assert is_numeric_dtype(dtype) == expected
+   ```
+
+### Coverage Requirements
+
+- Minimum coverage: 80%
+- New features must have >90% coverage
+- Run coverage: `hatch run test-cov`
+
+## Documentation
+
+### Docstring Standards
+
+All public functions, classes, and modules must have docstrings:
+
+```python
+"""Module description.
+
+This module provides functionality for X, Y, and Z.
+"""
+
+class DataProcessor:
+    """Process CSV data with various transformations.
+    
+    Attributes:
+        session_id: Unique session identifier
+        df: Pandas DataFrame containing the data
+    """
+    
+    def transform(
+        self,
+        operation: str,
+        **kwargs: Any
+    ) -> pd.DataFrame:
+        """Apply transformation to data.
+        
+        Args:
+            operation: Name of the transformation
+            **kwargs: Additional parameters for the operation
+            
+        Returns:
+            Transformed DataFrame
+            
+        Raises:
+            ValueError: If operation is not supported
+            
+        Examples:
+            >>> processor.transform("normalize", columns=["price"])
+            >>> processor.transform("fill_missing", strategy="mean")
+        """
+```
+
+### Updating Documentation
+
+1. **README.md**: Update for new features or breaking changes
+2. **API Docs**: Ensure docstrings are complete
+3. **Examples**: Add examples for new features
+4. **Changelog**: Update CHANGELOG.md
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Update your branch**:
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+3. **Create Pull Request**:
+   - Go to GitHub and create a PR from your fork
+   - Use a clear, descriptive title
+   - Fill out the PR template
+   - Link related issues
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] Tests pass locally
+- [ ] Added new tests
+- [ ] Coverage maintained/improved
+
+## Checklist
+- [ ] Code follows style guidelines
+- [ ] Self-review completed
+- [ ] Documentation updated
+- [ ] No new warnings
+```
+
+### Review Process
+
+1. **Automated checks** must pass
+2. **Code review** by at least one maintainer
+3. **Address feedback** promptly
+4. **Squash commits** if requested
+
+## Release Process
+
+### Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes
+
+### Release Steps
+
+1. **Update version** in `pyproject.toml`
+2. **Update CHANGELOG.md**
+3. **Create release PR**
+4. **Tag release** after merge
+5. **Publish to PyPI** (automated)
+
+## Getting Help
+
+- **Issues**: Use GitHub Issues for bugs and features
+- **Discussions**: Use GitHub Discussions for questions
+- **Discord**: Join our Discord server (link in README)
+
+## Recognition
+
+Contributors are recognized in:
+- AUTHORS.md file
+- Release notes
+- Project README
+
+Thank you for contributing to CSV Editor! 🎉

package/Dockerfile

@@ -0,0 +1,22 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/build/project-config
+FROM python:3.11-slim-bookworm
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends gcc python3-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml requirements.txt README.md ./
+COPY src/ src/
+
+# Install Python dependencies and project
+RUN pip install --no-cache-dir -r requirements.txt && \
+    pip install --no-cache-dir .
+
+# Default command
+ENV PYTHONUNBUFFERED=1
+CMD ["csv-editor", "--transport", "stdio"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Santosh Ray
+
+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.