mcpcap 0.2.2__tar.gz → 0.3.0__tar.gz

{mcpcap-0.2.2 → mcpcap-0.3.0}/.gitignore

@@ -215,4 +215,5 @@ src/mcpcap/_version.py
 !examples/*.pcap
 !examples/*.pcapng
 
-.DS_Store
+.DS_Store
+plan.md

{mcpcap-0.2.2/src/mcpcap.egg-info → mcpcap-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpcap
-Version: 0.2.2
+Version: 0.3.0
 Summary: A modular Python MCP Server for analyzing PCAP files
 Author: mcpcap contributors
 License: MIT
@@ -23,6 +23,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastmcp
 Requires-Dist: scapy
+Requires-Dist: requests
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
@@ -85,10 +86,26 @@ uvx mcpcap
 
 1. **Start the MCP Server**:
 
+   **Local PCAP file:**
+   ```bash
+   mcpcap --pcap-path /path/to/specific/file.pcap
+   ```
+
+   **Local PCAP directory:**
    ```bash
    mcpcap --pcap-path /path/to/pcap/files
    ```
 
+   **Remote PCAP file:**
+   ```bash
+   mcpcap --pcap-url https://example.com/sample.pcap
+   ```
+
+   **With advanced options:**
+   ```bash
+   mcpcap --pcap-path /path/to/pcaps --max-packets 100 --protocols dns
+   ```
+
 2. **Connect your LLM client** to the MCP server
 
 3. **Ask questions** about your network traffic:
@@ -121,27 +138,80 @@ The DNS module analyzes Domain Name System packets in PCAP files.
 
 ### PCAP Sources
 
-**Local Directory**:
+mcpcap supports multiple ways to specify PCAP data sources:
 
+**Local PCAP File**:
+```bash
+mcpcap --pcap-path /local/path/to/specific.pcap
+```
+
+**Local Directory**:
 ```bash
 mcpcap --pcap-path /local/path/to/pcaps
 ```
 
-**Remote HTTP Server**:
+**Remote PCAP File (Direct Link)**:
+```bash
+mcpcap --pcap-url https://wiki.wireshark.org/uploads/dns.cap
+```
 
+**Remote Directory Listing**:
 ```bash
 mcpcap --pcap-url http://example.com/pcaps/
 ```
 
-### Module Selection
+### Analysis Options
 
+**Module Selection**:
 ```bash
 mcpcap --modules dns --pcap-path /path/to/files
 ```
 
+**Protocol Filtering**:
+```bash
+mcpcap --protocols dns --pcap-path /path/to/files
+```
+
+**Packet Limiting** (for large files):
+```bash
+mcpcap --max-packets 1000 --pcap-path /path/to/files
+```
+
+**Combined Options**:
+```bash
+mcpcap --pcap-path /data/capture.pcap --max-packets 500 --protocols dns
+```
+
+## CLI Reference
+
+```bash
+mcpcap [--pcap-path PATH | --pcap-url URL] [OPTIONS]
+```
+
+**Source Options** (choose one):
+- `--pcap-path PATH`: Local PCAP file or directory
+- `--pcap-url URL`: Remote PCAP file URL or directory listing
+
+**Analysis Options**:
+- `--modules MODULES`: Comma-separated modules to load (default: dns)
+- `--protocols PROTOCOLS`: Comma-separated protocols to analyze (default: dns) 
+- `--max-packets N`: Maximum packets to analyze per file (default: unlimited)
+
+**Examples**:
+```bash
+# Analyze specific file
+mcpcap --pcap-path ./capture.pcap
+
+# Remote file with packet limit
+mcpcap --pcap-url https://example.com/dns.cap --max-packets 100
+
+# Directory with protocol filter
+mcpcap --pcap-path /captures --protocols dns --modules dns
+```
+
 ## Example
 
-An example PCAP file (`example.pcap`) containing DNS traffic is included with the project to help you get started.
+An example PCAP file (`dns.pcap`) containing DNS traffic is included in the `examples/` directory to help you get started.
 
 ## Architecture
 
@@ -170,7 +240,26 @@ Future modules might include:
 
 ## Remote Access
 
-mcpcap supports reading PCAP files from remote HTTP servers without authentication. Future versions may include support for Basic Authentication and other security mechanisms.
+mcpcap supports reading PCAP files from remote HTTP servers in two modes:
+
+**Direct File Access**: Point directly to a PCAP file URL
+```bash
+mcpcap --pcap-url https://wiki.wireshark.org/uploads/__moin_import__/attachments/SampleCaptures/dns.cap
+```
+
+**Directory Listing**: Parse HTML directory listings to find PCAP files
+```bash
+mcpcap --pcap-url http://server.com/pcap-files/
+```
+
+**Supported File Types**: `.pcap`, `.pcapng`, `.cap`
+
+**Current Limitations**:
+- HTTP/HTTPS only (no authentication)
+- Directory listings require standard HTML format
+- Files are downloaded temporarily for analysis
+
+Future versions may include support for Basic Authentication and other security mechanisms.
 
 ## Contributing
 
@@ -190,8 +279,10 @@ MIT
 ## Requirements
 
 - Python 3.10+
-- scapy
-- MCP server dependencies (automatically installed)
+- scapy (packet parsing and analysis)
+- requests (HTTP remote file access)
+- fastmcp (MCP server framework)
+- All dependencies are automatically installed via pip
 
 ## Support
 

{mcpcap-0.2.2 → mcpcap-0.3.0}/README.md

@@ -42,10 +42,26 @@ uvx mcpcap
 
 1. **Start the MCP Server**:
 
+   **Local PCAP file:**
+   ```bash
+   mcpcap --pcap-path /path/to/specific/file.pcap
+   ```
+
+   **Local PCAP directory:**
    ```bash
    mcpcap --pcap-path /path/to/pcap/files
    ```
 
+   **Remote PCAP file:**
+   ```bash
+   mcpcap --pcap-url https://example.com/sample.pcap
+   ```
+
+   **With advanced options:**
+   ```bash
+   mcpcap --pcap-path /path/to/pcaps --max-packets 100 --protocols dns
+   ```
+
 2. **Connect your LLM client** to the MCP server
 
 3. **Ask questions** about your network traffic:
@@ -78,27 +94,80 @@ The DNS module analyzes Domain Name System packets in PCAP files.
 
 ### PCAP Sources
 
-**Local Directory**:
+mcpcap supports multiple ways to specify PCAP data sources:
 
+**Local PCAP File**:
+```bash
+mcpcap --pcap-path /local/path/to/specific.pcap
+```
+
+**Local Directory**:
 ```bash
 mcpcap --pcap-path /local/path/to/pcaps
 ```
 
-**Remote HTTP Server**:
+**Remote PCAP File (Direct Link)**:
+```bash
+mcpcap --pcap-url https://wiki.wireshark.org/uploads/dns.cap
+```
 
+**Remote Directory Listing**:
 ```bash
 mcpcap --pcap-url http://example.com/pcaps/
 ```
 
-### Module Selection
+### Analysis Options
 
+**Module Selection**:
 ```bash
 mcpcap --modules dns --pcap-path /path/to/files
 ```
 
+**Protocol Filtering**:
+```bash
+mcpcap --protocols dns --pcap-path /path/to/files
+```
+
+**Packet Limiting** (for large files):
+```bash
+mcpcap --max-packets 1000 --pcap-path /path/to/files
+```
+
+**Combined Options**:
+```bash
+mcpcap --pcap-path /data/capture.pcap --max-packets 500 --protocols dns
+```
+
+## CLI Reference
+
+```bash
+mcpcap [--pcap-path PATH | --pcap-url URL] [OPTIONS]
+```
+
+**Source Options** (choose one):
+- `--pcap-path PATH`: Local PCAP file or directory
+- `--pcap-url URL`: Remote PCAP file URL or directory listing
+
+**Analysis Options**:
+- `--modules MODULES`: Comma-separated modules to load (default: dns)
+- `--protocols PROTOCOLS`: Comma-separated protocols to analyze (default: dns) 
+- `--max-packets N`: Maximum packets to analyze per file (default: unlimited)
+
+**Examples**:
+```bash
+# Analyze specific file
+mcpcap --pcap-path ./capture.pcap
+
+# Remote file with packet limit
+mcpcap --pcap-url https://example.com/dns.cap --max-packets 100
+
+# Directory with protocol filter
+mcpcap --pcap-path /captures --protocols dns --modules dns
+```
+
 ## Example
 
-An example PCAP file (`example.pcap`) containing DNS traffic is included with the project to help you get started.
+An example PCAP file (`dns.pcap`) containing DNS traffic is included in the `examples/` directory to help you get started.
 
 ## Architecture
 
@@ -127,7 +196,26 @@ Future modules might include:
 
 ## Remote Access
 
-mcpcap supports reading PCAP files from remote HTTP servers without authentication. Future versions may include support for Basic Authentication and other security mechanisms.
+mcpcap supports reading PCAP files from remote HTTP servers in two modes:
+
+**Direct File Access**: Point directly to a PCAP file URL
+```bash
+mcpcap --pcap-url https://wiki.wireshark.org/uploads/__moin_import__/attachments/SampleCaptures/dns.cap
+```
+
+**Directory Listing**: Parse HTML directory listings to find PCAP files
+```bash
+mcpcap --pcap-url http://server.com/pcap-files/
+```
+
+**Supported File Types**: `.pcap`, `.pcapng`, `.cap`
+
+**Current Limitations**:
+- HTTP/HTTPS only (no authentication)
+- Directory listings require standard HTML format
+- Files are downloaded temporarily for analysis
+
+Future versions may include support for Basic Authentication and other security mechanisms.
 
 ## Contributing
 
@@ -147,8 +235,10 @@ MIT
 ## Requirements
 
 - Python 3.10+
-- scapy
-- MCP server dependencies (automatically installed)
+- scapy (packet parsing and analysis)
+- requests (HTTP remote file access)
+- fastmcp (MCP server framework)
+- All dependencies are automatically installed via pip
 
 ## Support
 

mcpcap-0.3.0/docs/source/_static/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures the _static directory is tracked by git
+# Static files for Sphinx documentation go here

{mcpcap-0.2.2 → mcpcap-0.3.0}/docs/source/conf.py

@@ -52,7 +52,6 @@ html_theme_options = {
     "canonical_url": "",
     "analytics_id": "",
     "logo_only": False,
-    "display_version": True,
     "prev_next_buttons_location": "bottom",
     "style_external_links": False,
     "vcs_pageview_mode": "",

{mcpcap-0.2.2 → mcpcap-0.3.0}/docs/source/user-guide/installation.md

@@ -57,6 +57,7 @@ mcpcap depends on:
 
 - **fastmcp**: MCP server framework
 - **scapy**: Packet parsing and analysis
+- **requests**: HTTP client for remote PCAP access
 - **Python 3.10+**: Modern Python features and type hints
 
 All dependencies are automatically installed when you install mcpcap.

{mcpcap-0.2.2 → mcpcap-0.3.0}/docs/source/user-guide/mcp-integration.md

@@ -144,11 +144,17 @@ Analyzes DNS packets in a PCAP file.
 ### Server Configuration
 
 ```bash
-# Basic usage
+# Local directory
 mcpcap --pcap-path /path/to/pcaps
 
-# Advanced options (coming soon)
-mcpcap --pcap-path /path/to/pcaps --max-packets 1000 --protocols dns,http
+# Local file
+mcpcap --pcap-path /path/to/specific.pcap
+
+# Remote file
+mcpcap --pcap-url https://example.com/capture.pcap
+
+# With analysis options
+mcpcap --pcap-path /path/to/pcaps --max-packets 1000 --protocols dns --modules dns
 ```
 
 ### Client Configuration Examples
@@ -158,16 +164,20 @@ mcpcap --pcap-path /path/to/pcaps --max-packets 1000 --protocols dns,http
 ```json
 {
   "mcpServers": {
+    "mcpcap-local-file": {
+      "command": "mcpcap",
+      "args": ["--pcap-path", "/path/to/specific.pcap", "--max-packets", "500"]
+    },
     "mcpcap-production": {
       "command": "mcpcap",
-      "args": ["--pcap-path", "/production/captures"],
+      "args": ["--pcap-path", "/production/captures", "--protocols", "dns"],
       "env": {
         "LOG_LEVEL": "INFO"
       }
     },
-    "mcpcap-analysis": {
+    "mcpcap-remote": {
       "command": "mcpcap", 
-      "args": ["--pcap-path", "/analysis/workspace"]
+      "args": ["--pcap-url", "https://example.com/samples/dns.cap"]
     }
   }
 }

{mcpcap-0.2.2 → mcpcap-0.3.0}/docs/source/user-guide/quickstart.md

@@ -8,24 +8,40 @@ Get up and running with mcpcap in minutes!
 pip install mcpcap
 ```
 
-## 2. Prepare Your PCAP Files
+## 2. Choose Your PCAP Source
 
-Create a directory with your PCAP files:
+mcpcap supports multiple PCAP sources:
 
+**Single PCAP file**:
+```bash
+# Use a specific PCAP file
+mcpcap --pcap-path ~/Downloads/capture.pcap
+```
+
+**Directory of PCAP files**:
 ```bash
 mkdir ~/pcap-analysis
 # Copy your PCAP files to this directory
 cp your-capture.pcap ~/pcap-analysis/
+mcpcap --pcap-path ~/pcap-analysis
 ```
 
-## 3. Start the MCP Server
-
+**Remote PCAP file**:
 ```bash
-mcpcap --pcap-path ~/pcap-analysis
+# Direct link to a PCAP file
+mcpcap --pcap-url https://wiki.wireshark.org/uploads/__moin_import__/attachments/SampleCaptures/dns.cap
 ```
 
+## 3. Start the MCP Server
+
 The server will start and display connection information. Keep this terminal open.
 
+**With analysis options**:
+```bash
+# Limit to first 100 packets for faster analysis
+mcpcap --pcap-path ~/pcap-analysis --max-packets 100
+```
+
 ## 4. Connect with an MCP Client
 
 ### Option A: MCP Inspector (Quick Testing)
@@ -34,7 +50,15 @@ Install and run MCP Inspector:
 
 ```bash
 npm install -g @modelcontextprotocol/inspector
+
+# Test with local directory
 npx @modelcontextprotocol/inspector mcpcap --pcap-path ~/pcap-analysis
+
+# Test with specific file
+npx @modelcontextprotocol/inspector mcpcap --pcap-path ~/capture.pcap
+
+# Test with remote file
+npx @modelcontextprotocol/inspector mcpcap --pcap-url https://example.com/dns.cap
 ```
 
 This opens a web interface where you can test the tools interactively.
@@ -87,7 +111,7 @@ Use the `list_dns_packets` tool with a filename:
       "stackoverflow.com"
     ]
   },
-  "packets": [...]
+  "packets": ["..."]
 }
 ```
 
@@ -133,7 +157,7 @@ Here's a typical analysis workflow:
 
 - Explore the [MCP Integration Guide](mcp-integration.md) for detailed client setup
 - Read the [Analysis Guides](analysis-guides.md) for advanced techniques
-- Check out the [Examples](../examples/security-analysis.md) for real-world scenarios
+- Check out the examples directory for real-world scenarios
 
 ## Common Issues
 

mcpcap-0.3.0/examples/README.md

@@ -0,0 +1,64 @@
+# mcpcap Examples
+
+This directory contains example PCAP files and usage demonstrations.
+
+## Example Files
+
+- `dns.pcap` - Sample DNS traffic capture for testing mcpcap functionality
+
+## Usage Examples
+
+### Basic Analysis
+
+**Analyze the entire examples directory:**
+```bash
+mcpcap --pcap-path ./examples
+```
+
+**Analyze specific file:**
+```bash
+mcpcap --pcap-path ./examples/dns.pcap
+```
+
+**With packet limits for faster testing:**
+```bash
+mcpcap --pcap-path ./examples/dns.pcap --max-packets 50
+```
+
+### MCP Client Testing
+
+**With MCP Inspector:**
+```bash
+npm install -g @modelcontextprotocol/inspector
+npx @modelcontextprotocol/inspector mcpcap --pcap-path ./examples/dns.pcap
+```
+
+Then use the web interface to:
+- Call `list_pcap_files()` to see available files
+- Call `list_dns_packets()` (leave filename empty for direct file mode)
+- View structured DNS analysis results
+
+### Analysis Prompts
+
+Use these specialized prompts in your MCP client:
+
+- **`security_analysis`** - Focus on threat detection in DNS traffic
+- **`network_troubleshooting`** - Identify DNS performance issues  
+- **`forensic_investigation`** - Detailed timeline and attribution analysis
+
+## Creating Your Own Examples
+
+To add new example files:
+
+1. Place PCAP files (`.pcap` or `.pcapng`) in this directory
+2. Update this README with descriptions
+3. Test with the mcpcap server
+
+## Sample Output
+
+When analyzing DNS packets, you'll get structured JSON output including:
+
+- Packet timestamps and network details
+- DNS query/response information
+- Statistics (queries, responses, unique domains)
+- Security-relevant metadata

{mcpcap-0.2.2 → mcpcap-0.3.0}/pyproject.toml

@@ -28,6 +28,7 @@ classifiers = [
 dependencies = [
     "fastmcp",
     "scapy",
+    "requests",
 ]
 
 [project.optional-dependencies]
@@ -73,6 +74,7 @@ include = ["mcpcap*"]
 target-version = "py310"
 line-length = 88
 src = ["src", "tests"]
+exclude = ["src/mcpcap/_version.py"]
 
 [tool.ruff.lint]
 select = [

{mcpcap-0.2.2 → mcpcap-0.3.0}/src/mcpcap/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__commit_id__ = commit_id = 'gfe9c89f9a'
+__commit_id__ = commit_id = 'gc1a9a0372'

mcpcap-0.3.0/src/mcpcap/cli.py

@@ -0,0 +1,85 @@
+"""CLI entry point for mcpcap.
+
+This module provides the command-line interface for mcpcap, handling argument parsing
+and server initialization.
+"""
+
+import argparse
+import sys
+
+from .core import Config, MCPServer
+
+
+def main():
+    """Main function to parse arguments and start the MCP server.
+
+    Parses command-line arguments, initializes the configuration and MCP server,
+    and handles graceful shutdown and error conditions.
+
+    Returns:
+        int: Exit code (0 for success, 1 for error)
+
+    Raises:
+        ValueError: If the provided PCAP path is invalid
+        KeyboardInterrupt: If the user interrupts the server
+        Exception: For any unexpected errors during server operation
+    """
+    parser = argparse.ArgumentParser(description="mcpcap MCP Server")
+
+    # PCAP source options (mutually exclusive)
+    source_group = parser.add_mutually_exclusive_group(required=True)
+    source_group.add_argument(
+        "--pcap-path", help="Path to PCAP file or directory containing PCAP files"
+    )
+    source_group.add_argument(
+        "--pcap-url",
+        help="HTTP URL to PCAP file (direct link) or directory containing PCAP files",
+    )
+
+    # Analysis options
+    parser.add_argument(
+        "--modules",
+        help="Comma-separated list of modules to load (default: dns)",
+        default="dns",
+    )
+    parser.add_argument(
+        "--protocols",
+        help="Comma-separated list of protocols to analyze (default: dns)",
+        default="dns",
+    )
+    parser.add_argument(
+        "--max-packets",
+        type=int,
+        help="Maximum number of packets to analyze per file (default: unlimited)",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        # Initialize configuration
+        config = Config(
+            pcap_path=args.pcap_path,
+            pcap_url=args.pcap_url,
+            modules=args.modules.split(",") if args.modules else ["dns"],
+            protocols=args.protocols.split(",") if args.protocols else ["dns"],
+            max_packets=args.max_packets,
+        )
+
+        # Create and start MCP server
+        server = MCPServer(config)
+        server.run()
+        return 0
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\\nServer stopped by user", file=sys.stderr)
+        return 0
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    exit(main())