chuk-mcp-solver 0.1.2__tar.gz

chuk_mcp_solver-0.1.2/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(uv pip install:*)",
+      "Bash(uv venv:*)",
+      "Bash(source .venv/bin/activate)",
+      "Bash(pytest:*)",
+      "Bash(python:*)",
+      "Bash(pip install:*)",
+      "Bash(=9.10.0)",
+      "Bash(uv pip list:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(make check:*)",
+      "Bash(make format:*)",
+      "Bash(make typecheck:*)",
+      "Bash(cat:*)",
+      "Bash(uv run python:*)",
+      "Bash(timeout 10 uv run pytest:*)",
+      "Bash(make:*)",
+      "Bash(python3.11 -m pytest:*)",
+      "Bash(uv run mypy:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

chuk_mcp_solver-0.1.2/.dockerignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# CI/CD
+.github/
+
+# Documentation
+docs/
+
+# Other
+*.md
+!README.md
+.DS_Store
+*.log

chuk_mcp_solver-0.1.2/.github/workflows/fly-deploy.yml

@@ -0,0 +1,18 @@
+# See https://fly.io/docs/app-guides/continuous-deployment-with-github-actions/
+
+name: Fly Deploy
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    name: Deploy app
+    runs-on: ubuntu-latest
+    concurrency: deploy-group    # optional: ensure only one action runs at a time
+    steps:
+      - uses: actions/checkout@v4
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      - run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

chuk_mcp_solver-0.1.2/.github/workflows/test.yml

@@ -0,0 +1,65 @@
+name: Test
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Lint with ruff
+        run: |
+          uv run ruff check src/ tests/
+
+      - name: Format check with ruff
+        run: |
+          uv run ruff format --check src/ tests/
+
+      - name: Type check with mypy
+        run: |
+          uv run mypy src/
+
+      - name: Run tests
+        run: |
+          uv run pytest tests/ -v --tb=short -m "not network"
+
+      - name: Run tests with coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          uv run pytest tests/ --cov=src/chuk_mcp_solver --cov-report=xml --cov-report=term -m "not network"
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Check coverage threshold
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          uv run pytest tests/ --cov=src/chuk_mcp_solver --cov-report=term --cov-fail-under=90 -m "not network"

chuk_mcp_solver-0.1.2/.gitignore

@@ -0,0 +1,140 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Ruff
+.ruff_cache/
+
+# uv
+.uv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.bak

chuk_mcp_solver-0.1.2/CHANGELOG.md

