system1-mcp 0.1.0__tar.gz

system1_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 System 1 Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

system1_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: system1-mcp
+Version: 0.1.0
+Summary: Jev-powered System 1 reflex engine for AI agents via Model Context Protocol (MCP)
+Author: System 1 Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://typesafe.ai
+Project-URL: Documentation, https://github.com/ericmaddox/system1-mcp#readme
+Project-URL: Repository, https://github.com/ericmaddox/system1-mcp
+Project-URL: Issues, https://github.com/ericmaddox/system1-mcp/issues
+Keywords: mcp,ai-agents,typesafe,jev,system-1,system1,guardrails,routing,reflex,claude,cursor,antigravity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: typesafe-sdk>=0.5.7
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# System 1 MCP Server
+
+[![CI](https://github.com/ericmaddox/system1-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ericmaddox/system1-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/system1-mcp.svg)](https://pypi.org/project/system1-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**A Jev-powered System 1 reflex engine for AI agents via Model Context Protocol (MCP).**
+
+Modern AI agents (Claude Desktop, Cursor, Antigravity, OpenHands, Hermes) typically route every decision through a full large language model deliberation loop—even for fast binary checks such as determining if a command is destructive or selecting among known configuration paths. This introduces 1,500–3,000 ms of latency and burns unnecessary tokens per evaluation.
+
+**System 1 MCP** provides agents with calibrated, low-latency **System 1 reflexes**. Powered by [TypeSafe](https://typesafe.ai)'s Jev model, System 1 MCP exposes 4 specialized MCP tools that return typed probabilities and discrete verdicts in approximately 50–150 ms without chain-of-thought token generation.
+
+```
+Agent (Claude / Cursor / Antigravity)
+   │
+   ▼  [MCP stdio JSON-RPC]
+System 1 MCP Server
+   │
+   ▼  [Single TypeSafe API call ~50-150ms]
+TypeSafe Jev (System One) ──► Calibrated Probabilities & Decisions
+```
+
+---
+
+## Latency Profile and Operational Model
+
+- **Model inference**: ~20–40 ms
+- **Network round-trip to api.typesafe.ai**: ~30–120 ms (geography dependent)
+- **Total end-to-end latency**: **~50–200 ms**
+- Compared to full LLM deliberation (~1,500–3,000 ms), System 1 MCP executes **10x–20x faster** while using zero output tokens.
+
+> **Advisory Notice**: MCP tools provide advisory assessments. System 1 MCP supplies calibrated risk probabilities and classifications; the calling agent's decision engine retains authority over final execution.
+
+---
+
+## Tool Reference
+
+### 1. `fast_guard` — Pre-Execution Command and Action Safety Check
+
+Call prior to executing shell commands, database updates, or external API modifications to assess risk profile and blast radius.
+
+**Input**:
+```json
+{
+  "command": "rm -rf /var/cache/*",
+  "goal": "Clean project temporary artifacts",
+  "workspace": "/repo"
+}
+```
+
+**Output**:
+```json
+{
+  "action": "block",
+  "is_destructive": 0.99,
+  "is_dangerous": 0.72,
+  "is_out_of_scope": 0.85,
+  "blast_radius": {
+    "score": 2.1,
+    "legend": {
+      "0": "Isolated: Read-only check, single temporary file",
+      "1": "Workspace: Modifies local project directory",
+      "2": "System-wide: Modifies system configuration or root",
+      "3": "External: Impacts remote servers or databases"
+    }
+  }
+}
+```
+
+**Decision Logic**:
+- If `max(is_destructive, is_dangerous) >= block_threshold` (default `0.80`) ➔ `"block"`
+- Else if `max(is_destructive, is_dangerous) >= review_threshold` (default `0.40`) ➔ `"review"`
+- Else ➔ `"pass"`
+
+---
+
+### 2. `fast_judge` — Best-Option Selection
+
+Select one option from a bounded set without deliberative text generation.
+
+**Input**:
+```json
+{
+  "question": "Which configuration file handles TypeScript compiler options?",
+  "options": {
+    "tsconfig.json": "TypeScript configuration",
+    "package.json": "NPM manifest",
+    "vite.config.ts": "Bundler configuration"
+  }
+}
+```
+
+**Output**:
+```json
+{
+  "choice": "tsconfig.json",
+  "confidence": 0.96,
+  "probabilities": {
+    "tsconfig.json": 0.96,
+    "package.json": 0.03,
+    "vite.config.ts": 0.01
+  },
+  "is_confident": true
+}
+```
+
+---
+
+### 3. `fast_verify` — Condition and State Verification
+
+Verify assertions against evidence, goal completion, test outputs, or status checks.
+
+**Input**:
+```json
+{
+  "statement": "All unit tests passed without regression",
+  "evidence": "PASSED tests/test_auth.py (14/14) in 1.2s. 0 failed, 0 skipped."
+}
+```
+
+**Output**:
+```json
+{
+  "probability": 0.98,
+  "is_true": true,
+  "assessment": "high_confidence_yes"
+}
+```
+
+**Assessment Classifications**:
+- `> 0.85` ➔ `"high_confidence_yes"`
+- `0.60–0.85` ➔ `"likely_yes"`
+- `0.40–0.60` ➔ `"uncertain"`
+- `0.15–0.40` ➔ `"likely_no"`
+- `< 0.15` ➔ `"high_confidence_no"`
+
+---
+
+### 4. `fast_score` — Multi-Level Assessment
+
+Evaluate inputs against an ordered scale (e.g., severity, priority, or alignment).
+
+**Input**:
+```json
+{
+  "question": "Rate the severity of this production alert",
+  "levels": [
+    "Low / Cosmetic: non-blocking visual issue",
+    "Medium: degraded feature with workaround available",
+    "High / Critical: database unavailable or data corruption risk"
+  ],
+  "content": "ALERT: Primary PostgreSQL instance replication lag exceeded 15 minutes, writes failing."
+}
+```
+
+**Output**:
+```json
+{
+  "score": 1.95,
+  "confidence": 0.91,
+  "legend": {
+    "0": "Low / Cosmetic: non-blocking visual issue",
+    "1": "Medium: degraded feature with workaround available",
+    "2": "High / Critical: database unavailable or data corruption risk"
+  },
+  "probabilities": {
+    "0": 0.01,
+    "1": 0.08,
+    "2": 0.91
+  },
+  "is_confident": true
+}
+```
+
+---
+
+## Resilience and Graceful Escalation
+
+When API errors, network timeouts, or rate limits occur, System 1 MCP maintains standard MCP connection stability and does not terminate the JSON-RPC channel. Instead, it emits a structured fallback payload:
+
+```json
+{
+  "error": true,
+  "error_type": "api_timeout",
+  "message": "TypeSafe API request timed out after 5.0s",
+  "fallback_action": "escalate"
+}
+```
+
+When receiving `fallback_action: "escalate"`, the host agent gracefully falls back to standard LLM deliberative reasoning.
+
+---
+
+## Installation and Setup
+
+### Option A: Automatic Multi-IDE Installer (Recommended)
+
+System 1 MCP includes an automated installer that detects and configures Claude Desktop, Cursor, Google Antigravity, Windsurf, Roo Code, Cline, and Zed:
+
+```bash
+# Interactive setup (prompts for API key and autodetects IDE installations)
+uvx system1-mcp install
+
+# Non-interactive setup with explicit key
+uvx system1-mcp install --api-key ts_live_your_key_here
+```
+
+### Option B: Health Check and Diagnostics (`doctor`)
+
+Inspect installation status, identify detected configuration paths, and measure live API latency:
+
+```bash
+uvx system1-mcp doctor
+```
+
+Sample output:
+```
+>> System 1 MCP Diagnostics (v0.1.0)
+
+Environment:
+  Python:        3.11.15
+  Config File:   ~/.system1/config.json (found)
+
+API Key Status:
+  Status:        [OK] Configured
+  Resolved Key:  ts_...8f2a
+  Source Origin: config_file
+
+Live TypeSafe Jev Connectivity:
+  Status:        [OK] Connected to api.typesafe.ai
+  Model:         jev-latest
+  Roundtrip:     64.2ms
+  Calibration:   P(valid) = 0.99
+
+Detected IDE Configurations:
+  Claude Desktop       [Detected     ] -> Configured [OK]
+  Cursor               [Detected     ] -> Configured [OK]
+  Google Antigravity   [Detected     ] -> Configured [OK]
+```
+
+---
+
+### Option C: Manual Configuration
+
+To manually configure an editor, add the server configuration entry:
+
+#### Claude Desktop (`claude_desktop_config.json`) / Antigravity (`mcp_config.json`) / Cursor
+```json
+{
+  "mcpServers": {
+    "system1": {
+      "command": "uvx",
+      "args": ["system1-mcp"],
+      "env": {
+        "TYPESAFE_API_KEY": "your-typesafe-api-key-here"
+      }
+    }
+  }
+}
+```
+
+> **Note**: If your key is stored in `~/.system1/config.json`, the `"env"` block is optional; the server resolves stored credentials automatically.
+
+---
+
+## Configuration Hierarchy
+
+System 1 MCP searches for credentials using the following resolution order:
+
+1. **Process Environment**: `TYPESAFE_API_KEY` (from environment or host IDE `env` map)
+2. **User Configuration**: `~/.system1/config.json` (with fallback to `~/.fastpath/config.json`)
+3. **Workspace File**: `.env` in the current working directory
+
+To configure stored user credentials via CLI:
+
+```bash
+# Store API key
+uvx system1-mcp config set-key ts_live_your_key_here
+
+# Display current configuration status
+uvx system1-mcp config show
+```
+
+---
+
+## Development and Testing
+
+```bash
+# Run unit test suite (27 offline unit tests)
+pytest tests/ -v -m "not integration"
+
+# Run integration tests against the live TypeSafe Jev API (requires TYPESAFE_API_KEY)
+pytest tests/test_integration.py -v -m integration
+```
+
+---
+
+## Architectural Comparison
+
+| Dimension | TypeSafe Agent Skill | System 1 MCP |
+|---|---|---|
+| **Role** | Instruction skill (`SKILL.md`) guiding LLMs to write TypeSafe code | Pre-packaged MCP server giving agents low-latency runtime reflexes |
+| **Agent Schema Requirement** | Requires knowledge of `Noul`, `Choice`, `Score`, and state representations | Zero schema complexity; simple tool invocations (e.g. `fast_guard`) |
+| **Target Use Case** | Generating TypeSafe application code | Real-time safety validation, option routing, and verification |
+
+---
+
+## License
+
+This project is licensed under the terms of the [MIT License](LICENSE).

system1_mcp-0.1.0/README.md

@@ -0,0 +1,311 @@
+# System 1 MCP Server
+
+[![CI](https://github.com/ericmaddox/system1-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ericmaddox/system1-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/system1-mcp.svg)](https://pypi.org/project/system1-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**A Jev-powered System 1 reflex engine for AI agents via Model Context Protocol (MCP).**
+
+Modern AI agents (Claude Desktop, Cursor, Antigravity, OpenHands, Hermes) typically route every decision through a full large language model deliberation loop—even for fast binary checks such as determining if a command is destructive or selecting among known configuration paths. This introduces 1,500–3,000 ms of latency and burns unnecessary tokens per evaluation.
+
+**System 1 MCP** provides agents with calibrated, low-latency **System 1 reflexes**. Powered by [TypeSafe](https://typesafe.ai)'s Jev model, System 1 MCP exposes 4 specialized MCP tools that return typed probabilities and discrete verdicts in approximately 50–150 ms without chain-of-thought token generation.
+
+```
+Agent (Claude / Cursor / Antigravity)
+   │
+   ▼  [MCP stdio JSON-RPC]
+System 1 MCP Server
+   │
+   ▼  [Single TypeSafe API call ~50-150ms]
+TypeSafe Jev (System One) ──► Calibrated Probabilities & Decisions
+```
+
+---
+
+## Latency Profile and Operational Model
+
+- **Model inference**: ~20–40 ms
+- **Network round-trip to api.typesafe.ai**: ~30–120 ms (geography dependent)
+- **Total end-to-end latency**: **~50–200 ms**
+- Compared to full LLM deliberation (~1,500–3,000 ms), System 1 MCP executes **10x–20x faster** while using zero output tokens.
+
+> **Advisory Notice**: MCP tools provide advisory assessments. System 1 MCP supplies calibrated risk probabilities and classifications; the calling agent's decision engine retains authority over final execution.
+
+---
+
+## Tool Reference
+
+### 1. `fast_guard` — Pre-Execution Command and Action Safety Check
+
+Call prior to executing shell commands, database updates, or external API modifications to assess risk profile and blast radius.
+
+**Input**:
+```json
+{
+  "command": "rm -rf /var/cache/*",
+  "goal": "Clean project temporary artifacts",
+  "workspace": "/repo"
+}
+```
+
+**Output**:
+```json
+{
+  "action": "block",
+  "is_destructive": 0.99,
+  "is_dangerous": 0.72,
+  "is_out_of_scope": 0.85,
+  "blast_radius": {
+    "score": 2.1,
+    "legend": {
+      "0": "Isolated: Read-only check, single temporary file",
+      "1": "Workspace: Modifies local project directory",
+      "2": "System-wide: Modifies system configuration or root",
+      "3": "External: Impacts remote servers or databases"
+    }
+  }
+}
+```
+
+**Decision Logic**:
+- If `max(is_destructive, is_dangerous) >= block_threshold` (default `0.80`) ➔ `"block"`
+- Else if `max(is_destructive, is_dangerous) >= review_threshold` (default `0.40`) ➔ `"review"`
+- Else ➔ `"pass"`
+
+---
+
+### 2. `fast_judge` — Best-Option Selection
+
+Select one option from a bounded set without deliberative text generation.
+
+**Input**:
+```json
+{
+  "question": "Which configuration file handles TypeScript compiler options?",
+  "options": {
+    "tsconfig.json": "TypeScript configuration",
+    "package.json": "NPM manifest",
+    "vite.config.ts": "Bundler configuration"
+  }
+}
+```
+
+**Output**:
+```json
+{
+  "choice": "tsconfig.json",
+  "confidence": 0.96,
+  "probabilities": {
+    "tsconfig.json": 0.96,
+    "package.json": 0.03,
+    "vite.config.ts": 0.01
+  },
+  "is_confident": true
+}
+```
+
+---
+
+### 3. `fast_verify` — Condition and State Verification
+
+Verify assertions against evidence, goal completion, test outputs, or status checks.
+
+**Input**:
+```json
+{
+  "statement": "All unit tests passed without regression",
+  "evidence": "PASSED tests/test_auth.py (14/14) in 1.2s. 0 failed, 0 skipped."
+}
+```
+
+**Output**:
+```json
+{
+  "probability": 0.98,
+  "is_true": true,
+  "assessment": "high_confidence_yes"
+}
+```
+
+**Assessment Classifications**:
+- `> 0.85` ➔ `"high_confidence_yes"`
+- `0.60–0.85` ➔ `"likely_yes"`
+- `0.40–0.60` ➔ `"uncertain"`
+- `0.15–0.40` ➔ `"likely_no"`
+- `< 0.15` ➔ `"high_confidence_no"`
+
+---
+
+### 4. `fast_score` — Multi-Level Assessment
+
+Evaluate inputs against an ordered scale (e.g., severity, priority, or alignment).
+
+**Input**:
+```json
+{
+  "question": "Rate the severity of this production alert",
+  "levels": [
+    "Low / Cosmetic: non-blocking visual issue",
+    "Medium: degraded feature with workaround available",
+    "High / Critical: database unavailable or data corruption risk"
+  ],
+  "content": "ALERT: Primary PostgreSQL instance replication lag exceeded 15 minutes, writes failing."
+}
+```
+
+**Output**:
+```json
+{
+  "score": 1.95,
+  "confidence": 0.91,
+  "legend": {
+    "0": "Low / Cosmetic: non-blocking visual issue",
+    "1": "Medium: degraded feature with workaround available",
+    "2": "High / Critical: database unavailable or data corruption risk"
+  },
+  "probabilities": {
+    "0": 0.01,
+    "1": 0.08,
+    "2": 0.91
+  },
+  "is_confident": true
+}
+```
+
+---
+
+## Resilience and Graceful Escalation
+
+When API errors, network timeouts, or rate limits occur, System 1 MCP maintains standard MCP connection stability and does not terminate the JSON-RPC channel. Instead, it emits a structured fallback payload:
+
+```json
+{
+  "error": true,
+  "error_type": "api_timeout",
+  "message": "TypeSafe API request timed out after 5.0s",
+  "fallback_action": "escalate"
+}
+```
+
+When receiving `fallback_action: "escalate"`, the host agent gracefully falls back to standard LLM deliberative reasoning.
+
+---
+
+## Installation and Setup
+
+### Option A: Automatic Multi-IDE Installer (Recommended)
+
+System 1 MCP includes an automated installer that detects and configures Claude Desktop, Cursor, Google Antigravity, Windsurf, Roo Code, Cline, and Zed:
+
+```bash
+# Interactive setup (prompts for API key and autodetects IDE installations)
+uvx system1-mcp install
+
+# Non-interactive setup with explicit key
+uvx system1-mcp install --api-key ts_live_your_key_here
+```
+
+### Option B: Health Check and Diagnostics (`doctor`)
+
+Inspect installation status, identify detected configuration paths, and measure live API latency:
+
+```bash
+uvx system1-mcp doctor
+```
+
+Sample output:
+```
+>> System 1 MCP Diagnostics (v0.1.0)
+
+Environment:
+  Python:        3.11.15
+  Config File:   ~/.system1/config.json (found)
+
+API Key Status:
+  Status:        [OK] Configured
+  Resolved Key:  ts_...8f2a
+  Source Origin: config_file
+
+Live TypeSafe Jev Connectivity:
+  Status:        [OK] Connected to api.typesafe.ai
+  Model:         jev-latest
+  Roundtrip:     64.2ms
+  Calibration:   P(valid) = 0.99
+
+Detected IDE Configurations:
+  Claude Desktop       [Detected     ] -> Configured [OK]
+  Cursor               [Detected     ] -> Configured [OK]
+  Google Antigravity   [Detected     ] -> Configured [OK]
+```
+
+---
+
+### Option C: Manual Configuration
+
+To manually configure an editor, add the server configuration entry:
+
+#### Claude Desktop (`claude_desktop_config.json`) / Antigravity (`mcp_config.json`) / Cursor
+```json
+{
+  "mcpServers": {
+    "system1": {
+      "command": "uvx",
+      "args": ["system1-mcp"],
+      "env": {
+        "TYPESAFE_API_KEY": "your-typesafe-api-key-here"
+      }
+    }
+  }
+}
+```
+
+> **Note**: If your key is stored in `~/.system1/config.json`, the `"env"` block is optional; the server resolves stored credentials automatically.
+
+---
+
+## Configuration Hierarchy
+
+System 1 MCP searches for credentials using the following resolution order:
+
+1. **Process Environment**: `TYPESAFE_API_KEY` (from environment or host IDE `env` map)
+2. **User Configuration**: `~/.system1/config.json` (with fallback to `~/.fastpath/config.json`)
+3. **Workspace File**: `.env` in the current working directory
+
+To configure stored user credentials via CLI:
+
+```bash
+# Store API key
+uvx system1-mcp config set-key ts_live_your_key_here
+
+# Display current configuration status
+uvx system1-mcp config show
+```
+
+---
+
+## Development and Testing
+
+```bash
+# Run unit test suite (27 offline unit tests)
+pytest tests/ -v -m "not integration"
+
+# Run integration tests against the live TypeSafe Jev API (requires TYPESAFE_API_KEY)
+pytest tests/test_integration.py -v -m integration
+```
+
+---
+
+## Architectural Comparison
+
+| Dimension | TypeSafe Agent Skill | System 1 MCP |
+|---|---|---|
+| **Role** | Instruction skill (`SKILL.md`) guiding LLMs to write TypeSafe code | Pre-packaged MCP server giving agents low-latency runtime reflexes |
+| **Agent Schema Requirement** | Requires knowledge of `Noul`, `Choice`, `Score`, and state representations | Zero schema complexity; simple tool invocations (e.g. `fast_guard`) |
+| **Target Use Case** | Generating TypeSafe application code | Real-time safety validation, option routing, and verification |
+
+---
+
+## License
+
+This project is licensed under the terms of the [MIT License](LICENSE).