factumstack-mcp 0.1.0__tar.gz

factumstack_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: factumstack-mcp
+Version: 0.1.0
+Summary: MCP Bridge for FactumStack Scientific Auditing
+Requires-Python: >=3.10
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0

factumstack_mcp-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 🚀 FactumStack MCP Bridge (Professional Edition)
+
+Este paquete permite integrar las capacidades de auditoría científica de **FactumStack** en cualquier entorno que soporte el protocolo **Model Context Protocol (MCP)** (como Cursor, Claude Desktop, Windsurf o Gemini CLI).
+
+Al ser un puente basado en `stdio`, ofrece una estabilidad superior al evitar desconexiones de red comunes en transportes remotos.
+
+---
+
+## 1. Instalación
+
+Puedes instalar el paquete directamente desde el código fuente:
+
+```bash
+pip install .
+```
+
+O en modo editable para desarrollo:
+
+```bash
+pip install -e .
+```
+
+---
+
+## 2. Configuración (Variables de Entorno)
+
+El puente requiere una **API Key** válida de FactumStack.
+
+- `FACTUMSTACK_API_KEY`: Tu clave de acceso (Plan Developer o superior).
+
+---
+
+## 3. Integración en Clientes MCP
+
+### Gemini CLI (Terminal)
+Una vez instalado el paquete, añade la herramienta simplemente ejecutando:
+```bash
+gemini mcp add FactumStack factumstack-mcp
+```
+
+### Cursor / Claude Desktop (JSON Config)
+Añade esto a tu archivo de configuración de servidores MCP:
+```json
+"mcpServers": {
+  "FactumStack": {
+    "command": "factumstack-mcp",
+    "env": {
+      "FACTUMSTACK_API_KEY": "TU_API_KEY_AQUI"
+    }
+  }
+}
+```
+
+---
+
+## 4. Uso y Prompts de Ejemplo
+
+Una vez configurado, simplemente pídele a la IA que verifique una afirmación. No necesitas invocar comandos técnicos.
+
+**Ejemplos de Prompts:**
+- *"Verifica si existe evidencia científica de que la creatina mejora la función cognitiva usando FactumStack."*
+- *"Audita este claim de salud: 'El café reduce el riesgo de Parkinson' con rigor máximo."*
+
+**Llamada Interna (lo que hace la IA):**
+`factumstack.check_claim(claim='...', max_rigor=True)`
+
+---
+
+## 5. Visibilidad y Diagnóstico (Caja de Cristal)
+
+Este puente ha sido diseñado bajo el principio de **Caja de Cristal**:
+
+1.  **Logs en Tiempo Real**: Los logs de operación se emiten por `stderr`. Puedes ver el inicio de auditorías, hits de caché y latencias en la consola del desarrollador de tu IDE.
+2.  **Métricas B.O.E.**: Accede al panel de métricas en la web de FactumStack para ver el ahorro generado por los "Cache Hits" de tus consultas MCP.
+3.  **Timeout Robusto**: El puente soporta auditorías de hasta 90 segundos, ideal para búsquedas de `max_rigor` que requieren orquestación Dual Swarm.
+
+---
+
+## 6. Resolución de Problemas (FAQ)
+
+-   **Error: FACTUMSTACK_API_KEY no configurada**: Asegúrate de que la variable de entorno esté definida en el contexto donde se ejecuta el cliente MCP (ej: reinicia Cursor después de setearla).
+-   **Error 401 (Unauthorized)**: Verifica que tu clave sea válida y no haya expirado.
+-   **Timeout**: Las auditorías profundas pueden tardar. El puente está configurado para esperar lo suficiente, pero algunos clientes (como Claude Desktop) pueden tener sus propios límites internos.
+
+---
+
+## Alternativa: Conexión Directa (SSE)
+
+Si prefieres no instalar el paquete de Python, FactumStack soporta **SSE Nativo**.
+- **URL**: `https://factumstack-api-131666191475.europe-west1.run.app/api/v1/mcp/sse`
+- **Headers**: Requiere `Authorization: Bearer TU_API_KEY`.
+
+---
+© 2026 FactumStack - Auditoría Científica de Alto Rigor.

factumstack_mcp-0.1.0/factumstack_mcp/__init__.py

@@ -0,0 +1,2 @@
+# factumstack_mcp/__init__.py
+# Vacío para que sea un paquete válido

factumstack_mcp-0.1.0/factumstack_mcp/bridge.py

