Metadata-Version: 2.4
Name: factumstack-mcp
Version: 1.5.0
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 & Update

Install or update the package directly from **PyPI**:

```bash
# Install new version
pip install factumstack-mcp

# Update to latest (v1.4.0+)
pip install --upgrade factumstack-mcp
```

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

---

## 2. Configuration (Environment Variables)

The bridge requires a valid API key. You can set it as an environment variable or in a **`.env`** file in your working directory:

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

---

## 3. Integration in MCP Clients

> **⚠️ Important:** Most clients (including Gemini CLI and Cursor) require a **restart** or a **new session** to discover newly registered tools and environment variables correctly.

### Gemini CLI (Terminal)
The most robust way to add the tool is by using the Python module execution:
```bash
gemini mcp add FactumStack python --args "-m,factumstack_mcp.bridge"
```
*Note: Ensure your `FACTUMSTACK_API_KEY` is available in your environment or added to the `.gemini/settings.json` file. **Restart your terminal session after running this command.***

### Cursor / Claude Desktop / Cline (JSON Config)
Add this to your MCP server configuration file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
```json
"mcpServers": {
  "FactumStack": {
    "command": "python",
    "args": ["-m", "factumstack_mcp.bridge"],
    "env": {
      "FACTUMSTACK_API_KEY": "YOUR_API_KEY_HERE"
    }
  }
}
```
*Tip: Using `python -m` ensures the bridge finds all its dependencies regardless of your system's PATH configuration. **Restart your IDE/Client after saving the configuration file.***

---

## 4. Usage and Available Tools

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."*

**The AI will automatically discover and use these three tools:**

○ **`check_claim`**: Performs a deep scientific audit with high-granularity alignment.
  - **Inputs**: `claim` (string, req), `max_rigor` (boolean, opt).
  - **Outputs**: 
    - `factum_score`: Reliability score (0-100).
    - `factum_rating`: Qualitative verdict.
    - `evidence_level`: Highest detected evidence level.
    - `summary`: Executive conclusion.
    - `reasoning_scratchpad`: Full Chain-of-Thought reasoning based on scientific abstracts.
    - `critical_flaw`: The most relevant methodological or logical flaw detected.
    - `citations`: List of lightweight citations including Titles, Authors, Year, and URLs for direct consultation.

○ **`get_account_status`**: Consults your plan, identity, and usage quotas.
  - **Outputs**: Detailed JSON with `identity`, `quotas`, and active `features`.

○ **`check_connection`**: Diagnostic tool for infrastructure.
  - **Outputs**: `status`, `latency_ms`, `endpoint`, and providers' health (`Scholar`, `OpenAlex`).

---

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