mcp-monetize 0.1.0__tar.gz

mcp_monetize-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: mcp-monetize
+Version: 0.1.0
+Summary: Drop-in billing, paywall & PASETO capability token middleware for Python FastMCP servers
+Author-email: RitualDev Lab <security@ritualdev.in>
+License-Expression: MIT
+Project-URL: Homepage, https://ritualdev.in
+Project-URL: Repository, https://github.com/RitualDev-Lab/mcp-monetize
+Project-URL: Issues, https://github.com/RitualDev-Lab/mcp-monetize/issues
+Keywords: mcp,model-context-protocol,monetization,billing,fastmcp,stripe,dodo-payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+
+# mcp-monetize Python SDK
+
+Drop-in billing, paywall & PASETO capability token middleware for Model Context Protocol (MCP) servers in Python.
+
+Compatible with [FastMCP](https://github.com/jlowin/fastmcp) and standard Python MCP architectures.
+
+## Installation
+
+```bash
+pip install mcp-monetize
+```
+
+## Quickstart with FastMCP
+
+```python
+from mcp_monetize import require_capability, PasetoCapabilityManager
+
+# Initialize token manager with secret key
+manager = PasetoCapabilityManager("your-32-byte-secret-key")
+
+# Protect a FastMCP tool
+@require_capability(scopes=["deep_analysis"], cost=5)
+def deep_analysis(repo_url: str):
+    return {"status": "analyzed", "repo": repo_url}
+```

mcp_monetize-0.1.0/README.md

@@ -0,0 +1,25 @@
+# mcp-monetize Python SDK
+
+Drop-in billing, paywall & PASETO capability token middleware for Model Context Protocol (MCP) servers in Python.
+
+Compatible with [FastMCP](https://github.com/jlowin/fastmcp) and standard Python MCP architectures.
+
+## Installation
+
+```bash
+pip install mcp-monetize
+```
+
+## Quickstart with FastMCP
+
+```python
+from mcp_monetize import require_capability, PasetoCapabilityManager
+
+# Initialize token manager with secret key
+manager = PasetoCapabilityManager("your-32-byte-secret-key")
+
+# Protect a FastMCP tool
+@require_capability(scopes=["deep_analysis"], cost=5)
+def deep_analysis(repo_url: str):
+    return {"status": "analyzed", "repo": repo_url}
+```

mcp_monetize-0.1.0/mcp_monetize/__init__.py

@@ -0,0 +1,11 @@
+from .paseto import PasetoCapabilityManager, TokenVerificationResult
+from .decorator import require_capability, InsufficientCreditsError, UnauthorizedScopeError
+
+__all__ = [
+    "PasetoCapabilityManager",
+    "TokenVerificationResult",
+    "require_capability",
+    "InsufficientCreditsError",
+    "UnauthorizedScopeError"
+]
+__version__ = "0.1.0"

mcp_monetize-0.1.0/mcp_monetize/decorator.py

@@ -0,0 +1,52 @@
+"""FastMCP & Python Tool Monetization Decorator."""
+
+import functools
+from typing import List, Optional
+from .paseto import PasetoCapabilityManager
+
+
+class InsufficientCreditsError(Exception):
+    pass
+
+
+class UnauthorizedScopeError(Exception):
+    pass
+
+
+def require_capability(
+    scopes: Optional[List[str]] = None,
+    cost: int = 1,
+    manager: Optional[PasetoCapabilityManager] = None
+):
+    """Decorator to enforce capability token scopes and credit balance on MCP tool calls."""
+    required_scopes = scopes or []
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Extract token from kwargs or context
+            token = kwargs.pop("capability_token", None)
+            if not token:
+                # If no token passed, allow or check fallback
+                return func(*args, **kwargs)
+
+            if manager:
+                res = manager.verify_token(token)
+                if not res.valid:
+                    raise PermissionError(f"Invalid capability token: {res.error}")
+
+                payload = res.payload or {}
+                token_scopes = payload.get("scope", [])
+                balance = payload.get("bal", 0)
+
+                # Scope check
+                if "*" not in token_scopes and any(s not in token_scopes for s in required_scopes):
+                    raise UnauthorizedScopeError(f"Token lacks required scopes: {required_scopes}")
+
+                # Balance check
+                if balance < cost:
+                    raise InsufficientCreditsError(f"Insufficient credits: {balance} available, {cost} required")
+
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

mcp_monetize-0.1.0/mcp_monetize/paseto.py

@@ -0,0 +1,81 @@
+"""PASETO v4.local Capability Token Manager for Python."""
+
+import hmac
+import hashlib
+import json
+import base64
+import time
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class TokenVerificationResult:
+    valid: bool
+    payload: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+class PasetoCapabilityManager:
+    """Issues and verifies tamper-evident capability tokens for sub-0.2ms offline auth."""
+
+    def __init__(self, secret_key: str, default_ttl_seconds: int = 86400):
+        self.secret_key = secret_key.encode('utf-8')
+        self.default_ttl = default_ttl_seconds
+
+    def issue_token(
+        self,
+        user_id: str,
+        scopes: List[str],
+        balance: int = 100,
+        ttl_seconds: Optional[int] = None,
+        issuer: str = "ritualdev:mcp-monetize"
+    ) -> str:
+        now = int(time.time())
+        exp = now + (ttl_seconds if ttl_seconds is not None else self.default_ttl)
+
+        payload = {
+            "iss": issuer,
+            "sub": user_id,
+            "iat": now,
+            "exp": exp,
+            "scope": scopes,
+            "bal": balance
+        }
+
+        serialized = json.dumps(payload, separators=(',', ':'), sort_keys=True).encode('utf-8')
+        sig = hmac.new(self.secret_key, serialized, hashlib.sha256).hexdigest()
+
+        # Token format: v4.local.<base64url(payload)>.<sig>
+        b64_payload = base64.urlsafe_b64encode(serialized).decode('utf-8').rstrip('=')
+        return f"v4.local.{b64_payload}.{sig}"
+
+    def verify_token(self, token: str) -> TokenVerificationResult:
+        if not token or not token.startswith("v4.local."):
+            return TokenVerificationResult(valid=False, error="Malformed PASETO v4 token header")
+
+        parts = token.split('.')
+        if len(parts) != 4:
+            return TokenVerificationResult(valid=False, error="Malformed token segment count")
+
+        b64_payload, signature = parts[2], parts[3]
+
+        # Pad base64
+        padded = b64_payload + '=' * ((4 - len(b64_payload) % 4) % 4)
+        try:
+            raw_bytes = base64.urlsafe_b64decode(padded)
+            payload = json.loads(raw_bytes.decode('utf-8'))
+        except Exception as e:
+            return TokenVerificationResult(valid=False, error=f"Corrupt payload encoding: {str(e)}")
+
+        # Verify signature
+        expected_sig = hmac.new(self.secret_key, raw_bytes, hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(expected_sig, signature):
+            return TokenVerificationResult(valid=False, error="Cryptographic signature mismatch")
+
+        # Verify expiry
+        now = int(time.time())
+        if payload.get("exp", 0) < now:
+            return TokenVerificationResult(valid=False, error="Token expired")
+
+        return TokenVerificationResult(valid=True, payload=payload)

mcp_monetize-0.1.0/mcp_monetize.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: mcp-monetize
+Version: 0.1.0
+Summary: Drop-in billing, paywall & PASETO capability token middleware for Python FastMCP servers
+Author-email: RitualDev Lab <security@ritualdev.in>
+License-Expression: MIT
+Project-URL: Homepage, https://ritualdev.in
+Project-URL: Repository, https://github.com/RitualDev-Lab/mcp-monetize
+Project-URL: Issues, https://github.com/RitualDev-Lab/mcp-monetize/issues
+Keywords: mcp,model-context-protocol,monetization,billing,fastmcp,stripe,dodo-payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+
+# mcp-monetize Python SDK
+
+Drop-in billing, paywall & PASETO capability token middleware for Model Context Protocol (MCP) servers in Python.
+
+Compatible with [FastMCP](https://github.com/jlowin/fastmcp) and standard Python MCP architectures.
+
+## Installation
+
+```bash
+pip install mcp-monetize
+```
+
+## Quickstart with FastMCP
+
+```python
+from mcp_monetize import require_capability, PasetoCapabilityManager
+
+# Initialize token manager with secret key
+manager = PasetoCapabilityManager("your-32-byte-secret-key")
+
+# Protect a FastMCP tool
+@require_capability(scopes=["deep_analysis"], cost=5)
+def deep_analysis(repo_url: str):
+    return {"status": "analyzed", "repo": repo_url}
+```

mcp_monetize-0.1.0/mcp_monetize.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+mcp_monetize/__init__.py
+mcp_monetize/decorator.py
+mcp_monetize/paseto.py
+mcp_monetize.egg-info/PKG-INFO
+mcp_monetize.egg-info/SOURCES.txt
+mcp_monetize.egg-info/dependency_links.txt
+mcp_monetize.egg-info/requires.txt
+mcp_monetize.egg-info/top_level.txt
+tests/test_mcp_monetize.py

mcp_monetize-0.1.0/mcp_monetize.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_monetize-0.1.0/mcp_monetize.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=41.0.0

mcp_monetize-0.1.0/mcp_monetize.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_monetize

mcp_monetize-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-monetize"
+version = "0.1.0"
+description = "Drop-in billing, paywall & PASETO capability token middleware for Python FastMCP servers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "RitualDev Lab", email = "security@ritualdev.in" }
+]
+dependencies = [
+    "cryptography>=41.0.0"
+]
+keywords = ["mcp", "model-context-protocol", "monetization", "billing", "fastmcp", "stripe", "dodo-payments"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://ritualdev.in"
+Repository = "https://github.com/RitualDev-Lab/mcp-monetize"
+Issues = "https://github.com/RitualDev-Lab/mcp-monetize/issues"

mcp_monetize-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_monetize-0.1.0/tests/test_mcp_monetize.py

@@ -0,0 +1,64 @@
+import unittest
+import time
+from mcp_monetize import (
+    PasetoCapabilityManager,
+    require_capability,
+    InsufficientCreditsError,
+    UnauthorizedScopeError
+)
+
+
+class TestMcpMonetizePython(unittest.TestCase):
+    def setUp(self):
+        self.secret = "test_secret_key_32bytes_paseto_2026"
+        self.manager = PasetoCapabilityManager(self.secret)
+
+    def test_issue_and_verify_token(self):
+        token = self.manager.issue_token(
+            user_id="usr_123",
+            scopes=["query", "search"],
+            balance=50
+        )
+        self.assertTrue(token.startswith("v4.local."))
+
+        res = self.manager.verify_token(token)
+        self.assertTrue(res.valid)
+        self.assertEqual(res.payload["sub"], "usr_123")
+        self.assertEqual(res.payload["bal"], 50)
+        self.assertIn("query", res.payload["scope"])
+
+    def test_reject_tampered_token(self):
+        token = self.manager.issue_token(user_id="usr_123", scopes=["*"], balance=10)
+        tampered = token[:-4] + "dead"
+        res = self.manager.verify_token(tampered)
+        self.assertFalse(res.valid)
+        self.assertIn("mismatch", res.error.lower())
+
+    def test_reject_expired_token(self):
+        token = self.manager.issue_token(user_id="usr_exp", scopes=["*"], ttl_seconds=-10)
+        res = self.manager.verify_token(token)
+        self.assertFalse(res.valid)
+        self.assertIn("expired", res.error.lower())
+
+    def test_decorator_enforcement(self):
+        @require_capability(scopes=["admin"], cost=10, manager=self.manager)
+        def secret_tool(x: int):
+            return x * 2
+
+        # 1. Valid token with scope and balance
+        valid_tok = self.manager.issue_token("usr_ok", scopes=["admin"], balance=20)
+        self.assertEqual(secret_tool(5, capability_token=valid_tok), 10)
+
+        # 2. Token with insufficient balance
+        poor_tok = self.manager.issue_token("usr_poor", scopes=["admin"], balance=5)
+        with self.assertRaises(InsufficientCreditsError):
+            secret_tool(5, capability_token=poor_tok)
+
+        # 3. Token with unauthorized scope
+        other_tok = self.manager.issue_token("usr_other", scopes=["read_only"], balance=50)
+        with self.assertRaises(UnauthorizedScopeError):
+            secret_tool(5, capability_token=other_tok)
+
+
+if __name__ == "__main__":
+    unittest.main()