pwndoc-mcp-server 1.0.8__py3-none-any.whl

pwndoc_mcp_server/version.py

@@ -0,0 +1,26 @@
+"""
+Version helpers for PwnDoc MCP Server.
+
+Centralizes version lookup so the CLI and server report the same value.
+"""
+
+from importlib import metadata
+
+PACKAGE_NAME = "pwndoc-mcp-server"
+_FALLBACK_VERSION = "1.0.8"
+
+
+def get_version() -> str:
+    """
+    Return the installed package version, falling back to a bundled default.
+
+    This ensures local source checkouts (or editable installs) still report a
+    sensible version while published wheels use the package metadata.
+    """
+    try:
+        return metadata.version(PACKAGE_NAME)
+    except metadata.PackageNotFoundError:
+        return _FALLBACK_VERSION
+
+
+__all__ = ["get_version", "PACKAGE_NAME"]

pwndoc_mcp_server-1.0.8.dist-info/METADATA

@@ -0,0 +1,552 @@
+Metadata-Version: 2.4
+Name: pwndoc-mcp-server
+Version: 1.0.8
+Summary: Model Context Protocol server for PwnDoc penetration testing documentation
+Project-URL: Homepage, https://github.com/walidfaour/pwndoc-mcp-server
+Project-URL: Documentation, https://github.com/walidfaour/pwndoc-mcp-server#readme
+Project-URL: Repository, https://github.com/walidfaour/pwndoc-mcp-server
+Project-URL: Issues, https://github.com/walidfaour/pwndoc-mcp-server/issues
+Author-email: Walid Faour <security@walidfaour.com>
+License-Expression: MIT
+Keywords: documentation,mcp,penetration-testing,pentest,pwndoc,security,vulnerability
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: all
+Requires-Dist: aiohttp>=3.9.0; extra == 'all'
+Requires-Dist: rich>=13.0.0; extra == 'all'
+Requires-Dist: typer>=0.9.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Requires-Dist: typer>=0.9.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.9.0; extra == 'dev'
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: rich>=13.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: typer>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Provides-Extra: sse
+Requires-Dist: aiohttp>=3.9.0; extra == 'sse'
+Description-Content-Type: text/markdown
+
+# PwnDoc MCP Server
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/walidfaour/pwndoc-mcp-server/main/assets/banner.svg" alt="PwnDoc MCP Server Banner" width="800">
+</p>
+
+<p align="center">
+  <strong>Model Context Protocol server for PwnDoc pentest documentation</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/walidfaour/pwndoc-mcp-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/walidfaour/pwndoc-mcp-server/ci.yml?style=flat-square" alt="Build Status"></a>
+  <a href="https://pypi.org/project/pwndoc-mcp-server/"><img src="https://img.shields.io/pypi/v/pwndoc-mcp-server?style=flat-square" alt="PyPI Version"></a>
+  <a href="https://pypi.org/project/pwndoc-mcp-server/"><img src="https://img.shields.io/pypi/pyversions/pwndoc-mcp-server?style=flat-square" alt="Python Versions"></a>
+  <a href="https://github.com/walidfaour/pwndoc-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/github/license/walidfaour/pwndoc-mcp-server?style=flat-square" alt="License"></a>
+  <a href="https://walidfaour.github.io/pwndoc-mcp-server"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue?style=flat-square" alt="Documentation"></a>
+</p>
+
+<p align="center">
+  <a href="#-features">Features</a> •
+  <a href="#-installation">Installation</a> •
+  <a href="#%EF%B8%8F-configuration">Configuration</a> •
+  <a href="#-usage">Usage</a> •
+  <a href="#-documentation">Documentation</a>
+</p>
+
+---
+
+## 🎯 Overview
+
+PwnDoc MCP Server enables AI assistants to interact with your PwnDoc penetration testing documentation system through the [Model Context Protocol](https://modelcontextprotocol.io/). Query audits, manage findings, generate reports, and more—all through natural language.
+
+### Two Implementations
+
+| Version | Best For | Size | Install |
+|---------|----------|------|---------|
+| [**Python**](#python-installation) | Most users, extensibility | ~50MB | `pip install pwndoc-mcp-server` |
+| [**Native C++**](#native-installation) | Portability, minimal deps | ~5MB | [Download binary](https://github.com/walidfaour/pwndoc-mcp-server/releases) |
+
+## ✨ Features
+
+- 🔌 **90 MCP Tools** - Complete coverage of PwnDoc API (all endpoints)
+- 🔐 **Secure Authentication** - JWT tokens with auto-refresh
+- ⚡ **Rate Limiting** - Built-in sliding window rate limiter
+- 🔄 **Automatic Retries** - Exponential backoff for failed requests
+- 📊 **Comprehensive Logging** - Debug, file, and JSON logging
+- 🌍 **Cross-Platform** - Linux, macOS, Windows support
+- 🐳 **Docker Ready** - Pre-built container images
+- 📦 **Multiple Installation Methods** - pip, apt, yum, binaries
+- 🚀 **Native Binary** - Optional C++ implementation for portability
+- 🎯 **Type Safety** - Full mypy type checking (zero errors)
+- ✅ **Well Tested** - 111 tests, 100% quality checks passing
+
+## 📥 Installation
+
+### Python Installation
+
+```bash
+# Basic installation
+pip install pwndoc-mcp-server
+
+# With CLI enhancements
+pip install pwndoc-mcp-server[cli]
+
+# With all features
+pip install pwndoc-mcp-server[all]
+```
+
+**Kali Linux Users:** If you encounter errors during installation, use a virtual environment:
+
+```bash
+sudo apt update
+sudo apt install -y python3-venv
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
+pip install pwndoc-mcp-server
+```
+
+### Native Installation
+
+Download pre-built binaries from [Releases](https://github.com/walidfaour/pwndoc-mcp-server/releases):
+
+| Platform | Binary |
+|----------|--------|
+| Linux x64 | `pwndoc-mcp-linux-x64` |
+| macOS x64 | `pwndoc-mcp-macos-x64` |
+| macOS ARM | `pwndoc-mcp-macos-arm64` |
+| Windows | `pwndoc-mcp-windows-x64.exe` |
+
+```bash
+# Linux/macOS
+curl -LO https://github.com/walidfaour/pwndoc-mcp-server/releases/latest/download/pwndoc-mcp-linux-x64
+chmod +x pwndoc-mcp-linux-x64
+./pwndoc-mcp-linux-x64
+```
+
+### Installation Matrix
+
+| Platform | Method | Command |
+|----------|--------|---------|
+| **Any** | pip | `pip install pwndoc-mcp-server` |
+| **Any** | pipx | `pipx install pwndoc-mcp-server` |
+| **Linux (Debian/Ubuntu)** | apt | `sudo apt install pwndoc-mcp-server` |
+| **Linux (RHEL/CentOS)** | yum | `sudo yum install pwndoc-mcp-server` |
+| **macOS** | Homebrew | `brew install pwndoc-mcp-server` |
+| **Windows** | Scoop | `scoop install pwndoc-mcp-server` |
+| **Any** | Docker | `docker pull ghcr.io/walidfaour/pwndoc-mcp-server` |
+| **Any** | Binary | [Download from Releases](https://github.com/walidfaour/pwndoc-mcp-server/releases) |
+
+### From Source
+
+```bash
+# Python
+git clone https://github.com/walidfaour/pwndoc-mcp-server.git
+cd pwndoc-mcp-server/python
+pip install -e .[dev]
+
+# Native C++
+cd ../native
+mkdir build && cd build
+cmake .. && make
+```
+
+## ⚙️ Configuration
+
+### Quick Start (Interactive Setup)
+
+```bash
+pwndoc-mcp config init
+```
+
+The interactive wizard will guide you through configuration and support both authentication methods.
+
+### Authentication Methods
+
+You can authenticate using **environment variables**, **config file**, or **CLI arguments**.
+
+**Option 1: Username/Password (Recommended)**
+- ✅ Automatically handles token generation and refresh
+- ✅ No manual token management required
+- ✅ **Preferred** when both credentials and token are provided
+
+```bash
+# Environment variables
+export PWNDOC_URL="https://pwndoc.example.com"
+export PWNDOC_USERNAME="your-username"
+export PWNDOC_PASSWORD="your-password"
+
+# Or CLI arguments
+pwndoc-mcp serve --url https://pwndoc.example.com --username user --password pass
+pwndoc-mcp test --url https://pwndoc.example.com -u user -p pass
+```
+
+**Option 2: Pre-authenticated Token**
+- Use if you have a JWT token
+- ⚠️ Requires manual renewal when expired
+- Only used if username/password not provided
+
+```bash
+# Environment variables
+export PWNDOC_URL="https://pwndoc.example.com"
+export PWNDOC_TOKEN="your-jwt-token"
+
+# Or CLI arguments
+pwndoc-mcp serve --url https://pwndoc.example.com --token your-jwt-token
+```
+
+**Authentication Priority:**
+When multiple methods are configured, the system uses this priority:
+1. **Username/Password** (if both provided) → automatic token refresh ✅
+2. **Token** (if username/password not provided) → manual renewal required ⚠️
+
+This means if you set all three (URL + username/password + token), it will use username/password and ignore the token.
+
+### Configuration File
+
+Create `~/.pwndoc-mcp/config.yaml`:
+
+```yaml
+url: https://pwndoc.example.com
+username: your-username
+password: your-password
+verify_ssl: true
+timeout: 30
+```
+
+## 🖥️ Claude Desktop Integration
+
+### Automatic Installation (Recommended)
+
+```bash
+# Configure your PwnDoc credentials
+pwndoc-mcp config init
+
+# Automatically install for Claude Desktop
+pwndoc-mcp claude-install
+
+# Check installation status
+pwndoc-mcp claude-status
+```
+
+This will automatically update the appropriate MCP configuration file:
+- **Linux**: `~/.config/claude/mcp_servers.json`
+- **macOS**: `~/Library/Application Support/Claude/mcp_servers.json`
+- **Windows**: `%APPDATA%\Claude\mcp_servers.json`
+
+### Manual Installation
+
+Alternatively, manually add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+### Using Python (pip)
+
+```json
+{
+  "mcpServers": {
+    "pwndoc": {
+      "command": "pwndoc-mcp",
+      "args": ["serve"],
+      "env": {
+        "PWNDOC_URL": "https://pwndoc.example.com",
+        "PWNDOC_USERNAME": "your-username",
+        "PWNDOC_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Using Native Binary
+
+```json
+{
+  "mcpServers": {
+    "pwndoc": {
+      "command": "/path/to/pwndoc-mcp-linux-x64",
+      "env": {
+        "PWNDOC_URL": "https://pwndoc.example.com",
+        "PWNDOC_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Using Docker
+
+```json
+{
+  "mcpServers": {
+    "pwndoc": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm",
+        "-e", "PWNDOC_URL=https://pwndoc.example.com",
+        "-e", "PWNDOC_TOKEN=your-token",
+        "ghcr.io/walidfaour/pwndoc-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+## 🚀 Usage
+
+### CLI Commands
+
+```bash
+# Test connection
+pwndoc-mcp test
+
+# List available tools
+pwndoc-mcp tools
+
+# Start MCP server
+pwndoc-mcp serve
+
+# Interactive config setup
+pwndoc-mcp config init
+
+# Claude Desktop integration
+pwndoc-mcp claude-install   # Install MCP config for Claude
+pwndoc-mcp claude-status    # Check installation status
+pwndoc-mcp claude-uninstall # Remove MCP config
+```
+
+### Using with Other MCP Clients
+
+The server works with **any MCP-compatible client**, not just Claude Desktop:
+
+**stdio transport (default)** - For client integrations:
+```bash
+pwndoc-mcp serve  # Communicates via stdin/stdout
+```
+
+**SSE transport** - For web-based clients:
+```bash
+pwndoc-mcp serve --transport sse --host 0.0.0.0 --port 8080
+# Access at: http://localhost:8080/mcp
+```
+
+**Client configuration examples:**
+
+<details>
+<summary><b>Cline (VS Code)</b></summary>
+
+Add to Cline MCP settings:
+```json
+{
+  "mcpServers": {
+    "pwndoc": {
+      "command": "pwndoc-mcp",
+      "args": ["serve"],
+      "env": {
+        "PWNDOC_URL": "https://pwndoc.example.com",
+        "PWNDOC_USERNAME": "your-username",
+        "PWNDOC_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Continue.dev</b></summary>
+
+Add to Continue config:
+```json
+{
+  "mcpServers": {
+    "pwndoc": {
+      "command": "pwndoc-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Custom MCP Client</b></summary>
+
+Connect to stdio transport:
+```python
+import subprocess
+process = subprocess.Popen(
+    ["pwndoc-mcp", "serve"],
+    stdin=subprocess.PIPE,
+    stdout=subprocess.PIPE,
+    env={"PWNDOC_URL": "...", "PWNDOC_USERNAME": "...", "PWNDOC_PASSWORD": "..."}
+)
+```
+
+Or use SSE transport:
+```python
+import requests
+response = requests.post(
+    "http://localhost:8080/mcp",
+    json={"method": "tools/list"}
+)
+```
+</details>
+
+### Docker
+
+```bash
+docker run -it --rm \
+  -e PWNDOC_URL="https://pwndoc.example.com" \
+  -e PWNDOC_TOKEN="your-token" \
+  ghcr.io/walidfaour/pwndoc-mcp-server:latest
+```
+
+## 🔧 Available Tools (90)
+
+**Complete coverage of PwnDoc API** - All 92 endpoints exposed as MCP tools (minus 2 internal auth endpoints)
+
+### Audits (13 tools)
+- `list_audits` `get_audit` `create_audit` `update_audit_general` `delete_audit`
+- `get_audit_general` `get_audit_network` `update_audit_network`
+- `get_audit_sections` `update_audit_sections`
+- `toggle_audit_approval` `update_review_status` `generate_audit_report`
+
+### Findings (9 tools)
+- `get_audit_findings` `get_finding` `create_finding` `update_finding` `delete_finding`
+- `sort_findings` `move_finding` `search_findings`
+- `get_all_findings_with_context` (comprehensive: extracts CWE, OWASP, strips HTML, full team info)
+
+### Vulnerability Templates (9 tools)
+- `list_vulnerabilities` `get_vulnerabilities_by_locale` `create_vulnerability` `update_vulnerability` `delete_vulnerability`
+- `bulk_delete_vulnerabilities` `export_vulnerabilities` `create_vulnerability_from_finding`
+- `get_vulnerability_updates` `merge_vulnerability`
+
+### Clients & Companies (8 tools)
+- `list_clients` `create_client` `update_client` `delete_client`
+- `list_companies` `create_company` `update_company` `delete_company`
+
+### Users & Authentication (11 tools)
+- `list_users` `get_user` `get_current_user` `create_user` `update_user` `update_current_user`
+- `list_reviewers`
+- `get_totp_status` `setup_totp` `disable_totp` (2FA/TOTP support)
+
+### Data Types & Configuration (22 tools)
+**Languages** (4): `list_languages` `create_language` `update_language` `delete_language`
+
+**Audit Types** (4): `list_audit_types` `create_audit_type` `update_audit_type` `delete_audit_type`
+
+**Vulnerability Types** (4): `list_vulnerability_types` `create_vulnerability_type` `update_vulnerability_type` `delete_vulnerability_type`
+
+**Vulnerability Categories** (4): `list_vulnerability_categories` `create_vulnerability_category` `update_vulnerability_category` `delete_vulnerability_category`
+
+**Sections** (4): `list_sections` `create_section` `update_section` `delete_section`
+
+**Custom Fields** (4): `list_custom_fields` `create_custom_field` `update_custom_field` `delete_custom_field`
+
+### Settings & Templates (10 tools)
+- `get_settings` `get_public_settings` `update_settings` `export_settings` `import_settings`
+- `list_templates` `create_template` `update_template` `delete_template` `download_template`
+
+### Images (4 tools)
+- `get_image` `download_image` `upload_image` `delete_image`
+
+### Statistics & Metadata (4 tools)
+- `get_statistics` `list_roles`
+
+> 💡 **Tip:** Use `pwndoc-mcp tools` to list all available tools with descriptions
+
+[Full tool documentation →](https://walidfaour.github.io/pwndoc-mcp-server/tools)
+
+## 📖 Documentation
+
+- **GitHub Pages**: [walidfaour.github.io/pwndoc-mcp-server](https://walidfaour.github.io/pwndoc-mcp-server)
+- **Repository docs**: [GitHub Documentation](https://github.com/walidfaour/pwndoc-mcp-server/tree/main/docs)
+
+Quick links:
+- [Getting Started Guide](https://walidfaour.github.io/pwndoc-mcp-server/getting-started/quick-start)
+- [Configuration Reference](https://walidfaour.github.io/pwndoc-mcp-server/getting-started/configuration)
+- [Tool Reference](https://walidfaour.github.io/pwndoc-mcp-server/tools/overview)
+- [Docker Deployment](https://walidfaour.github.io/pwndoc-mcp-server/user-guide/docker)
+
+## 📁 Project Structure
+
+```
+pwndoc-mcp-server/
+├── python/                   # Python implementation
+│   ├── src/pwndoc_mcp_server/
+│   ├── tests/
+│   ├── pyproject.toml
+│   └── Dockerfile
+├── native/                   # C++ implementation
+│   ├── src/
+│   ├── include/
+│   └── CMakeLists.txt
+├── docs/                     # Documentation
+├── assets/                   # Branding assets
+├── debian/                   # Debian packaging
+├── rpm/                      # RPM packaging
+├── packaging/                # Homebrew/Scoop
+└── .github/                  # CI/CD workflows
+```
+
+## 🔒 Security
+
+See [SECURITY.md](https://github.com/walidfaour/pwndoc-mcp-server/blob/main/SECURITY.md) for reporting vulnerabilities.
+
+**Important:** This tool handles sensitive penetration testing data. Use only on authorized systems.
+
+## 🤝 Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](https://github.com/walidfaour/pwndoc-mcp-server/blob/main/CONTRIBUTING.md) for guidelines.
+
+```bash
+# First, configure git
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+
+# Clone and setup
+git clone https://github.com/walidfaour/pwndoc-mcp-server.git
+cd pwndoc-mcp-server/python
+pip install -e .[dev]
+pytest
+```
+
+## 📜 License
+
+MIT License - see [LICENSE](https://github.com/walidfaour/pwndoc-mcp-server/blob/main/LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- [PwnDoc](https://github.com/pwndoc/pwndoc) - The penetration testing documentation platform
+- **Walid Faour** - security@walidfaour.com
+
+---
+
+<p align="center">
+  Made with ❤️ by Walid Faour
+</p>

pwndoc_mcp_server-1.0.8.dist-info/RECORD

@@ -0,0 +1,12 @@
+pwndoc_mcp_server/__init__.py,sha256=Pe4Dla23dC-j4jYsISvP4RIMmtKM0a7fuKGH8l835Wo,2072
+pwndoc_mcp_server/cli.py,sha256=x6te9jK7NXqWmdt1-QonOI2J_y6ktjcHXp4AfGfK-Q4,23599
+pwndoc_mcp_server/client.py,sha256=70IMTtH5m12YDkok9zOwvixN5A9tgrdc5b_-p0I0zNs,42230
+pwndoc_mcp_server/config.py,sha256=rCe30UT7DASrz2qv_-lH2Qgl-0_bY_V_eueJliNn6y4,12854
+pwndoc_mcp_server/logging_config.py,sha256=-FuabER6p4XL-AGY3wfLRy9cBHJO6WhvgCASTiqlKRs,10648
+pwndoc_mcp_server/mcp_installer.py,sha256=xI5_s9e9p6DR_FqgforT_nHO9Q7uLpwaNV_1h5y3P68,9733
+pwndoc_mcp_server/server.py,sha256=vNXtTlNN_jJnmtzR4h7ksYWUxJjNYyH5v-gcjf4MPIE,74734
+pwndoc_mcp_server/version.py,sha256=v46b37bbWYttCe0QQZMuXn0409rT9RFTVJbLFYKGTiI,660
+pwndoc_mcp_server-1.0.8.dist-info/METADATA,sha256=msERemmCBrF2xAhx86RRB-J3hQMYAYRxI3iDsCTwleE,17549
+pwndoc_mcp_server-1.0.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pwndoc_mcp_server-1.0.8.dist-info/entry_points.txt,sha256=ksxRAw6RhdIzBX3mDMpm42qiuAF9SBYgK8aoqBJqxPI,58
+pwndoc_mcp_server-1.0.8.dist-info/RECORD,,

pwndoc_mcp_server-1.0.8.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pwndoc_mcp_server-1.0.8.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pwndoc-mcp = pwndoc_mcp_server.cli:main