chore: finalize v3.0.0 public release prep

.github/workflows/ci.yml

@@ -8,29 +8,28 @@ on:
 
 jobs:
   tests:
-    name: required-test-check
+    name: tests (py${{ matrix.python-version }})
     if: ${{ github.event_name == 'pull_request' || !contains(github.event.head_commit.message, '[skip ci]') }}
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
-          cache: "pip"
+          python-version: ${{ matrix.python-version }}
 
       - name: Install Poetry
         run: python -m pip install --upgrade pip poetry
 
       - name: Install dependencies
         run: poetry install --with dev
 
-      - name: Run required test suite
-        run: >
-          poetry run python -m pytest
-          tests/test_session_locking.py
-          tests/test_timeout_cap.py
-          tests/test_version_bump.py
+      - name: Run test suite
+        run: poetry run pytest

.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release
+
+# Triggered by pushing a semver tag, e.g. `git tag v3.0.1 && git push origin v3.0.1`.
+# Replaces the old auto-bump-on-every-push workflow with a deliberate,
+# tag-driven build + publish flow.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        run: python -m pip install --upgrade pip poetry
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION="$(poetry version --short)"
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          echo "pyproject version: $PKG_VERSION | tag: $TAG_VERSION"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag '$TAG_VERSION' does not match pyproject.toml version '$PKG_VERSION'."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: poetry build
+
+      - name: Check metadata
+        run: |
+          python -m pip install twine
+          twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Requires a PyPI "Trusted Publisher" configured for this repo + workflow +
+    # the `pypi` environment (no API token stored as a secret). See docs/RELEASING.md.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/metasploit-mcp
+    permissions:
+      id-token: write  # OIDC token for PyPI Trusted Publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # create the release and upload assets
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

CONTRIBUTING.md

@@ -36,7 +36,7 @@ This project adheres to a code of conduct that we expect all contributors to fol
 
 3. **Verify Setup**
    ```bash
-   poetry run python run_all_tests.py
+   poetry run pytest
    ```
 
 ## How to Contribute
