mcpcap 0.4.7__tar.gz → 0.5.2__tar.gz

{mcpcap-0.4.7 → mcpcap-0.5.2}/.github/workflows/release.yml

@@ -32,13 +32,18 @@ jobs:
       run: |
         # Extract version from tag (remove 'v' prefix)
         TAG_VERSION=${GITHUB_REF#refs/tags/v}
-        # Get version from setuptools-scm
-        DETECTED_VERSION=$(python -c "from setuptools_scm import get_version; print(get_version())")
+        # Debug git state
+        echo "Current commit: $(git rev-parse HEAD)"
+        echo "Current tag: $(git describe --tags)"
+        echo "All tags: $(git tag --list | tail -3)"
+        # Get version from setuptools-scm with debug
+        DETECTED_VERSION=$(python -c "import setuptools_scm; print(setuptools_scm.get_version())")
         echo "Tag version: $TAG_VERSION"
         echo "Detected version: $DETECTED_VERSION"
         # Verify they match
         if [ "$TAG_VERSION" != "$DETECTED_VERSION" ]; then
           echo "Version mismatch! Tag: $TAG_VERSION, Detected: $DETECTED_VERSION"
+          echo "This might be due to setuptools-scm caching or git fetch issues"
           exit 1
         fi
 
@@ -138,19 +143,6 @@ jobs:
       if: steps.pypi_publish.outcome == 'success'
       run: ./mcp-publisher login dns --domain mcpcap.ai --private-key "${{ secrets.MCP_PRIVATE_KEY }}"
 
-    # -------- (Optional) Validate server.json before publishing ----------------
-    - name: Validate server.json (optional)
-      if: steps.pypi_publish.outcome == 'success'
-      run: |
-        if [ -f server.json ]; then
-          # Validate against published schema
-          curl -s https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json | jq . > schema.json
-          npm i -g ajv-cli >/dev/null 2>&1 || true
-          ajv validate -s schema.json -d server.json || (echo "server.json failed schema validation"; exit 1)
-        else
-          echo "server.json not found; skipping validation"
-        fi
-
     # -------- MCP Registry: publish -------------------------------------------
     - name: Publish to MCP Registry
       if: steps.pypi_publish.outcome == 'success'

{mcpcap-0.4.7 → mcpcap-0.5.2}/.gitignore

@@ -217,4 +217,9 @@ src/mcpcap/_version.py
 
 .DS_Store
 plan.md
-key.pem
+key.pem
+
+# Website files (used separately)
+index.html
+script.js
+styles.css

mcpcap-0.5.2/CONTRIBUTING.md

@@ -0,0 +1,474 @@
+# Contributing to mcpcap
+
+Thank you for your interest in contributing to mcpcap! This guide will help you get started with development and contributing new features, especially new protocol analysis modules.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Code Style and Standards](#code-style-and-standards)
+- [Creating New Modules](#creating-new-modules)
+- [Testing Requirements](#testing-requirements)
+- [Documentation](#documentation)
+- [Pull Request Process](#pull-request-process)
+- [Getting Help](#getting-help)
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- Git
+- Virtual environment tool (venv, conda, etc.)
+
+### Setup Process
+
+1. **Fork and clone the repository:**
+   ```bash
+   git clone https://github.com/your-username/mcpcap.git
+   cd mcpcap
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install development dependencies:**
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+4. **Development tools are already included:**
+   ```bash
+   # The [dev] dependencies include ruff, mypy, pytest, etc.
+   # No additional installation needed
+   ```
+
+5. **Verify installation:**
+   ```bash
+   # Run tests
+   pytest
+   
+   # Start the server
+   mcpcap
+   ```
+
+## Code Style and Standards
+
+### Python Code Style
+
+We use several tools to maintain code quality:
+
+- **Ruff**: For linting and formatting
+- **Black**: Code formatting (via ruff)
+- **isort**: Import sorting (via ruff)
+- **mypy**: Type checking
+
+### Running Code Quality Checks
+
+```bash
+# Format code
+ruff format
+
+# Check linting
+ruff check
+
+# Type checking (when mypy is configured)
+mypy src/mcpcap
+
+# Run all checks together
+ruff check && ruff format && pytest
+```
+
+### Code Standards
+
+1. **Type Hints**: All functions should have type hints (we're working to improve existing code)
+2. **Docstrings**: All public functions and classes must have docstrings
+3. **Error Handling**: Use explicit exception handling with meaningful messages
+4. **Logging**: Use proper logging instead of print statements
+5. **Testing**: All new code must have tests with >95% coverage
+
+**Note**: We're currently improving our codebase to fully comply with mypy strict mode. New contributions should follow these standards, and we welcome help fixing existing type issues!
+
+## Creating New Modules
+
+### Module Architecture
+
+mcpcap uses a modular architecture where each protocol analyzer inherits from `BaseModule`. Here's how to create a new module:
+
+### 1. Create the Module File
+
+Create a new file in `src/mcpcap/modules/` for your protocol (e.g., `http.py`):
+
+```python
+"""HTTP analysis module."""
+
+from typing import Any
+from fastmcp import FastMCP
+from scapy.all import HTTP, TCP, rdpcap
+
+from .base import BaseModule
+
+
+class HTTPModule(BaseModule):
+    """Module for analyzing HTTP packets in PCAP files."""
+
+    @property
+    def protocol_name(self) -> str:
+        """Return the name of the protocol this module analyzes."""
+        return "HTTP"
+
+    def analyze_http_packets(self, pcap_file: str) -> dict[str, Any]:
+        """
+        Analyze HTTP packets from a PCAP file.
+
+        Args:
+            pcap_file: Path to local PCAP file or HTTP URL to remote PCAP file
+
+        Returns:
+            A structured dictionary containing HTTP packet analysis results
+        """
+        return self.analyze_packets(pcap_file)
+
+    def _analyze_protocol_file(self, pcap_file: str) -> dict[str, Any]:
+        """Perform the actual HTTP packet analysis on a local PCAP file."""
+        try:
+            packets = rdpcap(pcap_file)
+            http_packets = [pkt for pkt in packets if pkt.haslayer(HTTP)]
+
+            if not http_packets:
+                return {
+                    "file": pcap_file,
+                    "total_packets": len(packets),
+                    "http_packets_found": 0,
+                    "message": "No HTTP packets found in this capture",
+                }
+
+            # Apply max_packets limit if specified
+            packets_to_analyze = http_packets
+            limited = False
+            if self.config.max_packets and len(http_packets) > self.config.max_packets:
+                packets_to_analyze = http_packets[:self.config.max_packets]
+                limited = True
+
+            packet_details = []
+            for i, pkt in enumerate(packets_to_analyze, 1):
+                packet_info = self._analyze_http_packet(pkt, i)
+                packet_details.append(packet_info)
+
+            # Generate statistics
+            stats = self._generate_statistics(packet_details)
+
+            result = {
+                "file": pcap_file,
+                "total_packets": len(packets),
+                "http_packets_found": len(http_packets),
+                "http_packets_analyzed": len(packet_details),
+                "statistics": stats,
+                "packets": packet_details,
+            }
+
+            if limited:
+                result["note"] = (
+                    f"Analysis limited to first {self.config.max_packets} HTTP packets"
+                )
+
+            return result
+
+        except Exception as e:
+            return {
+                "error": f"Error reading PCAP file '{pcap_file}': {str(e)}",
+                "file": pcap_file,
+            }
+
+    def _analyze_http_packet(self, packet, packet_num: int) -> dict[str, Any]:
+        """Analyze a single HTTP packet."""
+        # Implement packet analysis logic
+        return {
+            "packet_number": packet_num,
+            "timestamp": packet.time,
+            # Add more fields as needed
+        }
+
+    def _generate_statistics(self, packets: list[dict[str, Any]]) -> dict[str, Any]:
+        """Generate statistics from analyzed HTTP packets."""
+        # Implement statistics generation
+        return {
+            "total_requests": 0,
+            "total_responses": 0,
+            # Add more statistics as needed
+        }
+
+    def setup_prompts(self, mcp: FastMCP) -> None:
+        """Set up HTTP-specific analysis prompts."""
+        
+        @mcp.prompt
+        def http_security_analysis():
+            """Prompt for analyzing HTTP traffic from a security perspective"""
+            return """You are analyzing HTTP traffic for security issues..."""
+```
+
+### 2. Register the Module
+
+Add your module to `src/mcpcap/core/server.py`:
+
+```python
+from ..modules.http import HTTPModule  # Add import
+
+# In the __init__ method:
+if "http" in self.config.modules:
+    self.modules["http"] = HTTPModule(config)
+
+# In the _register_tools method:
+elif module_name == "http":
+    self.mcp.tool(module.analyze_http_packets)
+```
+
+### 3. Update Configuration
+
+Add your module to the default modules list in `src/mcpcap/cli.py`:
+
+```python
+parser.add_argument(
+    "--modules",
+    default="dns,dhcp,http",  # Add your module here
+    help="Comma-separated list of modules to load (dns,dhcp,http)",
+)
+```
+
+### 4. Create Tests
+
+Create tests in `tests/test_modules/test_http.py`:
+
+```python
+"""Tests for HTTP module."""
+
+from unittest.mock import Mock, patch
+import pytest
+
+from mcpcap.modules.http import HTTPModule
+from mcpcap.core.config import Config
+
+
+class TestHTTPModule:
+    """Test HTTP module functionality."""
+
+    def setup_method(self):
+        """Set up test fixtures."""
+        config = Config(modules=["http"], max_packets=None)
+        self.http_module = HTTPModule(config)
+
+    def test_protocol_name(self):
+        """Test protocol name property."""
+        assert self.http_module.protocol_name == "HTTP"
+
+    @patch("mcpcap.modules.http.rdpcap")
+    def test_analyze_http_packets_no_packets(self, mock_rdpcap):
+        """Test analysis with no HTTP packets."""
+        # Mock empty packet capture
+        mock_rdpcap.return_value = []
+        
+        result = self.http_module.analyze_http_packets("test.pcap")
+        
+        assert result["http_packets_found"] == 0
+        assert "No HTTP packets found" in result["message"]
+```
+
+### 5. Add Documentation
+
+Create documentation in `docs/source/user-guide/` and add examples to the tutorial.
+
+## Testing Requirements
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src/mcpcap --cov-report=html
+
+# Run specific test file
+pytest tests/test_modules/test_http.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Test Coverage Requirements
+
+- All new modules must have >95% test coverage
+- All public methods must have tests
+- Error conditions must be tested
+- Edge cases should be covered
+
+### Test Structure
+
+- Unit tests for individual functions
+- Integration tests for module workflow
+- Mock external dependencies (scapy, file system, network)
+- Test both success and failure scenarios
+
+## Documentation
+
+### Required Documentation
+
+1. **Module docstrings**: Complete API documentation
+2. **User guide updates**: Add your module to relevant guides
+3. **Examples**: Provide working examples with sample data
+4. **Tutorial updates**: Add your module to the module creation tutorial
+
+### Documentation Style
+
+- Use clear, concise language
+- Provide practical examples
+- Include both simple and advanced use cases
+- Follow the existing documentation structure
+
+### Building Documentation Locally
+
+```bash
+# Install docs dependencies
+pip install -e ".[docs]"
+
+# Build documentation
+cd docs
+make html
+
+# View documentation
+open build/html/index.html
+```
+
+## Development Workflow
+
+We follow **GitHub Flow** for all development:
+
+1. **Create feature branches** from `main` for all changes
+2. **Use descriptive branch names**: `feature/add-http-module`, `fix/dns-parsing-bug`, `docs/update-contributing`
+3. **Keep branches focused** - one feature or fix per branch
+4. **Create pull requests early** for feedback and collaboration
+5. **Merge to main** only after review and CI passes
+6. **Delete feature branches** after merging
+
+### Branch Naming Convention
+
+```bash
+feature/description-of-feature    # New features
+fix/description-of-bug           # Bug fixes  
+docs/description-of-change       # Documentation updates
+refactor/description-of-change   # Code refactoring
+test/description-of-test         # Test improvements
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Run all checks:**
+   ```bash
+   # Format and lint your code
+   ruff format
+   ruff check
+   
+   # Run tests
+   pytest
+   
+   # Optional: Check types (may show issues in existing code)
+   mypy src/mcpcap --follow-imports=skip
+   ```
+
+2. **Update documentation:**
+   - Add/update docstrings
+   - Update user guides if needed
+   - Add examples
+
+3. **Write good commit messages:**
+   ```
+   Add HTTP analysis module
+   
+   - Implement HTTP packet parsing with request/response analysis
+   - Add security-focused analysis prompts
+   - Include comprehensive test coverage
+   - Update documentation with HTTP examples
+   ```
+
+### Pull Request Guidelines
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/add-http-module
+   ```
+
+2. **Keep PRs focused:** One feature or fix per PR
+
+3. **Write descriptive PR description:**
+   - Explain what the PR does
+   - Reference any related issues
+   - Include testing notes
+   - Add examples of usage
+
+4. **Respond to review feedback:** Address all comments promptly
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature (new protocol module)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Other (please describe)
+
+## Testing
+- [ ] Tests pass locally
+- [ ] Added new tests for new functionality
+- [ ] Coverage remains >95%
+
+## Documentation
+- [ ] Updated relevant documentation
+- [ ] Added examples
+- [ ] Docstrings updated
+
+## Checklist
+- [ ] Code follows style guidelines
+- [ ] Self-review completed
+- [ ] Tests added/updated
+- [ ] Documentation updated
+```
+
+## Getting Help
+
+### Resources
+
+- **Documentation**: https://mcpcap.readthedocs.io
+- **Examples**: Check the `examples/` directory
+- **Existing modules**: Study `dns.py` and `dhcp.py` as references
+
+### Communication
+
+- **Issues**: Open GitHub issues for bugs or feature requests
+- **Discussions**: Use GitHub discussions for questions
+- **Security**: Report security issues privately
+
+### Module Development Tips
+
+1. **Start simple:** Begin with basic packet parsing
+2. **Follow patterns:** Use existing modules as templates  
+3. **Test incrementally:** Write tests as you develop
+4. **Handle errors gracefully:** Provide meaningful error messages
+5. **Document as you go:** Write docstrings immediately
+
+## Contributing Guidelines Summary
+
+- Fork the repository and create feature branches
+- Follow code style and testing requirements
+- Write comprehensive documentation
+- Submit focused pull requests
+- Respond to review feedback promptly
+
+Thank you for contributing to mcpcap! Your contributions help make network analysis more accessible and powerful for everyone.