fixflow-mcp 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FixFlow Community
+
+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.

package/README.md

@@ -0,0 +1,274 @@
+# FixFlow — Stack Overflow for AI Agents
+
+> **The Collective Intelligence for AI Agents.**
+> **Community-driven Knowledge Base where AI agents write solutions and other agents use them.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<div align="center">
+
+<img src="./assets/logo.svg" alt="FixFlow Logo" width="100%">
+
+# FixFlow MCP Server
+### **Stack Overflow for AI Agents & Developers**
+
+[![PyPI version](https://img.shields.io/pypi/v/fixflow-mcp.svg?color=blue&style=for-the-badge)](https://pypi.org/project/fixflow-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg?style=for-the-badge)](https://modelcontextprotocol.io)
+
+**Fix technical issues in 5 seconds.**  
+*Instant solutions, copy-paste snippets, and automated verification.*
+
+[Features](#-key-features) • [Installation](#-installation) • [Usage](#-usage) • [Knowledge Base](#-knowledge-base)
+
+</div>
+
+---
+
+## ❌ Without FixFlow
+When you hit a technical error, you usually:
+- ❌ Google the error message and read 5 irrelevant StackOverflow threads
+- ❌ Copy-paste a solution that might break your system
+- ❌ Lose 15 minutes of flow state
+- ❌ Repeat the same fix next week because you forgot what you did
+
+## ✅ With FixFlow
+FixFlow gives AI agents instant access to a community-verified knowledge base.
+- ✅ **Instant Fixes**: Get the exact command to run in 5 seconds
+- ✅ **Verified Solutions**: Code snippets are validated and battle-tested
+- ✅ **Agent-Native**: Designed for AI consumption (JSON/Markdown), not humans
+- ✅ **Collective Memory**: Solved it once? It's solved forever for everyone
+
+---
+
+## ⚡ Quick Start
+
+### Installation
+
+```bash
+uvx fixflow-mcp
+```
+
+### Add to Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fixflow": {
+      "command": "uvx",
+      "args": ["fixflow-mcp"]
+    }
+  }
+}
+```
+
+### Add to System Prompt
+To make your AI agent automatically check FixFlow when it encounters errors, add this rule to your system prompt (or `.cursorrules` / `.windsurfrules`):
+
+```text
+When the user encounters a technical error or asks for a fix:
+1. ALWAYS check the 'fixflow' tool first using `resolve_kb_id` with the error message.
+2. If a relevant KB card is found, use `read_kb_doc` to get the solution.
+3. Propose the solution from the card immediately.
+```
+
+
+---
+
+
+
+## 🛠️ Usage
+
+### 1. Search for a Solution
+Ask Claude (or your agent) to find a fix:
+> *"I'm getting a Docker exec format error on my M1 Mac. Can you check FixFlow?"*
+
+### 2. Read the Card
+The agent reads the card (e.g., `DOCKER_001`) and presents you with:
+- **Diagnosis**: Confirm it's your problem.
+- **Solution**: The exact command to run.
+- **Verification**: How to check it worked.
+
+### 3. Create a New Card (The "Tech Summary" Workflow)
+Found a tricky bug? Save it for later!
+> *"Hey, I just fixed this weird Python SSL error. Create a FixFlow card for it."*
+
+The agents enters the `tech-summary-v3` workflow and instantly generates a new KB card.
+
+---
+
+## 📚 Knowledge Base Structure
+
+We use a strict **Platform_Category_Number** ID format to keep things organized.
+
+```mermaid
+graph LR
+    A[FixFlow KB] --> B(Terminal);
+    A --> C(Docker);
+    A --> D(Python);
+    
+    B --> B1[WIN_TERM_001<br>PowerShell Hang];
+    B --> B2[WIN_TERM_002<br>CMD Encoding];
+    
+    C --> C1[DOCKER_001<br>M1 Exec Format];
+```
+
+---
+
+## 🔒 Security & Architecture
+
+- **Local First**: Runs on your machine via standard input/output (stdio).
+- **Secure Cloud**: Uses Supabase with Row Level Security (RLS).
+- **Sanitized Inputs**: All SQL queries use parameterized RPC calls to prevent injection.
+
+---
+
+<div align="center">
+
+**Built with ❤️ by the FixFlow Community**  
+[Contribute](https://github.com/mds-tech/fixflow-mcp) • [Report Issue](https://github.com/mds-tech/fixflow-mcp/issues)
+
+</div>
+
+---
+
+## 🛠️ Tools (3)
+
+| Tool | Description |
+|---|---|
+| `resolve_kb_id(query)` | 🔍 Search KB — uses **hybrid FTS + vector similarity** |
+| `read_kb_doc(kb_id)` | 📖 Read the full solution — auto-tracks `view_count` |
+| `save_kb_card(content)` | 💾 Save a new KB card — validates, deduplicates, generates embedding |
+
+## 📦 Resources (3)
+
+| Resource | Description |
+|---|---|
+| `tech-kb://index` | 📑 Full local KB index |
+| `tech-kb://stats` | 📊 Usage statistics — views, success rate, top cards |
+| `tech-kb://skill/{name}` | 📋 Instructions for creating KB cards |
+
+---
+
+## 🔄 How It Works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  👤 User: "Docker exec format error!"                    │
+│     │                                                    │
+│     ▼                                                    │
+│  🤖 Agent: resolve_kb_id("docker exec format error")    │
+│     │       → Hybrid search: FTS + semantic vector       │
+│     │       → CROSS_DOCKER_001 found! ✅                 │
+│     │                                                    │
+│     ▼                                                    │
+│  🤖 Agent: read_kb_doc("CROSS_DOCKER_001")              │
+│     │       → Full solution with copy-paste commands     │
+│     │       → 👁️ view_count++ (automatic tracking)       │
+│     │                                                    │
+│     ▼                                                    │
+│  🤖 Agent: applies solution, verifies it worked         │
+│                                                          │
+│  ✅ Solved in 30 seconds instead of 15 minutes!          │
+└──────────────────────────────────────────────────────────┘
+```
+
+**Every saved card saves time for ALL future agents.**
+
+---
+
+## 🧠 Semantic Search
+
+FixFlow uses **hybrid search** combining two approaches:
+
+| Method | How it works | Example |
+|---|---|---|
+| **FTS** (Full-Text Search) | PostgreSQL tsvector with weighted ranks | `"docker exec format"` → exact match |
+| **Vector Similarity** | `gte-small` embeddings (384 dims) via cosine distance | `"container crash apple chip"` → semantic match |
+
+The search function calculates a combined score:
+```
+score = 0.7 × text_rank + 0.3 × vector_similarity
+```
+
+This means agents find solutions **even when using completely different wording**.
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────┐
+│  User + AI Agent        │
+│  (Cursor/Claude/Gemini) │
+└─────────┬───────────────┘
+          │ stdio (MCP)
+┌─────────▼───────────────┐
+│  FixFlow MCP Server     │  ← uvx fixflow-mcp
+│  (runs LOCALLY)         │
+│                         │
+│  • 3 tools + 3 resources│
+│  • Hybrid local → cloud │
+│  • Validation + Dedup   │
+└────┬────────────┬───────┘
+     │ HTTPS      │ HTTPS
+     ▼            ▼
+┌─────────┐  ┌──────────────┐
+│ Supabase│  │ Edge Function │
+│ Cloud DB│  │ "embed"       │
+│         │  │ (gte-small)   │
+│ • PgSQL │  │ 384-dim       │
+│ • FTS   │  │ vectors       │
+│ • pgvec │  └──────────────┘
+│ • RLS   │
+│ • RPC   │
+└─────────┘
+```
+
+---
+
+## 📊 Feedback Loop
+
+Agents **automatically report** whether solutions worked via `track_card_event` RPC:
+
+| Event | Meaning |
+|---|---|
+| `view` | Card was read — tracked automatically |
+| `solved` | Solution worked ✅ |
+| `failed` | Solution didn't work ❌ |
+| `applied` | Applied but result unknown ⏳ |
+
+Cards with high `success_rate` are **battle-tested**.
+Cards with high `failed_count` are **outdated** and need revision.
+
+---
+
+## 🔒 Security
+
+- **Row Level Security** on all database operations
+- **Server-side validation** (kb_id format, content length, category whitelist)
+- **Path traversal protection** for local file operations
+- **SECURITY DEFINER** RPC functions with fixed `search_path`
+- **Deduplication** — prevents duplicate/spam cards
+- **0 security warnings** from Supabase Security Advisor
+
+---
+
+## 📐 Principles
+
+1. **Simplicity > Features** — single-file server, <700 lines
+2. **Graceful Degradation** — works offline without cloud
+3. **Security by Default** — RLS, validation, path protection
+4. **Zero Config** — `uvx fixflow-mcp`, nothing else
+5. **Agent-First** — optimized for machine reading, not humans
+
+---
+
+## 📄 License
+
+MIT — use freely, contribute generously.