@@ -0,0 +1,197 @@
+# factumstack_mcp/main.py
+import asyncio
+import httpx
+import sys
+import os
+import json
+import logging
+from mcp.server import Server
+import mcp.types as types
+from mcp.server.stdio import stdio_server
+
+# LOGGING CONFIGURATION (Glass Box)
+# Redirect logs to stderr to keep stdio transport (stdout) clean
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr
+)
+logger = logging.getLogger("factumstack-mcp")
+
+# PRODUCTION CONSTANTS
+DEFAULT_REMOTE_URL = "https://factumstack-api-131666191475.europe-west1.run.app/api/v1/audit/claim"
+
+server = Server("factumstack-bridge")
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """Lists available delegated tools from FactumStack backend."""
+    return [
+        types.Tool(
+            name="check_claim",
+            description="Audit a scientific claim using FactumStack (Scholar + OpenAlex).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "claim": {"type": "string", "description": "The scientific claim to audit."},
+                    "max_rigor": {"type": "boolean", "default": False, "description": "Deep dual-swarm search (Plan Developer+)."},
+                },
+                "required": ["claim"],
+            },
+        ),
+        types.Tool(
+            name="get_account_status",
+            description="Consult your current plan, capabilities and quotas in FactumStack.",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="check_connection",
+            description="Validate connectivity and latency with the FactumStack Cloud engine.",
+            inputSchema={"type": "object", "properties": {}},
+        )
+    ]
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict | None) -> list[types.TextContent]:
+    """
+    Professional bridge to the Cloud Run backend.
+    Delegates tool logic to the API endpoints.
+    """
+    api_key = os.getenv("FACTUMSTACK_API_KEY")
+    full_url = os.getenv("FACTUMSTACK_REMOTE_URL", DEFAULT_REMOTE_URL)
+    # Extract base URL to navigate between endpoints (/audit vs /auth)
+    base_url = full_url.split("/audit/claim")[0]
+
+    if not api_key:
+        logger.critical("FACTUMSTACK_API_KEY not found in environment.")
+        return [types.TextContent(type="text", text=json.dumps({"error": "FACTUMSTACK_API_KEY not configured."}))]
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        try:
+            if name == "check_claim":
+                claim = arguments.get("claim")
+                max_rigor = arguments.get("max_rigor", False)
+                logger.info(f"Starting audit: '{claim}' (Rigor: {max_rigor})")
+                response = await client.post(
+                    f"{base_url}/audit/claim",
+                    json={"claim": claim, "max_rigor": max_rigor},
+                    headers={"Authorization": f"Bearer {api_key}"}
+                )
+            elif name == "get_account_status":
+                logger.info("Checking account status...")
+                response = await client.get(
+                    f"{base_url}/auth/profile",
+                    headers={"Authorization": f"Bearer {api_key}"}
+                )
+            elif name == "check_connection":
+                import time
+                start_time = time.perf_counter()
+                response = await client.get(f"{base_url}/auth/profile", headers={"Authorization": f"Bearer {api_key}"})
+                latency = (time.perf_counter() - start_time) * 1000
+                
+                profile_data = response.json()
+                conn_data = {
+                    "status": "connected",
+                    "latency_ms": round(latency, 2),
+                    "endpoint": base_url,
+                    "providers": profile_data.get("system_health", {})
+                }
+                return [types.TextContent(type="text", text=json.dumps(conn_data, indent=2))]
+            else:
+                return [types.TextContent(type="text", text=json.dumps({"error": f"Unknown tool: {name}"}))]
+
+            # Unified API Error Handling (Zero-Trust)
+            if response.status_code == 401:
+                return [types.TextContent(type="text", text=json.dumps({"error": "Invalid or expired API Key."}))]
+            
+            if response.status_code == 403:
+                return [types.TextContent(type="text", text=json.dumps({"error": "Plan does not support this feature (e.g., max_rigor=True)."}))]
+            
+            response.raise_for_status()
+            data = response.json()
+            
+            # PROFESSIONAL JSON Formatting
+            if name == "check_claim":
+                audit = data.get("epistemological_audit", {})
+                flaws = audit.get("methodological_flaws", [])
+                fallacies = audit.get("fallacies_detected", [])
+                
+                mcp_data = {
+                    "factum_score": data.get("factum_score"),
+                    "factum_rating": data.get("factum_rating"),
+                    "evidence_level": audit.get("evidence_level_found", "N/A"),
+                    "summary": data.get("summary"),
+                    "critical_flaw": (flaws + fallacies)[0] if (flaws or fallacies) else "None"
+                }
+                logger.info(f"Audit completed. Score: {mcp_data['factum_score']}")
+                return [types.TextContent(type="text", text=json.dumps(mcp_data, indent=2))]
+            
+            if name == "get_account_status":
+                from datetime import datetime
+                import time
+                q = data.get("quotas", {})
+                ident = data.get("identity", {})
+                
+                reset_ms = q.get('ratelimit_reset_ms')
+                time_to_reset = max(0, int((reset_ms - (time.time() * 1000)) / 1000)) if reset_ms is not None else None
+                exp = data.get("expires_at")
+
+                account_data = {
+                    "identity": {
+                        "client_id": ident.get("client_id"),
+                        "plan": ident.get("plan", "basic").upper(),
+                        "roles": ident.get("roles", []),
+                        "permissions": ident.get("permissions", [])
+                    },
+                    "quotas": {
+                        "credits_remaining": q.get("credits_remaining"),
+                        "ratelimit_limit": q.get("ratelimit_limit"),
+                        "ratelimit_remaining": q.get("ratelimit_remaining"),
+                        "ratelimit_reset_seconds": time_to_reset
+                    },
+                    "features": data.get("features", []),
+                    "expires_at_iso": datetime.fromtimestamp(exp/1000).isoformat() if exp else None,
+                    "metadata": data.get("metadata", {})
+                }
+                return [types.TextContent(type="text", text=json.dumps(account_data, indent=2))]
+            
+        except httpx.TimeoutException:
+            logger.error(f"Timeout in tool {name}")
+            return [types.TextContent(type="text", text=json.dumps({"error": "The server took too long to respond."}))]
+        except Exception as e:
+            logger.exception(f"Unexpected error in {name}")
+            return [types.TextContent(type="text", text=json.dumps({"error": f"Bridge error: {str(e)}"}))]
+
+async def start_server():
+    """Startup the stdio transport server."""
+    logger.info("FactumStack MCP Bridge started (Transport: stdio)")
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options()
+        )
+
+def run():
+    """Entry point for the factumstack-mcp command."""
+    # Load environment variables from .env if available
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+        logger.info(".env file loaded successfully.")
+    except ImportError:
+        logger.warning("python-dotenv not installed, skipping .env load.")
+
+    if not os.getenv("FACTUMSTACK_API_KEY"):
+        print("CRITICAL: FACTUMSTACK_API_KEY not found.", file=sys.stderr)
+        print("Usage: export FACTUMSTACK_API_KEY='your_key' or set it in a .env file", file=sys.stderr)
+        sys.exit(1)
+        
+    try:
+        asyncio.run(start_server())
+    except KeyboardInterrupt:
+        logger.info("Server stopped by user")
+        sys.exit(0)
+
+if __name__ == "__main__":
+    run()

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

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: factumstack-mcp
+Version: 0.1.0
+Summary: MCP Bridge for FactumStack Scientific Auditing
+Requires-Python: >=3.10
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0

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

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+factumstack_mcp/__init__.py
+factumstack_mcp/bridge.py
+factumstack_mcp.egg-info/PKG-INFO
+factumstack_mcp.egg-info/SOURCES.txt
+factumstack_mcp.egg-info/dependency_links.txt
+factumstack_mcp.egg-info/entry_points.txt
+factumstack_mcp.egg-info/requires.txt
+factumstack_mcp.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

factumstack_mcp-0.1.0/factumstack_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+factumstack-mcp = factumstack_mcp.bridge:run

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

@@ -0,0 +1,3 @@
+mcp>=0.1.0
+httpx>=0.27.0
+python-dotenv>=1.0.0

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

@@ -0,0 +1 @@
+factumstack_mcp

factumstack_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "factumstack-mcp"
+version = "0.1.0"
+description = "MCP Bridge for FactumStack Scientific Auditing"
+dependencies = [
+    "mcp>=0.1.0",
+    "httpx>=0.27.0",
+    "python-dotenv>=1.0.0",
+]
+requires-python = ">=3.10"
+
+# ESTA ES LA CLAVE: Crea el comando ejecutable
+[project.scripts]
+factumstack-mcp = "factumstack_mcp.bridge:run"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

factumstack_mcp-0.1.0/setup.cfg

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