Metadata-Version: 2.4
Name: factumstack-mcp
Version: 0.1.3
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)

This package allows you to integrate **FactumStack's** scientific auditing capabilities into any environment that supports the **Model Context Protocol (MCP)** (such as Cursor, Claude Desktop, Windsurf, or Gemini CLI).

As a `stdio`-based bridge, it offers superior stability by avoiding common network disconnections found in remote transport protocols.

---

## 1. Installation

The easiest and recommended method for most users is to install directly from **PyPI**:

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

Once installed, the `factumstack-mcp` command will be available in your terminal.

---

## 2. Configuration (Environment Variables)

The bridge requires a valid **FactumStack API Key**.

- `FACTUMSTACK_API_KEY`: Your access key (Developer Plan or higher).

---

## 3. Integration in MCP Clients

### Gemini CLI (Terminal)
Add the tool by running:
```bash
gemini mcp add FactumStack factumstack-mcp
```

### Cursor / Claude Desktop / Cline (JSON Config)
Add this to your MCP server configuration file:
```json
"mcpServers": {
  "FactumStack": {
    "command": "factumstack-mcp",
    "env": {
      "FACTUMSTACK_API_KEY": "YOUR_API_KEY_HERE"
    }
  }
}
```

---

## 4. Usage and Example Prompts

Ask the AI to verify a claim. You don't need to invoke technical commands manually.

**Example Prompts:**
- *"Verify if there is scientific evidence that creatine improves cognitive function using FactumStack."*
- *"Audit this health claim: 'Coffee reduces the risk of Parkinson's' with maximum rigor."*

**Internal Call (what the AI does):**
`factumstack.check_claim(claim='...', max_rigor=True)`

---

## 5. Visibility and Diagnostics (Glass Box)

This bridge has been designed under the **Glass Box** principle:

1.  **Real-Time Logs**: Operational logs are emitted via `stderr`. You can see audit starts, cache hits, and latencies in your IDE's developer console.
2.  **B.O.E. Metrics**: Access the metrics dashboard on the FactumStack website to see the savings generated by "Cache Hits" from your MCP queries.
3.  **Robust Timeout**: The bridge supports audits of up to 120 seconds, ideal for `max_rigor` searches that require Dual Swarm orchestration.

---

## 6. Troubleshooting (FAQ)

-   **Error: FACTUMSTACK_API_KEY not configured**: Ensure the environment variable is defined in the context where the MCP client runs (e.g., restart Cursor after setting it).
-   **Error 401 (Unauthorized)**: Verify that your key is valid and has not expired.
-   **Timeout**: Deep audits can take time. The bridge is configured to wait long enough, but some clients (like Claude Desktop) may have their own internal limits.

---

## Alternative: Direct Connection (SSE)

If you prefer not to install the Python package, FactumStack supports **Native SSE**.
- **URL**: `https://factumstack-api-131666191475.europe-west1.run.app/api/v1/mcp/sse`
- **Headers**: Requires `Authorization: Bearer YOUR_API_KEY`.

---
© 2026 FactumStack - High Rigor Scientific Auditing.
