# CouchLoop EQ - MCP Server

Behavioral governance layer for safer, more consistent AI conversations.

<p align="center">
  <img src="https://raw.githubusercontent.com/wisenbergg/couchloop-mcp/master/assets/logo/couchloop_EQ-IconLogo.png" alt="CouchLoop EQ" width="120" />
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/couchloop-eq-mcp"><img src="https://img.shields.io/npm/v/couchloop-eq-mcp.svg" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/wisenbergg/couchloop-mcp"><img src="https://img.shields.io/github/stars/wisenbergg/couchloop-mcp?style=social" alt="GitHub stars"></a>
</p>

<p align="center">
  <a href="https://mcp.couchloop.com">🌐 Landing Page</a> •
  <a href="https://www.npmjs.com/package/couchloop-eq-mcp">📦 npm</a> •
  <a href="https://github.com/wisenbergg/couchloop-mcp">⭐ GitHub</a>
</p>

---

## 📖 Choose Your Guide

| Use Case          | Guide                                      | Description                                                              |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| 💻 **Developers** | [README-DEVELOPER.md](README-DEVELOPER.md) | Package validation, security scanning, code review, context preservation |
| 🧘 **Wellness**   | [README-WELLNESS.md](README-WELLNESS.md)   | Guided sessions, journeys, insights, reflection tools                    |

---

## What is CouchLoop EQ?

CouchLoop EQ is a behavioral governance layer for AI assistants. Built on MCP (Model Context Protocol), it monitors for hallucination, inconsistency, and unsafe reasoning patterns while managing stateful AI sessions.

## Why CouchLoop EQ?

Unlike raw LLMs that can hallucinate packages, generate insecure code, and lose context mid-conversation, CouchLoop EQ catches problems before they ship:

| Problem                      | CouchLoop EQ Solution                                                         |
| ---------------------------- | ----------------------------------------------------------------------------- |
| 🎭 **Hallucinated packages** | `review(mode: "packages")` catches fake npm/PyPI/Maven before install        |
| 🔓 **Insecure code**         | `review(mode: "code")` detects SQLi, XSS, hardcoded secrets                  |
| 📉 **Code bloat**            | `review(mode: "code")` flags over-engineering, console.logs, missing errors  |
| 🧠 **Lost context**          | `memory` stores architecture decisions and checkpoints across sessions        |
| 📚 **Deprecated APIs**       | `review(mode: "packages")` warns about outdated versions and breaking changes |
| 🔍 **Sloppy AI code**        | `review(mode: "verify")` pre-checks AI responses for hallucinated APIs       |
| 🧠 **Session continuity**    | `conversation` with crisis detection, journeys, and session memory            |

## Architecture

CouchLoop EQ uses a modular pipeline:

```
Request -> Classify -> Policy -> Plan -> Execute -> Compose
```

- **Intent Classifier**: Confidence-based routing with multi-intent detection
- **Policy Engine**: Health-aware routing with fallbacks and crisis override
- **Execution Planner**: DAG generation for parallel operations
- **Tool Registry**: Health tracking and circuit breakers
- **OpenTelemetry**: Distributed tracing across all stages

## Key Safety Features

### Behavioral Governance

- **Hallucination Detection**: Monitors for fabricated facts and unsupported claims
- **Consistency Checking**: Identifies contradictions and logical incoherence across turns
- **Tone Monitoring**: Detects emotional escalation, manipulation, or dependency-forming language
- **Safety Guardrails**: Prevents harmful advice, clinical overreach, and inappropriate moralizing

### Session Management

- **Stateful Conversations**: Maintains context across multiple interactions
- **Progress Tracking**: Remember where users left off in guided journeys
- **Crisis Detection**: Integrated crisis detection with guided self-reflection journeys
- **Memory Context**: Preserves important insights and checkpoints

### Privacy by Design

- **No personal data stored**: No emails, names, passwords, or API keys
- **Session-based isolation**: Each session is anonymous and isolated
- **Your data stays yours**: Insights and context are tied to session IDs, not identities
- **No tracking**: No analytics, no telemetry, no third-party data sharing

## Quick Start