@@ -89,7 +89,7 @@ Before creating an issue, please:
 3. **Test Your Changes**
    ```bash
    # Run all tests
-   poetry run python run_all_tests.py
+   poetry run pytest
 
    # Run specific tests
    poetry run pytest tests/test_your_feature.py -v

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 GH05TCREW and the MetasploitMCP contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

Makefile

@@ -51,19 +51,19 @@ dev-setup: dev-install ## Setup: Complete development environment setup
 # Development targets
 run: ## Development: Run the MCP server in development mode
 	@echo "$(BLUE)Starting MetasploitMCP server...$(RESET)"
-	poetry run python MetasploitMCP.py --transport http --host 127.0.0.1 --port 8085
+	poetry run metasploit-mcp --transport http --host 127.0.0.1 --port 8085
 
 run-debug: ## Development: Run server with debug logging
 	@echo "$(BLUE)Starting MetasploitMCP server in debug mode...$(RESET)"
-	LOG_LEVEL=DEBUG poetry run python MetasploitMCP.py --transport http --host 127.0.0.1 --port 8085
+	LOG_LEVEL=DEBUG poetry run metasploit-mcp --transport http --host 127.0.0.1 --port 8085
 
 shell: ## Development: Open Poetry shell
 	poetry shell
 
 # Testing targets
-test: ## Testing: Run all tests using custom test runner
+test: ## Testing: Run all tests
 	@echo "$(BLUE)Running all tests...$(RESET)"
-	poetry run python run_all_tests.py
+	poetry run pytest
 
 test-unit: ## Testing: Run unit tests only
 	@echo "$(BLUE)Running unit tests...$(RESET)"
@@ -75,7 +75,7 @@ test-integration: ## Testing: Run integration tests only
 
 test-coverage: ## Testing: Run tests with coverage report
 	@echo "$(BLUE)Running tests with coverage...$(RESET)"
-	poetry run pytest tests/ --cov=. --cov-report=html --cov-report=term-missing
+	poetry run pytest --cov=metasploit_mcp --cov-report=html --cov-report=term-missing
 	@echo "$(GREEN)Coverage report: file://$(PWD)/htmlcov/index.html$(RESET)"
 
 test-watch: ## Testing: Run tests in watch mode (requires pytest-watch)
@@ -101,7 +101,7 @@ test-metasploitable3: ## Testing: Run integration tests against Metasploitable 3
 		echo "Usage: make test-metasploitable3 TARGET=10.0.2.15 LHOST=10.0.2.4 [LPORT=4444]"; \
 		exit 1; \
 	fi
-	poetry run python metasploitable3_test_harness.py \
+	poetry run python tests/harness.py \
 		--target $(TARGET) \
 		--lhost $(LHOST) \
 		--lport $(if $(LPORT),$(LPORT),4444)
@@ -117,26 +117,26 @@ test-metasploitable3-quick: ## Testing: Quick test against Metasploitable 3 (req
 
 list-metasploitable3-tests: ## Testing: List available Metasploitable 3 tests
 	@echo "$(BLUE)Available Metasploitable 3 exploit tests:$(RESET)"
-	poetry run python metasploitable3_test_harness.py --list-tests
+	poetry run python tests/harness.py --list-tests
 
 # Quality targets
 lint: ## Quality: Run all linting checks
 	@echo "$(BLUE)Running flake8...$(RESET)"
-	poetry run flake8 MetasploitMCP.py tests/
+	poetry run flake8 src tests
 	@echo "$(GREEN)✓ Linting passed!$(RESET)"
 
 format: ## Quality: Format code with black
 	@echo "$(BLUE)Formatting code with black...$(RESET)"
-	poetry run black MetasploitMCP.py tests/
+	poetry run black src tests
 	@echo "$(GREEN)✓ Code formatted!$(RESET)"
 
 format-check: ## Quality: Check if code is properly formatted
 	@echo "$(BLUE)Checking code formatting...$(RESET)"
-	poetry run black --check MetasploitMCP.py tests/
+	poetry run black --check src tests
 
 type-check: ## Quality: Run type checking with mypy
 	@echo "$(BLUE)Running type checks...$(RESET)"
-	poetry run mypy MetasploitMCP.py
+	poetry run mypy src
 	@echo "$(GREEN)✓ Type checking passed!$(RESET)"
 
 pre-commit: ## Quality: Run pre-commit hooks on all files

NOTICE

@@ -0,0 +1,26 @@
+MetasploitMCP
+Copyright 2025 GH05TCREW and the MetasploitMCP contributors
+
+This product includes software developed as part of the MetasploitMCP project.
+
+------------------------------------------------------------------------------
+Upstream attribution
+------------------------------------------------------------------------------
+
+This project is a fork of MetasploitMCP, originally created by GH05TCREW:
+
+    https://github.com/GH05TCREW/MetasploitMCP
+
+The original implementation (core Metasploit RPC integration, exploit/payload/
+session/console management, and background job handling) was authored by
+GH05TCREW <harmasic@gmail.com> and is licensed under the Apache License, 2.0.
+This fork retains that license and extends the project; see README.md
+("Relationship to upstream") and CHANGELOG.md for a summary of the changes.
+
+------------------------------------------------------------------------------
+Third-party software
+------------------------------------------------------------------------------
+
+This software integrates with, but does not redistribute, the Metasploit
+Framework (https://www.metasploit.com/) via its RPC interface. The Metasploit
+Framework is a separate work distributed under its own license.

README.md

@@ -2,11 +2,15 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![Poetry](https://img.shields.io/badge/dependency%20management-poetry-blue.svg)](https://python-poetry.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 A modern, secure Model Context Protocol (MCP) server that provides AI assistants with controlled access to Metasploit Framework functionality.
 
+> **Fork notice:** This project is a fork of [GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP),
+> the original Metasploit MCP server created by GH05TCREW. It is distributed under the same Apache License 2.0.
+> See [Relationship to upstream](#relationship-to-upstream) for what this fork changes and improves.
+
 ## Features
 
 ### Core Capabilities
@@ -309,6 +313,7 @@ For detailed documentation, see:
 - **[Integration Testing](docs/METASPLOITABLE3_TESTING.md)**: Testing with Metasploitable 3
 - **[Quick Start Testing](docs/QUICK_START_TESTING.md)**: 5-minute testing setup
 - **[Poetry Migration](docs/POETRY_MIGRATION.md)**: Migration from requirements.txt
+- **[Releasing](docs/RELEASING.md)**: How maintainers cut a release
 - **[Changelog](CHANGELOG.md)**: Version history and breaking changes
 - **[Contributing](CONTRIBUTING.md)**: How to contribute to the project
 
@@ -348,12 +353,43 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guid
 5. Run quality checks: `make full-check`
 6. Submit a pull request
 
+## Relationship to upstream
+
+This project is a fork of **[GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP)**,
+the original Metasploit MCP server created by **GH05TCREW** (`harmasic@gmail.com`). Full credit for the
+original design and implementation goes to the upstream author. This fork retains the upstream
+**Apache License 2.0** (see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE)).
+
+**Upstream base (GH05TCREW):** core Metasploit RPC integration, exploit / payload / session / console
+management, and background job handling — originally a single-file server with a `requirements.txt`
+install and SSE transport.
+
+**What this fork changes and improves:**
+
+- **Packaging & layout** — Poetry-based packaging, a `src/metasploit_mcp/` layout, and a
+  `metasploit-mcp` CLI entry point (replacing the single-file `requirements.txt` setup).
+- **Transport** — FastMCP HTTP (streamable) transport, replacing SSE.
+- **Dynamic option detection** — module/payload options are queried live from Metasploit instead of
+  being hardcoded, with detection of confused module/payload options.
+- **Concurrency safety** — per-session locking to prevent concurrent Meterpreter/shell access, plus a
+  per-agent Metasploit instance manager for isolation.
+- **Reliability** — async event-loop monitoring (blocking/backlog detection), MCP keep-alive to
+  prevent client timeouts, an RPC timeout cap with client cleanup and `auth.logout`, session-ID
+  normalization with fallback lookups, and force-option validation against module capabilities.
+- **Quality** — a comprehensive test suite, a Metasploitable 3 integration harness, and dependency
+  security updates.
+
+See [`CHANGELOG.md`](CHANGELOG.md) for the detailed version history.
+
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the **Apache License 2.0** — see the [`LICENSE`](LICENSE) file for the
+full text and the [`NOTICE`](NOTICE) file for attribution. As a fork, it preserves the license of the
+upstream [GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP) project.
 
 ## Acknowledgments
 
+- **[GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP)**: The original project this fork is based on
 - **Metasploit Framework**: The powerful penetration testing platform
 - **Model Context Protocol**: The standardized AI-tool communication protocol
 - **FastMCP**: Modern MCP server implementation framework