@@ -0,0 +1,134 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.1] - 2025-12-02
+
+### Fixed
+
+#### Cache Deadlock Fix
+- **Issue**: `test_cache_stats` test was hanging due to deadlock in `SolutionCache.stats()` method
+- **Root Cause**: The `stats()` method acquired `self._lock`, then called the `hit_rate` property which tried to acquire the same lock again. Since `threading.Lock` is not reentrant, this caused a deadlock.
+- **Fix**: Changed `threading.Lock` to `threading.RLock` (Reentrant Lock) in `src/chuk_mcp_solver/cache.py`
+  - Line 10: Updated import from `Lock` to `RLock`
+  - Line 38: Changed `self._lock = Lock()` to `self._lock = RLock()`
+- **Impact**: All cache tests now pass without hanging
+
+#### Performance Test Fix
+- **Issue**: `test_partial_solution_on_timeout` was failing with timeout status instead of returning a partial solution
+- **Root Cause**: Test timeout was too short (1ms) for OR-Tools CP-SAT to find even a trivial feasible solution before timing out
+- **Fix**: Increased timeout in `tests/test_performance.py:178` from 1ms to 50ms
+- **Additional**: Updated `src/chuk_mcp_solver/solver/ortools/solver.py:164` to check for both `cp_model.FEASIBLE` and `cp_model.OPTIMAL` statuses when handling partial solutions
+- **Impact**: Test now reliably passes by giving solver enough time to find at least one feasible solution
+
+### Added
+
+#### Docker Support
+- **Dockerfile**: Multi-stage build for optimized image size (~300-400MB)
+  - Based on `python:3.11-slim`
+  - Runs as non-root user (`mcpuser`) for security
+  - Includes health check
+  - Default command: HTTP mode on port 8000
+- **docker-compose.yml**: Service definition with resource limits and health checks
+- **.dockerignore**: Optimizes Docker build context by excluding unnecessary files
+- **DOCKER.md**: Comprehensive Docker usage guide with examples for:
+  - Building and running containers
+  - Configuration with environment variables
+  - Transport modes (HTTP vs STDIO)
+  - Production deployment
+  - CI/CD integration
+  - Troubleshooting
+
+#### Makefile Docker Targets
+- `docker-build`: Build Docker image
+- `docker-run`: Run Docker container
+- `docker-stop`: Stop running container
+- `docker-clean`: Remove container and image
+- `docker-test`: Run tests in Docker container
+- `docker-shell`: Open shell in running container
+- `docker-push`: Push image to registry
+- `docker-compose-up`: Start services with docker-compose
+- `docker-compose-down`: Stop services with docker-compose
+- `docker-compose-rebuild`: Rebuild and restart services
+
+#### Package Distribution
+- **MANIFEST.in**: Ensures proper file inclusion in source distributions
+  - Includes README.md, LICENSE, pyproject.toml
+  - Recursively includes Python files from src/ and examples/
+  - Excludes compiled bytecode files
+
+#### Public MCP Endpoint
+- Added documentation for hosted solver at `https://solver.chukai.io/mcp`
+- No installation required - use directly from Claude Desktop
+- Perfect for testing, demos, or production use
+
+#### Enhanced Installation Options
+- Highlighted `uvx` as recommended installation method
+- Added `uvx install` option for global installation
+- Organized installation options by use case
+
+### Changed
+
+#### Server Transport Handling
+- **Breaking**: Simplified command-line argument parsing in `src/chuk_mcp_solver/server.py`
+- **Removed**: `argparse` dependency
+- **Default**: STDIO mode (for Claude Desktop compatibility)
+- **HTTP Mode**: Pass `http` or `--http` argument
+- **Logging**: Improved logging suppression in STDIO mode to reduce noise
+- **Pattern**: Now matches chuk-mcp-celestial transport handling
+
+#### Documentation Updates
+- **README.md**:
+  - Updated test count from 151+ to 170 tests
+  - Added public MCP endpoint section
+  - Enhanced Quick Start with three options (Public, uvx, Development)
+  - Added Docker usage section
+  - Improved installation instructions with emojis and clear hierarchy
+- **Test Count**: Updated badges and documentation to reflect 170 passing tests
+
+### Test Results
+
+All 170 tests passing:
+- Fixed hanging cache tests (test_cache_stats)
+- Fixed failing performance test (test_partial_solution_on_timeout)
+- All existing functionality preserved
+- No breaking changes to core API
+
+### Migration Notes
+
+#### For Users
+- No action required - all changes are backward compatible
+- Consider using the public endpoint at `https://solver.chukai.io/mcp` for quick testing
+- For production use, consider Docker deployment for better isolation
+
+#### For Developers
+- If running the server programmatically, note the simplified transport handling:
+  - Default: STDIO mode (no arguments)
+  - HTTP mode: Pass `"http"` or `"--http"` as argument
+  - Old `--transport` flag is no longer supported
+
+#### For Docker Users
+- Use `make docker-build` and `make docker-run` for easy Docker operations
+- Default container runs in HTTP mode on port 8000
+- See DOCKER.md for comprehensive deployment guide
+
+### Security
+
+- Docker image runs as non-root user (`mcpuser`)
+- Minimal runtime dependencies reduce attack surface
+- Health checks ensure service availability
+- No secrets or credentials in Docker image
+
+### Performance
+
+- Multi-stage Docker build reduces image size
+- Cache now uses reentrant locks for better concurrency
+- Partial solution timeout handling improved for better user experience
+
+---
+
+## [0.1.0] - 2024-12-01
+
+Initial release with comprehensive constraint solving and optimization capabilities.
+
+See README.md for full feature list.

chuk_mcp_solver-0.1.2/Dockerfile

@@ -0,0 +1,81 @@
+# CHUK MCP Solver Dockerfile
+# ========================================
+# Multi-stage build for optimal image size
+# Based on chuk-mcp-server patterns
+
+# Build stage
+FROM python:3.11-slim as builder
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast dependency management
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:${PATH}"
+
+# Copy project configuration
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+# Install the package with all dependencies
+# Use --no-cache to reduce layer size
+RUN uv pip install --system --no-cache -e .
+
+# Runtime stage
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install minimal runtime dependencies
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy Python environment from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy application code
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/README.md ./
+COPY --from=builder /app/pyproject.toml ./
+
+# Create non-root user for security
+RUN useradd -m -u 1000 mcpuser && \
+    chown -R mcpuser:mcpuser /app
+
+# Switch to non-root user
+USER mcpuser
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONPATH=/app/src
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import sys; sys.path.insert(0, '/app/src'); import chuk_mcp_solver; print('OK')" || exit 1
+
+# Default command - run MCP server in HTTP mode for Docker
+CMD ["python", "-m", "chuk_mcp_solver.server", "http"]
+
+# Expose port for HTTP mode
+EXPOSE 8000
+
+# Labels for metadata
+LABEL maintainer="info@chuk.ai" \
+      description="CHUK MCP Solver - General-purpose constraint and optimization solver" \
+      version="0.1.1" \
+      org.opencontainers.image.source="https://github.com/chuk-ai/chuk-mcp-solver" \
+      org.opencontainers.image.title="CHUK MCP Solver" \
+      org.opencontainers.image.description="MCP server for constraint satisfaction and optimization using OR-Tools" \
+      org.opencontainers.image.authors="CHUK AI <info@chuk.ai>"

chuk_mcp_solver-0.1.2/LICENSE

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

chuk_mcp_solver-0.1.2/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src *.py
+recursive-include examples *.py *.sh *.json *.md
+exclude examples/*.pyc
+exclude **/__pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *~