redmine-mcp-server 0.4.2__tar.gz

redmine_mcp_server-0.4.2/.env.example

@@ -0,0 +1,33 @@
+# Redmine MCP Configuration
+# Copy this file to .env and update the values
+
+# Authentication Options:
+# Option 1: Username and Password (traditional)
+REDMINE_URL=https://your-redmine-server.com
+REDMINE_USERNAME=your_username
+REDMINE_PASSWORD=your_password
+
+
+# Option 2: API Key (alternative to username/password)
+# Uncomment and set this if you want to use API key authentication instead
+# REDMINE_API_KEY=your_api_key
+
+# Server configuration
+SERVER_HOST=0.0.0.0
+SERVER_PORT=8000
+
+# Public URL configuration for file serving
+# External hostname/IP for generated download URLs
+PUBLIC_HOST=localhost
+PUBLIC_PORT=8000
+
+# File Management (Optional)
+# Directory where downloaded attachments are stored
+ATTACHMENTS_DIR=./attachments
+
+# Automatic cleanup configuration
+AUTO_CLEANUP_ENABLED=true
+CLEANUP_INTERVAL_MINUTES=10
+
+# Default expiry time for downloaded attachments (in minutes)
+ATTACHMENT_EXPIRES_MINUTES=60

redmine_mcp_server-0.4.2/.github/workflows/pr-tests.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - develop
+
+  push:
+    branches:
+      - feature/*
+      - release/*
+      - hotfix/*
+      
+  workflow_dispatch:  # 👈 allows manual run from GitHub UI
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install uv
+        run: pip install uv
+      - name: Set up environment
+        run: |
+          uv venv
+          source .venv/bin/activate
+          uv pip install -e .[test,dev]
+      - name: Run code quality checks
+        run: |
+          source .venv/bin/activate
+          flake8 src/ --max-line-length=88
+          black --check src/ --line-length=88
+      - name: Run tests
+        run: |
+          source .venv/bin/activate
+          python tests/run_tests.py --all --verbose

redmine_mcp_server-0.4.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'  # Trigger on version tags like v0.4.1
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*

redmine_mcp_server-0.4.2/.gitignore

@@ -0,0 +1,23 @@
+# VsCode and IDE specific files
+.vscode/settings.json
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Test and coverage files
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv
+.env
+.env.docker
+CLAUDE.md
+.claude
+attachments
+plans

redmine_mcp_server-0.4.2/.python-version

@@ -0,0 +1 @@
+3.13

redmine_mcp_server-0.4.2/AGENTS.md

@@ -0,0 +1,73 @@
+# Repository Guidelines for Codex Agents
+
+This file provides instructions for any Codex agent interacting with this repository.
+
+## Setup
+- Requires **Python 3.13+** and the [`uv`](https://docs.astral.sh/uv/) package manager.
+- Create a virtual environment and install dependencies:
+  ```bash
+  uv venv
+  source .venv/bin/activate
+  uv pip install -e .
+  ```
+- Install development/test requirements with:
+  ```bash
+  uv pip install pytest pytest-asyncio pytest-cov pytest-mock
+  ```
+
+## Running the Server
+- Development mode:
+  ```bash
+  uv run fastapi dev src/redmine_mcp_server/main.py
+  ```
+- Production mode:
+  ```bash
+  uv run python src/redmine_mcp_server/main.py
+  ```
+
+## Testing
+Use the provided test runner located in `tests/run_tests.py`.
+
+- Run **all** tests:
+  ```bash
+  python tests/run_tests.py --all
+  ```
+- Run **unit** tests only:
+  ```bash
+  python tests/run_tests.py
+  ```
+- Run **integration** tests only:
+  ```bash
+  python tests/run_tests.py --integration
+  ```
+- Generate a coverage report:
+  ```bash
+  python tests/run_tests.py --coverage
+  ```
+
+Integration tests require a reachable Redmine instance configured via environment variables.
+
+## Docker Usage
+- Recommended workflow with `docker-compose`:
+  ```bash
+  cp .env.example .env.docker
+  # Edit .env.docker with your Redmine configuration
+  docker-compose up --build
+  ```
+- Or build and run directly with Docker:
+  ```bash
+  docker build -t redmine-mcp-server .
+  docker run -p 8000:8000 --env-file .env.docker redmine-mcp-server
+  ```
+
+## Environment Configuration
+Copy `.env.example` to `.env` and set:
+
+- `REDMINE_URL` – base URL of your Redmine server
+- `REDMINE_USERNAME` and `REDMINE_PASSWORD` **or** `REDMINE_API_KEY`
+- `SERVER_HOST` and `SERVER_PORT` to control server binding
+
+Do **not** commit `.env` or other secrets to version control.
+
+## Licensing
+This project uses the MIT License. See `LICENSE` for details.

redmine_mcp_server-0.4.2/CHANGELOG.md

@@ -0,0 +1,249 @@
+# 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).
+
+## [0.4.2] - 2025-09-23
+
+### Added
+- PyPI package publishing support as `redmine-mcp-server`
+- Console script entry point: `redmine-mcp-server` command
+- Comprehensive package metadata for PyPI distribution
+- GitHub Actions workflow for automated PyPI publishing
+
+### Changed
+- Updated package name from `mcp-redmine` to `redmine-mcp-server` for PyPI
+- Enhanced pyproject.toml with full package metadata and classifiers
+- Added main() function for console script execution
+
+### Improved
+- Better package discoverability with keywords and classifications
+- Professional package structure following PyPI best practices
+- Automated release workflow for seamless publishing
+
+## [0.4.1] - 2025-09-23
+
+### Fixed
+- GitHub Actions CI test failure in security validation tests
+- Updated test assertions to handle Redmine client initialization state properly
+- Security validation tests now pass consistently in CI environments
+
+### Improved
+- Enhanced GitHub Actions workflow with manual dispatch trigger
+- Added verbose test output for better CI debugging
+- Improved test reliability across different environments
+
+## [0.4.0] - 2025-09-22
+
+### Added
+- `get_redmine_attachment_download_url()` - Secure replacement for attachment downloads
+- Comprehensive security validation test suite
+- Server-controlled storage and expiry policies for enhanced security
+
+### Changed
+- Updated MCP library to v1.14.1
+- Integration tests now create their own test attachments for reliability
+- Attachment files always use UUID-based directory structure
+
+### Deprecated
+- `download_redmine_attachment()` - Use `get_redmine_attachment_download_url()` instead
+  - ⚠️ SECURITY: `save_dir` parameter vulnerable to path traversal (CWE-22, CVSS 7.5)
+  - `expires_hours` parameter exposes server policies to clients
+  - Will be removed in v0.5.0
+
+### Fixed
+- Path traversal vulnerability in attachment downloads eliminated
+- Integration test no longer skipped due to missing attachments
+
+### Security
+- **CRITICAL**: Fixed path traversal vulnerability in attachment downloads (CVSS 7.5)
+- Removed client control over server storage configuration
+- Enhanced logging for security events and deprecated function usage
+
+## [0.3.1] - 2025-09-21
+
+### Fixed
+- Integration test compatibility with new attachment download API format
+- Test validation now properly checks HTTP download URLs instead of file paths
+- Comprehensive validation of all attachment response fields (download_url, filename, content_type, size, expires_at, attachment_id)
+
+## [0.3.0] - 2025-09-21
+
+### Added
+- **Automatic file cleanup system** with configurable intervals and expiry times
+- `AUTO_CLEANUP_ENABLED` environment variable for enabling/disabling automatic cleanup (default: true)
+- `CLEANUP_INTERVAL_MINUTES` environment variable for cleanup frequency (default: 10 minutes)
+- `ATTACHMENT_EXPIRES_MINUTES` environment variable for default attachment expiry (default: 60 minutes)
+- Background cleanup task with lazy initialization via MCP tool calls
+- Cleanup status endpoint (`/cleanup/status`) for monitoring background task
+- `CleanupTaskManager` class for managing cleanup task lifecycle
+- Enhanced health check endpoint with cleanup task initialization
+- Comprehensive file management configuration documentation in README
+
+### Changed
+- **BREAKING**: `CLEANUP_INTERVAL_HOURS` replaced with `CLEANUP_INTERVAL_MINUTES` for finer control
+- Default attachment expiry configurable via environment variable instead of hardcoded 24 hours
+- Cleanup task now starts automatically when first MCP tool is called (lazy initialization)
+- Updated `.env.example` with new minute-based configuration options
+
+### Improved
+- More granular control over cleanup timing with minute-based intervals
+- Better resource management with automatic cleanup task lifecycle
+- Enhanced monitoring capabilities with cleanup status endpoint
+- Clearer documentation with practical configuration examples for development and production
+
+## [0.2.1] - 2025-09-20
+
+### Added
+- HTTP file serving endpoint (`/files/{file_id}`) for downloaded attachments
+- Secure UUID-based file URLs with automatic expiry (24 hours default)
+- New `file_manager.py` module for attachment storage and cleanup management
+- `cleanup_attachment_files` MCP tool for expired file management
+- PUBLIC_HOST/PUBLIC_PORT environment variables for external URL generation
+- PEP 8 compliance standards and development tools (flake8, black)
+- Storage statistics tracking for attachment management
+
+### Changed
+- **BREAKING**: `download_redmine_attachment` now returns `download_url` instead of `file_path`
+- Attachment downloads now provide HTTP URLs for external access
+- Docker URL generation fixed (uses localhost instead of 0.0.0.0)
+- Dependencies optimized (httpx moved to dev/test dependencies)
+
+### Fixed
+- Docker container URL accessibility issues for downloaded attachments
+- URL generation for external clients in containerized environments
+
+### Improved
+- Code quality with full PEP 8 compliance across all Python modules
+- Test coverage for new HTTP URL return format
+- Documentation updated with file serving details
+
+## [0.2.0] - 2025-09-20
+
+### Changed
+- **BREAKING**: Migrated from FastAPI/SSE to FastMCP streamable HTTP transport
+- **BREAKING**: MCP endpoint changed from `/sse` to `/mcp`
+- Updated server architecture to use FastMCP's native HTTP capabilities
+- Simplified initialization and removed FastAPI dependency layer
+
+### Added
+- Native FastMCP streamable HTTP transport support
+- Claude Code CLI setup command documentation
+- Stateless HTTP mode for better scalability
+- Smart issue summarization tool with comprehensive project analytics
+
+### Improved
+- Better MCP protocol compliance with native FastMCP implementation
+- Reduced complexity by removing custom FastAPI/SSE layer
+- Updated all documentation to reflect new transport method
+- Enhanced health check endpoint with service identification
+
+### Migration Notes
+- Existing MCP clients need to update endpoint from `/sse` to `/mcp`
+- Claude Code users can now use: `claude mcp add --transport http redmine http://127.0.0.1:8000/mcp`
+- Server initialization simplified with `mcp.run(transport="streamable-http")`
+
+## [0.1.6] - 2025-06-19
+### Added
+- New MCP tool `search_redmine_issues` for querying issues by text.
+
+## [0.1.5] - 2025-06-18
+### Added
+- `get_redmine_issue` can now return attachment metadata via a new
+  `include_attachments` parameter.
+- New MCP tool `download_redmine_attachment` for downloading attachments.
+
+## [0.1.4] - 2025-05-28
+
+### Removed
+- Deprecated `get_redmine_issue_comments` tool. Use `get_redmine_issue` with
+  `include_journals=True` to retrieve comments.
+
+### Changed
+- `get_redmine_issue` now includes issue journals by default. A new
+  `include_journals` parameter allows opting out of comment retrieval.
+
+## [0.1.3] - 2025-05-27
+
+### Added
+- New MCP tool `list_my_redmine_issues` for retrieving issues assigned to the current user
+- New MCP tool `get_redmine_issue_comments` for retrieving issue comments
+## [0.1.2] - 2025-05-26
+
+### Changed
+- Roadmap moved to its own document with updated plans
+- Improved README badges and links
+
+### Added
+- New MCP tools `create_redmine_issue` and `update_redmine_issue` for managing issues
+- Documentation updates describing the new tools
+- Integration tests for issue creation and update
+- Integration test for Redmine issue management
+
+## [0.1.1] - 2025-05-25
+
+### Changed
+- Updated project documentation with correct repository URLs
+- Updated LICENSE with proper copyright (2025 Kevin Tan and contributors)
+- Enhanced VS Code integration documentation
+- Improved .gitignore to include test coverage files
+
+
+## [0.1.0] - 2025-05-25
+
+### Added
+- Initial release of Redmine MCP Server
+- MIT License for open source distribution
+- Core MCP server implementation with FastAPI and SSE transport
+- Two primary MCP tools:
+  - `get_redmine_issue(issue_id)` - Retrieve detailed issue information
+  - `list_redmine_projects()` - List all accessible Redmine projects
+- Comprehensive authentication support (username/password and API key)
+- Modern Python project structure with uv package manager
+- Complete testing framework with 20 tests:
+  - 10 unit tests for core functionality
+  - 7 integration tests for end-to-end workflows
+  - 3 connection validation tests
+- Docker containerization support:
+  - Multi-stage Dockerfile with security hardening
+  - Docker Compose configuration with health checks
+  - Automated deployment script with comprehensive management
+  - Production-ready container setup with non-root user
+- Comprehensive documentation:
+  - Detailed README.md with installation and usage instructions
+  - Complete API documentation with examples
+  - Docker deployment guide
+  - Testing framework documentation
+- Git Flow workflow implementation with standard branching strategy
+- Environment configuration templates and examples
+- Advanced test runner with coverage reporting and flexible execution
+
+### Technical Features
+- **Architecture**: FastAPI application with Server-Sent Events (SSE) transport
+- **Security**: Authentication with Redmine instances, non-root Docker containers
+- **Testing**: pytest framework with mocks, fixtures, and comprehensive coverage
+- **Deployment**: Docker support with automated scripts and health monitoring
+- **Documentation**: Complete module docstrings and user guides
+- **Development**: Modern Python toolchain with uv, Git Flow, and automated testing
+
+### Dependencies
+- Python 3.13+
+- FastAPI with standard extensions
+- MCP CLI tools
+- python-redmine for Redmine API integration
+- Docker for containerization
+- pytest ecosystem for testing
+
+### Compatibility
+- Compatible with Redmine 3.x and 4.x instances
+- Supports both username/password and API key authentication
+- Works with Docker and docker-compose
+- Tested on macOS and Linux environments
+
+[0.1.1]: https://github.com/jztan/redmine-mcp-server/releases/tag/v0.1.1
+[0.1.0]: https://github.com/jztan/redmine-mcp-server/releases/tag/v0.1.0
+[0.1.2]: https://github.com/jztan/redmine-mcp-server/releases/tag/v0.1.2
+

redmine_mcp_server-0.4.2/Dockerfile

@@ -0,0 +1,68 @@
+# Multi-stage Docker build for the Redmine MCP Server
+FROM python:3.13-slim AS builder
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_CACHE_DIR=/opt/uv-cache
+
+# Install uv package manager
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Create and set working directory
+WORKDIR /app
+
+# Copy dependency files and source code for installation
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+COPY README.md ./
+
+# Install dependencies and the project in a virtual environment
+RUN uv venv /opt/venv && \
+    uv pip install . --python=/opt/venv/bin/python
+
+# Production stage
+FROM python:3.13-slim AS runtime
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH="/opt/venv/bin:$PATH"
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN groupadd --gid 1000 appuser && \
+    useradd --uid 1000 --gid appuser --shell /bin/bash --create-home appuser
+
+# Copy virtual environment from builder stage
+COPY --from=builder --chown=appuser:appuser /opt/venv /opt/venv
+
+# Set working directory
+WORKDIR /app
+
+# Copy application code
+COPY --chown=appuser:appuser src/ ./src/
+COPY --chown=appuser:appuser README.md ./
+
+# Create directories for logs and data
+RUN mkdir -p /app/logs /app/data && \
+    chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Expose port
+EXPOSE 8000
+
+# Default command
+CMD ["python", "-m", "uvicorn", "src.redmine_mcp_server.main:app", "--host", "0.0.0.0", "--port", "8000"]

redmine_mcp_server-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kevin Tan and contributors
+
+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.