feat/file_input_output

[silvestre-perret-bentley]

This pull request introduces robust server-side file I/O support for the execute_code tool, enabling direct reading and writing of CSV/XLSX files within user-configured, validated directories. It adds comprehensive path validation, strict file size and shape limits, and Pydantic-based return value validation to ensure both security and usability. The changes also update the user configuration and documentation to reflect these new capabilities.

Major features and improvements:

1. Server-side File I/O Support

• Implements file input/output for execute_code, allowing the server to read from and write to CSV/XLSX files directly, with file data injected into the sandbox as __input__ and output written atomically. [1] [2] [3]

2. User Configuration and Path Validation

• Adds a user_config option in manifest.json for users to select allowed directories, and ensures all file operations are contained within these directories using a new path validation module. [1] [2] [3]

3. File I/O Limits and Security

• Enforces strict limits on file size, row/column/sheet counts, and allowed file extensions, with all constants centralized in file_io/const.py. [1] [2]

4. Data Validation and Model Enforcement

• Introduces Pydantic models to validate and enforce the structure and limits of return values for both flat (CSV) and multi-sheet (XLSX) outputs.

5. Dependency and Type Improvements

• Updates dependencies to include pydantic, openpyxl, defusedxml, and chardet for robust file handling, and improves type annotations for better type safety. [1] [2] [3]

Documentation and User Guidance

• Updates the README.md to document the new file I/O workflow, parameters, and security/containment guarantees.

These changes collectively provide a secure, user-friendly, and highly configurable file I/O interface for bulk data workflows in the openSTAAD MCP server.

[Copilot]

Pull request overview

This PR adds server-side CSV/XLSX file input/output support to the execute_code tool, including path containment validation (roots / allowed dirs), size/shape limits, and return-value validation to keep sandbox execution safe while enabling bulk data workflows.

Changes:

• Extend execute_code to optionally read input_path into sandbox __input__ and write result to output_path.
• Introduce a new openstaad_mcp.file_io package (readers/writers/path validation/Pydantic models) plus extensive unit tests and fixtures.
• Add CLI/config support for allowed directories (--allowed-dirs) and wire it into the packaged manifest; update README.

Reviewed changes

Copilot reviewed 34 out of 42 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/test_connection.py	Updates tool server creation in tests to pass allowed_dirs.
tests/sandbox/test_executor.py	Adds tests for __input__ injection behavior in the sandbox executor.
tests/fixtures/basic.csv	Adds CSV fixture for reader tests.
tests/fixtures/cp1252.csv	Adds CP1252 encoding fixture for CSV reader fallback tests.
tests/fixtures/empty.csv	Adds empty CSV fixture for reader edge-case tests.
tests/fixtures/header_only.csv	Adds single-row CSV fixture for header detection behavior.
tests/fixtures/no_header.csv	Adds numeric-only CSV fixture for header auto-detection.
tests/fixtures/semicolon.csv	Adds semicolon-delimited CSV fixture for dialect detection tests.
tests/fixtures/utf8.csv	Adds UTF-8 CSV fixture for encoding tests.
tests/file_io/conftest.py	Adds shared helpers for generating CSV/XLSX test files.
tests/file_io/test_path_validator.py	Adds comprehensive tests for path containment/UNC/extension/existence rules.
tests/file_io/test_readers.py	Adds tests for CSV/XLSX reading (encoding, dialect, limits, summaries).
tests/file_io/test_validation.py	Adds tests for Pydantic validation, deep-freeze behavior, and allowed-dir arg normalization.
tests/file_io/test_writers.py	Adds tests for atomic writes, overwrite behavior, and output summaries.
tests/file_io/init.py	Marks the tests.file_io package.
src/openstaad_mcp/server.py	Extends execute_code tool API to support file I/O and allowed-dir resolution.
src/openstaad_mcp/main.py	Adds --allowed-dirs CLI arg and passes validated paths into server creation.
src/openstaad_mcp/connection.py	Improves typing for connect_and_run using a TypeVar.
src/openstaad_mcp/sandbox/executor.py	Injects __input__ into sandbox globals for file-backed input.
src/openstaad_mcp/sandbox/ast.py	Allows __input__ as an exempted dunder name in AST validation.
src/openstaad_mcp/sandbox/const.py	Adds INPUT_DATA_VARIABLE_NAME and ALLOWED_DUNDER_NAMES.
src/openstaad_mcp/sandbox/com_proxy.py	Adds/adjusts header comment block.
src/openstaad_mcp/sandbox/module_proxy.py	Adds/adjusts header comment block.
src/openstaad_mcp/sandbox/stdio_helpers.py	Adds/adjusts header comment block.
src/openstaad_mcp/file_io/init.py	Exposes the new file I/O public API from the file_io package.
src/openstaad_mcp/file_io/const.py	Centralizes file I/O limits and constants.
src/openstaad_mcp/file_io/helpers.py	Adds dispatch/helpers for roots/allowed-dirs resolution and I/O operations.
src/openstaad_mcp/file_io/models.py	Introduces Pydantic models and cell validation for output structures.
src/openstaad_mcp/file_io/path_validator.py	Adds path validation (roots guard, resolve, UNC reject, containment, extension, existence).
src/openstaad_mcp/file_io/readers.py	Implements CSV/XLSX readers, header detection, coercion, and summaries.
src/openstaad_mcp/file_io/validation.py	Adds return-value validation, deep-freeze, and allowed-dirs arg normalization.
src/openstaad_mcp/file_io/writers.py	Implements atomic CSV/XLSX writers and summary generation.
src/openstaad_mcp/file_io.py	Adds a second (monolithic) file I/O implementation that conflicts with the new package.
README.md	Documents new file I/O parameters and containment/limits (needs alignment with allowed-dirs behavior).
pyproject.toml	Adds dependencies required for file I/O + validation (pydantic/openpyxl/defusedxml/chardet).
mcpb/manifest.json	Adds user-configurable allowed directories and passes them to the server via CLI args.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.