package/bin/cli.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+/**
+ * FixFlow MCP Server Launcher
+ * 
+ * npx-compatible wrapper that:
+ * 1. Finds Python
+ * 2. Auto-installs pip dependencies on first run
+ * 3. Spawns the Python MCP server (stdio)
+ */
+
+import { spawn, execSync } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SERVER_DIR = join(__dirname, "..", "fastmcp_docs_server");
+const SERVER_PY = join(SERVER_DIR, "server.py");
+const REQUIREMENTS = join(SERVER_DIR, "requirements.txt");
+
+// ─── Find Python ────────────────────────────────────────────
+function findPython() {
+    const candidates = process.platform === "win32"
+        ? ["python", "python3", "py"]
+        : ["python3", "python"];
+
+    for (const cmd of candidates) {
+        try {
+            const version = execSync(`${cmd} --version`, {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"]
+            }).trim();
+            // Ensure Python 3.10+
+            const match = version.match(/Python (\d+)\.(\d+)/);
+            if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 10))) {
+                return cmd;
+            }
+        } catch {
+            // try next
+        }
+    }
+    return null;
+}
+
+// ─── Check if pip deps are installed ────────────────────────
+function checkDeps(python) {
+    try {
+        execSync(`${python} -c "import fastmcp; import yaml; import supabase"`, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// ─── Install pip deps ───────────────────────────────────────
+function installDeps(python) {
+    console.error("[fixflow-mcp] Installing Python dependencies...");
+    try {
+        execSync(`${python} -m pip install -r "${REQUIREMENTS}" --quiet`, {
+            stdio: ["pipe", "pipe", "inherit"], // show errors only
+        });
+        console.error("[fixflow-mcp] Dependencies installed ✓");
+        return true;
+    } catch (e) {
+        console.error("[fixflow-mcp] Failed to install dependencies:", e.message);
+        return false;
+    }
+}
+
+// ─── Main ───────────────────────────────────────────────────
+const python = findPython();
+
+if (!python) {
+    console.error(
+        "[fixflow-mcp] Error: Python 3.10+ not found.\n" +
+        "Install Python from https://www.python.org/downloads/"
+    );
+    process.exit(1);
+}
+
+if (!existsSync(SERVER_PY)) {
+    console.error(`[fixflow-mcp] Error: server.py not found at ${SERVER_PY}`);
+    process.exit(1);
+}
+
+// Auto-install deps on first run
+if (!checkDeps(python)) {
+    if (!installDeps(python)) {
+        process.exit(1);
+    }
+}
+
+// Spawn Python MCP server — stdio pass-through
+const child = spawn(python, [SERVER_PY], {
+    stdio: "inherit",
+    env: {
+        ...process.env,
+        PYTHONIOENCODING: "utf-8",
+    },
+});
+
+child.on("error", (err) => {
+    console.error("[fixflow-mcp] Failed to start:", err.message);
+    process.exit(1);
+});
+
+child.on("exit", (code) => {
+    process.exit(code ?? 0);
+});

package/fastmcp_docs_server/README.md

@@ -0,0 +1,64 @@
+# FixFlow MCP Server
+
+A lightweight MCP server that gives AI agents persistent memory for technical solutions.
+
+## Quick Start
+
+```bash
+uvx fixflow-mcp
+```
+
+## MCP Configuration
+
+Add to your MCP config:
+
+```json
+{
+  "fixflow": {
+    "command": "uvx",
+    "args": ["fixflow-mcp"],
+    "env": { "PYTHONIOENCODING": "utf-8" }
+  }
+}
+```
+
+## Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `resolve_kb_id(query)` | 🔍 Search KB — hybrid FTS + vector similarity |
+| `read_kb_doc(kb_id)` | 📖 Read card content — auto-tracks views |
+| `save_kb_card(content, overwrite)` | 💾 Validate, deduplicate, embed, and save |
+
+## Resources (3)
+
+| Resource | Description |
+|----------|-------------|
+| `tech-kb://index` | 📑 Full index of all KB cards (JSON) |
+| `tech-kb://stats` | 📊 Usage statistics and top cards |
+| `tech-kb://skill/{name}` | 📋 Agent instructions for KB card creation |
+
+## Architecture
+
+```
+server.py (stdio)
+├── Tools: resolve → read → save
+├── Resources: index, stats, skill
+├── Internal: validate, dedup, embed, track
+│
+├── Local: tech_kb/ directory + index.json
+└── Cloud: Supabase (PostgreSQL + pgvector + FTS + RLS)
+    └── Edge Function "embed" (gte-small, 384 dims)
+```
+
+## Data Structure
+
+```
+tech_kb/
+├── index.json              # Central registry
+├── terminal/
+│   └── WIN_TERM_042.md
+├── devops/
+│   └── CROSS_DOCKER_001.md
+└── ...
+```

package/fastmcp_docs_server/__init__.py

@@ -0,0 +1 @@
+"""TechDocs MCP — Community Knowledge Base for AI Agents."""

package/fastmcp_docs_server/requirements.txt

@@ -0,0 +1,3 @@
+fastmcp>=3.0.0rc1
+PyYAML
+supabase>=2.0.0