mcpcat 0.1.0__tar.gz

mcpcat-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(uv run pytest tests/test_get_unknown_or_stdio_session.py -v)",
+      "Bash(uv run:*)",
+      "Bash(rg:*)",
+      "Bash(/Users/naseemalnaji/.nvm/versions/node/v23.5.0/lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep/arm64-darwin/rg \"CallToolResult\" --type py -A 3 -B 3)",
+      "Bash(/Users/naseemalnaji/.nvm/versions/node/v23.5.0/lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep/arm64-darwin/rg \"from mcp.types import.*CallToolResult\" --type py)",
+      "Bash(pip show:*)"
+    ],
+    "deny": []
+  }
+}

mcpcat-0.1.0/.github/workflows/mcp-compatibility.yml

@@ -0,0 +1,119 @@
+name: MCP Version Compatibility Testing
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    # Run weekly to catch new MCP versions
+    - cron: '0 0 * * 0'
+  workflow_dispatch:
+
+jobs:
+  discover-versions:
+    runs-on: ubuntu-latest
+    outputs:
+      mcp-versions: ${{ steps.get-versions.outputs.versions }}
+    
+    steps:
+    - name: Get available MCP versions
+      id: get-versions
+      run: |
+        # Get all available versions from PyPI
+        versions=$(pip index versions mcp 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | sort -V)
+        
+        # Filter to versions >= 1.2.0 and get only latest patch version for each minor
+        declare -A latest_minor
+        for version in $versions; do
+          major=$(echo $version | cut -d. -f1)
+          minor=$(echo $version | cut -d. -f2)
+          patch=$(echo $version | cut -d. -f3)
+          
+          # Include if version >= 1.2.0
+          if [ "$major" -gt 1 ] || ([ "$major" -eq 1 ] && [ "$minor" -ge 2 ]); then
+            minor_key="$major.$minor"
+            latest_minor[$minor_key]="$version"
+          fi
+        done
+        
+        # Create JSON array from latest versions
+        filtered_versions=()
+        for version in "${latest_minor[@]}"; do
+          filtered_versions+=("\"$version\"")
+        done
+        
+        json_array="[$(IFS=,; echo "${filtered_versions[*]}")]"
+        echo "Found MCP versions: $json_array"
+        echo "versions=$json_array" >> $GITHUB_OUTPUT
+
+  test-compatibility:
+    runs-on: ubuntu-latest
+    needs: discover-versions
+    strategy:
+      matrix:
+        mcp-version: ${{ fromJson(needs.discover-versions.outputs.mcp-versions) }}
+      fail-fast: false
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+    
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    
+    - name: Update pyproject.toml with MCP ${{ matrix.mcp-version }}
+      run: |
+        # Replace the whole quoted string, preserving the trailing comma
+        sed -i -E 's/"mcp==[^"]+"/"mcp==${{ matrix.mcp-version }}"/' pyproject.toml
+        
+    - name: Install dependencies with MCP ${{ matrix.mcp-version }}
+      run: |
+        uv sync --extra dev
+    
+    - name: Run full test suite with MCP ${{ matrix.mcp-version }}
+      run: |
+        echo "Running full test suite with MCP version ${{ matrix.mcp-version }}"
+        uv run pytest tests/ -v
+  
+  report-compatibility:
+    runs-on: ubuntu-latest
+    needs: [discover-versions, test-compatibility]
+    if: always()
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Print compatibility report
+      run: |
+        echo "=========================================="
+        echo "     MCP VERSION COMPATIBILITY REPORT    "
+        echo "=========================================="
+        echo ""
+        echo "This report shows the compatibility status of MCPCat with different MCP versions."
+        echo ""
+        echo "Generated on: $(date)"
+        echo ""
+        echo "📋 TESTED VERSIONS"
+        echo "─────────────────────────────────────────"
+        echo "MCP versions tested: ${{ needs.discover-versions.outputs.mcp-versions }}"
+        echo "Python version: 3.12"
+        echo ""
+        echo "🧪 TEST COVERAGE"
+        echo "─────────────────────────────────────────"
+        echo "✓ FastMCP server compatibility"
+        echo "✓ Low-level Server compatibility"
+        echo "✓ Both implementations tested with is_compatible_server function"
+        echo ""
+        echo "📊 RESULTS"
+        echo "─────────────────────────────────────────"
+        echo "Check the individual test job results above for detailed compatibility status."
+        echo "Each MCP version was tested in a separate matrix job."
+        echo ""
+        echo "=========================================="

mcpcat-0.1.0/.gitignore

@@ -0,0 +1,147 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# macOS
+.DS_Store
+
+# uv
+.uv/
+uv.lock

mcpcat-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+- Always run with `uv`

mcpcat-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mcpcat
+Version: 0.1.0
+Summary: Analytics Tool for MCP Servers - provides insights into MCP tool usage patterns
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: datafog>=4.1.1
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MCPCat Python SDK
+
+Analytics tool for MCP (Model Context Protocol) servers that provides insights into tool usage patterns.
+
+## Features
+
+- **Tool Usage Analytics**: Tracks which tools are called and how frequently
+- **Context Injection**: Adds context parameters to tools to understand user intent  
+- **Session Tracking**: Identifies and tracks user sessions
+- **Report Missing Tools**: Allows clients to report when needed tools are missing
+- **PII Redaction**: Automatically redacts sensitive information from logs
+- **Non-invasive Integration**: Simple one-line integration with existing MCP servers
+
+## Installation
+
+```bash
+pip install mcpcat
+```
+
+## Quick Start
+
+```python
+from fastmcp import FastMCP
+from mcpcat import track
+
+# Create your MCP server
+mcp = FastMCP("my-server")
+
+# Add your tools
+@mcp.tool()
+def my_tool(arg: str) -> str:
+    return f"Result: {arg}"
+
+# Enable MCPCat tracking
+track(mcp)
+
+# Run the server
+mcp.run()
+```
+
+## Configuration
+
+MCPCat can be configured with various options:
+
+```python
+from mcpcat import track, MCPCatOptions
+
+options = MCPCatOptions(
+    enableToolCallContext=True,   # Add context parameters to tools
+    enableTracing=True,           # Trace tool calls
+    enableReportMissing=True,     # Add report_missing tool
+    identify=my_identify_func     # Custom session identification
+)
+
+track(mcp, options)
+```
+
+## How It Works
+
+1. MCPCat intercepts the MCP server's tool listing and calling mechanisms
+2. It injects a `context` parameter into each tool's schema
+3. When tools are called, it captures analytics data including timing, arguments, and results
+4. The `report_missing` tool allows LLMs to report when they need functionality that isn't available
+
+## Custom Session Identification
+
+You can provide a custom function to identify users:
+
+```python
+def identify_user(request_context):
+    # Your logic to identify the user
+    return {
+        "sessionId": "session-123",
+        "userId": "user-456"
+    }
+
+options = MCPCatOptions(identify=identify_user)
+```
+
+## Log Format
+
+MCPCat logs are written in JSON format with the following structure:
+
+```json
+{
+  "timestamp": "2024-01-20T10:30:00Z",
+  "event": "tool_call",
+  "tool_name": "my_tool",
+  "session_id": "session-123",
+  "user_id": "user-456",
+  "duration": 0.123,
+  "result": "success",
+  "context_provided": true
+}
+```
+
+## Development
+
+To set up for development:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/mcpcat-python-sdk.git
+cd mcpcat-python-sdk
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run type checking
+mypy src
+
+# Run linting
+ruff check src
+```
+
+## License
+
+MIT