CouchLoop EQ is a standard MCP server that works with **any MCP-compatible client** - Claude Desktop, ChatGPT, Cursor, Windsurf, VS Code, and more.

### Option 1: Connect to Hosted Server (Easiest)

**Production endpoint:** `https://mcp.couchloop.com/mcp`

For Claude Desktop (v0.7.0+), add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "couchloop-eq": {
      "url": "https://mcp.couchloop.com/mcp",
      "transport": "streamable-http"
    }
  }
}
```

Restart Claude and try: **"Start a daily reflection session"**

### Option 2: Run Locally

```bash
npm install -g couchloop-eq-mcp
```

Add to Claude Desktop configuration:

```json
{
  "mcpServers": {
    "couchloop-eq": {
      "command": "couchloop-eq-mcp",
      "env": {
        "COUCHLOOP_SERVER": "https://mcp.couchloop.com"
      }
    }
  }
}
```

Sessions automatically persist locally to `~/.couchloop-mcp/identity.json` - no signup required.

### For ChatGPT (Developer Mode)

ChatGPT supports MCP servers through Developer Mode. See [CHATGPT_SETUP.md](CHATGPT_SETUP.md) for detailed setup instructions.

### For Other MCP Clients

Any MCP-compatible client (Cursor, Windsurf, Continue, etc.) can connect using:

- **URL:** `https://mcp.couchloop.com/mcp`
- **Transport:** `streamable-http`
- **Auth:** Optional — anonymous by default, OAuth available for persistent identity. See [Authentication](#authentication).

**Production Server Available:** `https://mcp.couchloop.com/mcp`

Quick steps:

1. Enable Developer Mode in ChatGPT Settings
2. Add as MCP connector with URL: `https://mcp.couchloop.com/mcp`
3. No authentication required to start - uses session-based isolation

For local development:

- Use ngrok or deploy your own server
- Follow setup in [CHATGPT_SETUP.md](CHATGPT_SETUP.md)

## Authentication

Connecting works with no signup, no API key, and no login screen. Auth is layered on top of that default, not required to use it:

| Mode                    | What you get                                                                                     | How                                                                 |
| ----------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Anonymous (default)** | Session-based isolation. Each session gets its own context; no identity is collected.              | Just connect — nothing to configure.                                 |
| **OAuth 2.1**            | A persistent identity across reconnects and devices, tied to a Bearer token instead of a session ID. | The server exposes dynamic client registration, `/oauth/authorize`, `/oauth/token`, `/oauth/revoke`, and `/.well-known/oauth-authorization-server` metadata. MCP clients that support OAuth (e.g. Claude Desktop) discover and complete this automatically on connect. |
| **SSO (optional)**       | The same persistent identity as OAuth, backed by a Google or GitHub sign-in instead of a bare client credential — useful for linking work across devices you don't control. | Behind the `FF_SSO_SUPABASE` flag: the consent screen shows "Sign in with Google/GitHub" buttons, backed by Supabase Auth.           |

Identity is stored as a hashed subject, not a raw email or name — signing in with Google or GitHub shares your profile with that provider per its own policy, but CouchLoop EQ only persists a keyed hash plus an internal user ID, consistent with the [Privacy by Design](#privacy-by-design) principles above.

If a client doesn't send a Bearer token, requests fall through to anonymous session-based isolation automatically — nothing breaks, you just don't get identity continuity across reconnects.

## Available Tools (4)

CouchLoop EQ is consolidated to 4 public tools. There is no router tool in front of them — each tool's name and description are specific enough that MCP clients route directly, which cuts a hop of latency and removes a second place routing can go wrong.

| Tool           | Description                                                                                                                                                    |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memory`       | **Hero tool** - Save and recall context, insights, checkpoints, and decisions across sessions (Supabase-backed). Actions: `save`, `recall`, `list`             |
| `conversation` | Guided self-reflection, burnout check-ins, and wellness conversations with crisis detection, plus local developer journeys (standup, retro, postmortem). Actions: `send`, `start`, `end`, `resume`, `status` |
| `review`       | Unified code review, package audit, and pre-delivery verification. Modes: `code`, `packages`, `verify`, `confirm`, `apply-fix`, `dismiss`, `full`              |
| `status`       | **Dashboard** - Session progress, history, context window usage, protection status, preferences                                                                |

`guard` is an internal governance tool that auto-runs on every response — it is not user-facing and does not need to be called directly.

### Usage Examples

```
memory(action: "save", type: "insight", content: "...")   # Save context
memory(action: "recall", content: "auth flow")             # Retrieve saved context
memory(action: "list")                                     # Browse everything saved

conversation(action: "start", message: "Begin daily reflection")
conversation(action: "send", message: "...")

review(mode: "code", content: "function foo() {...}")      # Security/quality analysis
review(mode: "packages", packages: ["lodash-utils"])        # Validate before install
review(mode: "verify", content: "...")                      # Hallucination/fact check

status(section: "session")                                  # Quick dashboard summary
```

## Real-World Usage

CouchLoop EQ is actively used in production development. Here is what 2 weeks of actual usage looked like:

### Usage Statistics

| Metric            | Value                |
| ----------------- | -------------------- |
| Insights captured | 49                   |
| Active sessions   | 5                    |
| Unique tags       | 85+                  |
| Date range        | Jan 19 - Feb 2, 2026 |

### Development Areas Tracked

| Category                  | Insights | Example                                      |
| ------------------------- | -------- | -------------------------------------------- |
| 🔐 Security fixes         | 12       | Auth flow hardening, validation improvements |
| 💳 Payment integration    | 8        | Payment flow patterns, webhook handling      |
| 📱 Mobile development     | 15       | State management, navigation guards          |
| 🗄️ Database operations    | 6        | Data cleanup, schema optimization            |
| 🏗️ Architecture decisions | 8        | Caching strategies, event patterns           |

### Featured Insight: Complex Bug Resolution

```
PAYMENT FLOW BUG ROOT CAUSE IDENTIFIED:

Issue: Race condition between frontend state and backend data caused
inconsistent user experience during payment retry flows.

Analysis: Traced through 5 components across iOS and backend to find
the state synchronization gap.

FIX OPTIONS:
A) Data cleanup - reset stale records
B) Frontend fix - stricter validation
C) Backend fix - additional verification step

