Metadata-Version: 2.4
Name: factumstack-mcp
Version: 0.1.1
Summary: MCP Bridge for FactumStack Scientific Auditing
Author-email: Kossen <contacto@factumstack.com>
License: MIT
Project-URL: Homepage, https://factumstack-api-131666191475.europe-west1.run.app
Project-URL: Repository, https://github.com/factumstack/factumstack-mcp
Keywords: mcp,ai,science,audit,fact-checking,gemini
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0

# 🚀 FactumStack MCP Bridge (Professional Edition)

[![PyPI version](https://img.shields.io/pypi/v/factumstack-mcp.svg)](https://pypi.org/project/factumstack-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/factumstack-mcp.svg)](https://pypi.org/project/factumstack-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

La forma más sencilla y recomendada para la mayoría de los usuarios es instalar directamente desde **PyPI**:

```bash
pip install factumstack-mcp
```

Una vez instalado, el comando `factumstack-mcp` estará disponible en tu terminal.

---

## 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)
Añade la herramienta ejecutando:
```bash
gemini mcp add FactumStack factumstack-mcp
```

### Cursor / Claude Desktop / Cline (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

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. Desarrollo e Instalación desde Fuente (Avanzado)

Si deseas contribuir al proyecto o probar versiones en desarrollo:

1. Clona el repositorio.
2. Instala en modo editable:
```bash
pip install -e .
```

---

## 6. 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.
