libb-cognitive-clarity 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# Libb Cognitive Clarity — MCP Server
+
+Score any message through 15 clinical cognitive assessment gates before it reaches a human.
+
+Built on clinical speech-language pathology research, Libb measures whether a message is **cognitively processable** — not just grammatically correct, but actually understandable by the person reading it.
+
+## What it does
+
+| Tool | Description |
+|------|-------------|
+| `analyze_message` | Full 15-gate analysis with CPS score, gate-by-gate breakdown, specific issues with fixes, and a cognitively accessible rewrite |
+| `quick_check` | Fast pass/flag screening — CPS score and flagged gates only |
+
+**Use it before sending:** emails, Slack messages, HR communications, medical instructions, educational materials, or any text where clarity matters.
+
+## Why it matters
+
+- **HB 3773** (Illinois) and **SB 24-205** (Colorado) create legal liability for AI-generated communications that discriminate through cognitive inaccessibility
+- **1 in 5 adults** has a disability that affects how they process written communication
+- Grammar checkers ask "Is this correct?" — Libb asks **"Will this message land?"**
+
+## Quick start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "libb": {
+      "command": "npx",
+      "args": ["-y", "libb-cognitive-clarity"],
+      "env": {
+        "LIBB_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio libb -- npx -y libb-cognitive-clarity
+```
+
+### Windows (Claude Desktop)
+
+```json
+{
+  "mcpServers": {
+    "libb": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "libb-cognitive-clarity"],
+      "env": {
+        "LIBB_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / other MCP clients
+
+Add to your MCP configuration:
+
+```json
+{
+  "libb": {
+    "command": "npx",
+    "args": ["-y", "libb-cognitive-clarity"],
+    "env": {
+      "LIBB_API_KEY": "your-api-key"
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `LIBB_API_KEY` | Yes | API key for analysis (get one at https://libb.ai) |
+| `LIBB_API_URL` | No | Override API endpoint (default: `https://api.libb.ai`) |
+
+## Example usage
+
+Once connected, ask your AI assistant:
+
+> "Check this email before I send it: [paste message]"
+
+> "Run a cognitive clarity analysis on this Slack message"
+
+> "Is this HR communication cognitively accessible?"
+
+> "Analyze this message for cognitive friction — it's going to employees"
+
+The assistant will call the `analyze_message` tool and return a full breakdown with specific issues and fixes.
+
+## What the analysis covers
+
+The 15-gate assessment checks for:
+
+- **Ambiguity & Referents** — unclear pronouns, vague references
+- **Unstated Assumptions** — missing context the reader needs
+- **Time & Deadlines** — vague or missing temporal information
+- **Hedge Words** — language that avoids commitment
+- **Information Volume** — cognitive overload
+- **External Dependencies** — unexplained references
+- **Repair Paths** — whether the reader can ask for clarification
+- **Emotional Processing Cost** — emotional labor required
+- **Sentence Complexity** — syntactic demands
+- **Structure & Organization** — scaffolding for working memory
+- **Decision Architecture** — clarity of choices presented
+- **Specialized Vocabulary** — jargon and domain terms
+- **Pacing & Recovery** — breathing room between concepts
+- **Sender–Reader Frame Gap** — assumptions about shared context
+- **AI Optimization Patterns** — machine-generated artifacts
+
+## Compliance
+
+Libb supports audit readiness for:
+
+- **Illinois HB 3773** — AI employment discrimination (effective Jan 1, 2026)
+- **Colorado SB 24-205** — algorithmic discrimination (effective Jun 30, 2026)
+- **EU AI Act** — high-risk AI employment provisions (effective Aug 2, 2026)
+
+## Privacy
+
+- Your message text is sent to `api.libb.ai` for analysis and is **not stored**
+- Anonymous telemetry (gate pass/flag counts, no message content) helps improve the service
+- No user data is shared with third parties
+
+## Links
+
+- **Website:** https://libb.ai
+- **Enterprise & API access:** hello@libb.ai
+- **OpenClaw skill:** `clawhub install cognitive-clarity`
+
+## License
+
+MIT — the server code is open. The scoring methodology is patent-pending.

package/build/index.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Libb Cognitive Clarity — MCP Server
+ *
+ * Scores any message through 15 clinical assessment gates for cognitive
+ * accessibility before it reaches a human. Powered by api.libb.ai.
+ *
+ * Tools:
+ *   analyze_message  — Full 15-gate Cognitive Processability analysis
+ *   quick_check      — Fast pass/flag check (lighter weight, no findings)
+ *
+ * Environment:
+ *   LIBB_API_KEY  — API key for authenticated analysis (required for custom text)
+ *   LIBB_API_URL  — Override API base URL (default: https://api.libb.ai)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const API_BASE = process.env.LIBB_API_URL || "https://api.libb.ai";
+const API_KEY = process.env.LIBB_API_KEY || "";
+async function parseSSEStream(response) {
+    const result = {
+        cps: 0,
+        signal: "unknown",
+        gate_scores: [],
+        violations: [],
+        summary: "",
+        rewrite: "",
+        veto: null,
+        cascades: [],
+    };
+    const text = await response.text();
+    const blocks = text.split("\n\n").filter(Boolean);
+    for (const block of blocks) {
+        const lines = block.split("\n");
+        let eventType = "";
+        let data = "";
+        for (const line of lines) {
+            if (line.startsWith("event: "))
+                eventType = line.slice(7).trim();
+            if (line.startsWith("data: "))
+                data = line.slice(6);
+        }
+        if (!data || !eventType)
+            continue;
+        try {
+            const parsed = JSON.parse(data);
+            switch (eventType) {
+                case "scores":
+                    result.cps = parsed.cps ?? 0;
+                    result.signal = parsed.signal ?? "unknown";
+                    result.gate_scores = parsed.gate_scores ?? [];
+                    result.veto = parsed.veto ?? null;
+                    result.cascades = parsed.cascades ?? [];
+                    break;
+                case "findings":
+                    result.violations = parsed.violations ?? [];
+                    result.summary = parsed.summary ?? "";
+                    result.rewrite = parsed.rewrite ?? "";
+                    break;
+                case "done":
+                    break;
+            }
+        }
+        catch {
+            // Skip unparseable events
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Format results as readable text for the LLM
+// ---------------------------------------------------------------------------
+const GATE_LABELS = {
+    1: "Ambiguity & Referents",
+    2: "Unstated Assumptions",
+    3: "Time & Deadlines",
+    4: "Hedge Words & Hedging",
+    5: "Information Volume",
+    6: "External Dependencies",
+    7: "Repair & Clarification Paths",
+    8: "Emotional Processing Cost",
+    9: "Sentence Complexity",
+    10: "Structure & Organization",
+    11: "Decision Architecture",
+    12: "Specialized Vocabulary",
+    13: "Pacing & Recovery",
+    14: "Sender–Reader Frame Gap",
+    15: "AI Optimization Patterns",
+};
+function signalEmoji(signal) {
+    switch (signal) {
+        case "green": return "🟢";
+        case "amber": return "🟡";
+        case "red": return "🔴";
+        default: return "⚪";
+    }
+}
+function formatFullResult(result) {
+    const lines = [];
+    // Header
+    lines.push(`${signalEmoji(result.signal)} Cognitive Processability Score: ${result.cps.toFixed(1)} / 5.0`);
+    lines.push("");
+    // Summary
+    if (result.summary) {
+        lines.push(result.summary);
+        lines.push("");
+    }
+    // Veto
+    if (result.veto) {
+        lines.push("⛔ VETO: Message held — governance threshold triggered.");
+        lines.push("");
+    }
+    // Cascades
+    if (result.cascades && result.cascades.length > 0) {
+        lines.push(`⚠️ ${result.cascades.length} compound pattern(s) detected — multiple issues interact and amplify friction.`);
+        lines.push("");
+    }
+    // Gate scores
+    lines.push("── Gate Scores ──");
+    for (const g of result.gate_scores) {
+        const label = GATE_LABELS[g.gate_id] || "";
+        const bar = g.score >= 4 ? "🔴" : g.score >= 2.5 ? "🟡" : "🟢";
+        lines.push(`  ${bar} Gate ${String(g.gate_id).padStart(2, "0")} ${label.padEnd(28)} ${g.score.toFixed(1)}`);
+    }
+    lines.push("");
+    // Violations
+    if (result.violations.length > 0) {
+        lines.push(`── What to Fix (${result.violations.length}) ──`);
+        for (const v of result.violations) {
+            const label = GATE_LABELS[v.gate_id] || v.gate_name;
+            lines.push(`  [${v.severity.toUpperCase()}] ${label}`);
+            if (v.original_quote)
+                lines.push(`    Original: "${v.original_quote}"`);
+            if (v.analysis)
+                lines.push(`    Issue: ${v.analysis}`);
+            if (v.fix)
+                lines.push(`    Fix: ${v.fix}`);
+            lines.push("");
+        }
+    }
+    // Rewrite
+    if (result.rewrite) {
+        lines.push("── Suggested Rewrite ──");
+        lines.push(result.rewrite);
+        lines.push("");
+    }
+    lines.push("Powered by Libb — https://libb.ai");
+    return lines.join("\n");
+}
+function formatQuickResult(result) {
+    const lines = [];
+    lines.push(`${signalEmoji(result.signal)} CPS: ${result.cps.toFixed(1)} / 5.0`);
+    if (result.veto) {
+        lines.push("⛔ VETO — governance threshold triggered");
+    }
+    const flagged = result.gate_scores.filter((g) => g.score >= 2.5);
+    if (flagged.length > 0) {
+        lines.push(`${flagged.length} gate(s) flagged:`);
+        for (const g of flagged) {
+            const label = GATE_LABELS[g.gate_id] || "";
+            lines.push(`  ${g.score >= 4 ? "🔴" : "🟡"} Gate ${g.gate_id} ${label}: ${g.score.toFixed(1)}`);
+        }
+    }
+    else {
+        lines.push("All gates passing. Message is cognitively accessible.");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// API call
+// ---------------------------------------------------------------------------
+async function callAnalyze(text, mode) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+    };
+    if (API_KEY) {
+        headers["X-Libb-Key"] = API_KEY;
+    }
+    const res = await fetch(`${API_BASE}/api/analyze`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ text, mode }),
+    });
+    if (!res.ok) {
+        const errText = await res.text().catch(() => "Unknown error");
+        throw new Error(`Libb API returned ${res.status}: ${errText}`);
+    }
+    return parseSSEStream(res);
+}
+// ---------------------------------------------------------------------------
+// Telemetry ping — anonymous, no user text
+// ---------------------------------------------------------------------------
+async function sendPing(result) {
+    try {
+        const gateResults = {};
+        for (const g of result.gate_scores) {
+            gateResults[`gate_${g.gate_id}`] = g.score >= 2.5 ? "flag" : "pass";
+        }
+        await fetch(`${API_BASE}/v1/ping`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                event: "mcp_analysis",
+                gate_results: gateResults,
+                source: "mcp-server",
+                cps: result.cps,
+            }),
+        });
+    }
+    catch {
+        // Telemetry failure is silent — never blocks analysis
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "libb-cognitive-clarity",
+    version: "1.0.0",
+});
+// Tool 1: Full analysis
+server.tool("analyze_message", "Score a message through 15 clinical cognitive assessment gates. Returns a Cognitive Processability Score (CPS), gate-by-gate breakdown, specific issues found with fixes, and a cognitively accessible rewrite. Use this before sending important emails, Slack messages, HR communications, or any text where clarity matters.", {
+    text: z.string().min(1).describe("The message text to analyze"),
+    mode: z
+        .enum([
+        "email_professional",
+        "email_casual",
+        "slack_message",
+        "hr_communication",
+        "medical_communication",
+        "educational",
+        "general",
+    ])
+        .optional()
+        .default("general")
+        .describe("Communication context — helps calibrate the analysis"),
+}, async ({ text, mode }) => {
+    try {
+        const result = await callAnalyze(text, mode || "general");
+        sendPing(result); // fire and forget
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatFullResult(result),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Analysis failed: ${err.message}. Ensure LIBB_API_KEY is set or check your connection to ${API_BASE}.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool 2: Quick check (scores only, no findings)
+server.tool("quick_check", "Fast cognitive accessibility check — returns the CPS score and any flagged gates without detailed findings or rewrite. Good for quick screening of messages before deciding whether to run the full analysis.", {
+    text: z.string().min(1).describe("The message text to check"),
+}, async ({ text }) => {
+    try {
+        const result = await callAnalyze(text, "general");
+        sendPing(result);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatQuickResult(result),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Quick check failed: ${err.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Connect via stdio
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "libb-cognitive-clarity",
+  "version": "1.0.0",
+  "description": "MCP server for cognitive accessibility analysis — score any message through 15 clinical assessment gates before it reaches a human",
+  "type": "module",
+  "bin": {
+    "libb-cognitive-clarity": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector node build/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "cognitive-accessibility",
+    "ai-governance",
+    "communication-quality",
+    "neurodivergent",
+    "plain-language",
+    "cognitive-load",
+    "hb-3773",
+    "ai-compliance"
+  ],
+  "author": "Cognitive Velocity Consulting <hello@libb.ai> (https://libb.ai)",
+  "license": "MIT",
+  "homepage": "https://libb.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cognitivevelocity/libb-mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  }
+}