Recommended: Defense-in-depth approach combining A + B
```

This insight was captured mid-debugging session, preserved across context window resets, and referenced 3 days later when implementing the fix.

### Best Practices for Sprint Development

**Start of sprint:** Create a session to establish context

```
"Create a session for Sprint 42 - user authentication overhaul"
```

**After completing a feature:** Save insights, context, or checkpoints depending on complexity

| Feature Size          | Recommended Actions                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------- |
| **Small fix**         | `memory(action: "save")` with type `insight` — Quick note of what was done and why              |
| **Medium feature**    | `memory(action: "save")` with type `insight` + `checkpoint` — Capture decisions and state      |
| **Large feature set** | Multiple `memory` saves (insight, checkpoint, decision) — Full architecture context            |

**Why this matters:** When you need to review or debug later, you can retrieve the exact context of what was just built - even weeks later, across different AI sessions.

```
memory(action: "recall") -> Instant recall of decisions made
"Resume my Sprint 42 session" -> Pick up exactly where you left off
```

## Available Journeys

- **Daily Reflection** (5 min) - A brief check-in to process your day
- **Gratitude Practice** (3 min) - Notice and name three things you appreciate
- **Weekly Review** (10 min) - Look back on your week and set intentions

## Example Usage

Start a daily reflection:

```
"Start a daily reflection session"
```

Resume where you left off:

```
"Resume my last session"
```

Save an insight:

```
"Save this insight: I notice I'm more energized in the mornings"
```

## Screenshots

<p align="center">
  <img src="assets/screenshots/save_insights.png" alt="Save Insights" width="400" />
  <img src="assets/screenshots/checkpoint_session.png" alt="Checkpoint Session" width="400" />
  <img src="assets/screenshots/code_review_workflow.png" alt="Code Review Workflow" width="400" />
</p>

## Support

- Issues: [github.com/wisenbergg/couchloop-mcp/issues](https://github.com/wisenbergg/couchloop-mcp/issues)
- Email: support@couchloop.com

## License

MIT