fixflow-mcp 1.0.0

package/fastmcp_docs_server/skills/creating-kb-cards.md

@@ -0,0 +1,146 @@
+---
+name: creating-kb-cards
+description: Generates concise, actionable Knowledge Base (KB) cards for technical problem-solving. Use when documenting bug fixes, solutions, or creating new technical summaries.
+---
+
+# Creating Actionable KB Cards
+
+## When to use this skill
+- **ALWAYS Proactively**: Immediately after successfully solving a technical issue (debugging, config fix, or complex implementation), you MUST use this skill to preserve the solution. Do not wait for the user to ask.
+- **Proactive Threshold**: If the solution involved non-obvious steps, specific commands, or took >2 turns to resolve, assume it remains valuable and needs documentation.
+- **Explicit Triggers**: When the user asks to "document this", "save fix", "create KB", or uses `/tech-summary`.
+
+## Workflow
+
+1.  **Analyze Context**: Extract the problem category, platform, symptoms, diagnostic steps, and the solution from the conversation.
+2.  **Generate Metadata**: Determine a unique `KB_ID` (format: `PLATFORM_CATEGORY_NUMBER`), criticality, and complexity.
+3.  **Draft Content**: Create the Markdown content following the *Strict Priority Order* (Diagnosis -> Solution -> Verification).
+4.  **Save & Validate (Server-Side)**: Call the `save_kb_card` MCP tool. This tool will automatically validate the content and save it to the correct location if valid.
+5.  **Update Index**: The `save_kb_card` tool automatically updates the index. No manual action required.
+
+## Instructions
+
+### 1. KB_ID Generation Rule
+Format: `[PLATFORM]_[CATEGORY]_[NUMBER]`
+- **Examples**: `WIN_TERM_001`, `CROSS_PROXY_012`
+- **Number**: Increment the max ID found in the category.
+
+### 2. Save & Validation (Server-Side)
+You MUST use the `save_kb_card` MCP tool.
+- **Tool**: `save_kb_card`
+- **Input**: The full markdown string.
+- **Process**: The server validates the content and saves the file.
+- **Success**: Returns a success message with the file path.
+- **Fail**: Returns an error message. Fix and retry.
+**DO NOT use manual file writing tools.**
+
+### 3. Content Structure (Strict Priority)
+
+Your output MD file MUST follow this structure:
+
+1.  **Frontmatter**:
+    - `kb_id`, `category`, `platform`, `technologies` (list), `complexity` (1-10), `criticality` (low/medium/high/critical), `created` (YYYY-MM-DD), `tags`, `related_kb`.
+2.  **Title & TL;DR**:
+    - Short, descriptive title (max 5 words).
+    - "TL;DR" block with Fix Time and Platform.
+3.  **🔍 This Is Your Problem If**:
+    - 3 specific symptoms (checkboxes).
+    - "Where to Check" line.
+4.  **✅ SOLUTION (copy-paste)**:
+    - **Integration Pattern**: Explicitly state where to put the code (Global/Init/Event).
+    - **Code**: Depersonalized, using `__VAR__` for placeholders.
+    - **Drop-in Component** (if applicable): Self-contained class/fn.
+    - **Self-Test**: Runtime check snippet.
+    - **Critical Points**: What breaks if missing.
+5.  **✔️ Verification**:
+    - Single command (<30 sec execution).
+    - Expected output.
+6.  **🔄 Fallback**:
+    - 1-2 alternative options if the main solution fails.
+7.  **💡 Context**:
+    - Root cause (optional, at the end).
+
+### 4. "Actionable" Rules
+- **Solution FIRST**: Code comes immediately after diagnosis.
+- **Depersonalization**: No specific paths or user names. Use `__VAR__` if needed.
+- **Black Box**: Prefer self-contained wrappers over snippets.
+- **Verification**: MUST have a verification command.
+- **Fix Time**: Estimate realistic fix time (e.g., "5min").
+
+### 5. MCP Server Installation
+If access to the MCP server is available:
+- **Requirement**: You MUST use the server to install the KB card.
+- **Action**: Use `save_kb_card`.
+
+## Template
+
+```markdown
+---
+kb_id: "WIN_TERM_042"
+category: "terminal"
+platform: "windows"
+technologies: [powershell, cmd]
+complexity: 7
+criticality: "high"
+created: "2026-02-11"
+tags: [windows, hang, async]
+related_kb: []
+---
+
+# [Title]
+
+> **TL;DR**: [Problem] → [Solution]
+> **Fix Time**: ~5 min | **Platform**: Windows
+
+---
+
+## 🔍 This Is Your Problem If:
+
+- [ ] [Symptom 1]
+- [ ] [Symptom 2]
+
+**Where to Check**: [Logs/Console]
+
+---
+
+## ✅ SOLUTION (copy-paste)
+
+### 🎯 Integration Pattern: [Global/Init/Event]
+
+```bash
+[Command or Code]
+```
+
+### ⚡ Critical:
+- ✓ **[Point 1]**
+- ✓ **[Point 2]**
+
+---
+
+## ✔️ Verification (<30 sec)
+
+```bash
+[Verification Command]
+```
+
+**Expected**: [Output]
+
+---
+
+## 🔄 Fallback
+
+### Option 1: [Alternative]
+```bash
+[Command]
+```
+
+---
+
+## 💡 Context
+**Root Cause**: [Brief explanation]
+```
+
+## Resources
+
+- **Server-Side Tool**: `save_kb_card` (Handles validation, saving, and indexing)
+- **Categories**: terminal, security, database, network, storage, devops, frontend, specialized.

package/fastmcp_docs_server/tech_kb/devops/CROSS_DOCKER_001.md

@@ -0,0 +1,104 @@
+---
+kb_id: "CROSS_DOCKER_001"
+category: "devops"
+platform: "cross-platform"
+technologies: [docker, buildx, multi-arch]
+complexity: 4
+criticality: "high"
+created: "2026-02-17"
+tags: [docker, exec-format-error, arm64, amd64, multi-arch, buildx]
+related_kb: []
+---
+
+# Docker exec format error — Wrong Architecture
+
+> **TL;DR**: Container fails with `exec format error` → rebuild image with correct `--platform`
+> **Fix Time**: ~5 min | **Platform**: Any OS (common on Apple Silicon M1/M2/M3)
+
+---
+
+## 🔍 This Is Your Problem If:
+
+- [ ] Container exits immediately after `docker run`
+- [ ] Error log contains `exec /usr/bin/... : exec format error`
+- [ ] You built image on Mac M1/M2 and deploying to Linux x86_64 (or vice versa)
+- [ ] Image pulled from registry shows wrong architecture
+
+**Where to Check**: `docker logs <container>`, `docker inspect --format='{{.Architecture}}' <image>`
+
+---
+
+## ✅ SOLUTION (copy-paste)
+
+### 🎯 Integration Pattern: [Build Phase — Dockerfile]
+
+```bash
+# Option A: Build for specific platform
+docker build --platform linux/amd64 -t __IMAGE_NAME__ .  # 🖍️ VAR
+
+# Option B: Build multi-arch with buildx (recommended)
+docker buildx create --use
+docker buildx build --platform linux/amd64,linux/arm64 -t __IMAGE_NAME__ --push .  # 🖍️ VAR
+```
+
+### ⚡ Critical (won't work without this):
+- ✓ **`--platform` flag** — explicitly specify target architecture
+- ✓ **buildx** — must be installed (`docker buildx version`)
+- ✓ **For existing images** — re-pull with `docker pull --platform linux/amd64 image:tag`
+
+### 📌 Versions:
+- **Works**: Docker 20.10+, Docker Desktop 4.x
+- **buildx required for**: multi-arch builds
+
+---
+
+## ✔️ Verification (<30 sec)
+
+```bash
+# Check image architecture
+docker inspect __IMAGE_NAME__ | grep Architecture  # 🖍️ VAR
+
+# Test run
+docker run --rm __IMAGE_NAME__ echo "Architecture OK"  # 🖍️ VAR
+```
+
+**Expected**:
+✓ Architecture shows `amd64` (or your target)
+✓ Container prints "Architecture OK" and exits cleanly
+
+**If it didn't work** → see Fallback below ⤵
+
+---
+
+## 🔄 Fallback (if main solution failed)
+
+### Option 1: Use QEMU emulation
+```bash
+docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
+docker run --platform linux/amd64 __IMAGE_NAME__  # 🖍️ VAR
+```
+**When**: Can't rebuild image, need quick workaround | **Risks**: 5-10x slower performance
+
+### Option 2: Find native image
+```bash
+# Search for arm64 variant of the image
+docker manifest inspect __IMAGE_NAME__  # 🖍️ VAR
+```
+**When**: Image maintainer provides multi-arch support
+
+---
+
+## 💡 Context (optional)
+
+**Root Cause**: Docker images contain binaries compiled for a specific CPU architecture. Running an amd64 binary on arm64 (or vice versa) causes the kernel to reject the executable format.
+
+**Side Effects**: Multi-arch builds take longer, image size may increase
+
+**Best Practice**: Always specify `--platform` in CI/CD pipelines and Dockerfiles (`FROM --platform=linux/amd64 node:20`)
+
+**Anti-Pattern**: ✗ Using QEMU emulation in production (severe performance penalty)
+
+---
+
+**Applicable**: Docker 20.10+, Apple Silicon Macs, CI/CD cross-compilation
+**Frequency**: Very common since Apple M1 release (2020)

package/fastmcp_docs_server/tech_kb/devops/CROSS_GIT_001.md

@@ -0,0 +1,70 @@
+---
+kb_id: "CROSS_GIT_001"
+category: "devops"
+platform: "cross-platform"
+technologies: [git, github]
+complexity: 3
+criticality: "medium"
+created: "2026-02-17"
+tags: [git, merge, conflict, resolve]
+related_kb: []
+---
+
+# Git Merge Conflict Resolution
+
+> **TL;DR**: Merge conflict in pull request → use rebase + manual resolve
+> **Fix Time**: ~10 min | **Platform**: Any OS
+
+---
+
+## 🔍 This Is Your Problem If:
+
+- [ ] `git pull` shows CONFLICT markers
+- [ ] PR cannot be merged automatically
+- [ ] Files contain `<<<<<<<` markers
+
+**Where to Check**: terminal output, GitHub/GitLab PR page
+
+---
+
+## ✅ SOLUTION (copy-paste)
+
+### 🎯 Integration Pattern: [Event — on merge conflict]
+
+```bash
+git fetch origin
+git rebase origin/main
+git add __CONFLICTED_FILE__
+git rebase --continue
+git push --force-with-lease
+```
+
+### ⚡ Critical:
+- ✓ **`--force-with-lease`** — safer than `--force`
+- ✓ **Remove ALL conflict markers**
+- ✓ **Test after resolve**
+
+---
+
+## ✔️ Verification (<30 sec)
+
+```bash
+git log --oneline -5
+git diff --check
+```
+
+**Expected**: Clean log, no conflict markers
+
+---
+
+## 🔄 Fallback
+
+### Option 1: Merge instead of rebase
+```bash
+git merge origin/main
+```
+
+---
+
+## 💡 Context
+**Root Cause**: Divergent changes to same file lines on different branches

package/fastmcp_docs_server/tech_kb/index.json

@@ -0,0 +1,78 @@
+[
+    {
+        "kb_id": "WIN_TERM_042",
+        "title": "PowerShell Async Hang",
+        "category": "terminal",
+        "platform": "windows",
+        "technologies": [
+            "powershell",
+            "cmd"
+        ],
+        "complexity": 7,
+        "criticality": "high",
+        "created": "2026-02-11",
+        "tags": [
+            "windows",
+            "hang",
+            "async",
+            "utf8"
+        ],
+        "related_kb": [
+            "WIN_ENC_001"
+        ],
+        "file_path": "terminal/WIN_TERM_042.md",
+        "quick_summary": "PowerShell 7 async hang → use CMD with WaitMs = 0",
+        "quick_fix": "cmd /c \"chcp 65001 > nul && command\"",
+        "diagnostic_time": "5sec",
+        "fix_time": "5min"
+    },
+    {
+        "kb_id": "CROSS_GIT_001",
+        "title": "Git Merge Conflict Resolution",
+        "category": "devops",
+        "platform": "cross-platform",
+        "technologies": [
+            "git",
+            "github"
+        ],
+        "complexity": 3,
+        "criticality": "medium",
+        "created": "2026-02-17",
+        "tags": [
+            "git",
+            "merge",
+            "conflict",
+            "resolve"
+        ],
+        "related_kb": [],
+        "file_path": "devops/CROSS_GIT_001.md",
+        "quick_summary": "Merge conflict in pull request → use rebase + manual resolve",
+        "fix_time": "~10 min"
+    },
+    {
+        "kb_id": "CROSS_DOCKER_001",
+        "title": "Docker exec format error — Wrong Architecture",
+        "category": "devops",
+        "platform": "cross-platform",
+        "technologies": [
+            "docker",
+            "buildx",
+            "multi-arch"
+        ],
+        "complexity": 4,
+        "criticality": "high",
+        "created": "2026-02-17",
+        "tags": [
+            "docker",
+            "exec-format-error",
+            "arm64",
+            "amd64",
+            "multi-arch",
+            "buildx"
+        ],
+        "related_kb": [],
+        "file_path": "devops/CROSS_DOCKER_001.md",
+        "quick_summary": "Container fails with `exec format error` → rebuild image with correct `--platform`",
+        "fix_time": "~5 min"
+    }
+]

package/fastmcp_docs_server/tech_kb/terminal/WIN_TERM_042.md

@@ -0,0 +1,93 @@
+---
+kb_id: "WIN_TERM_042"
+category: "terminal"
+platform: "windows"
+technologies: [powershell, cmd, async]
+complexity: 7
+criticality: "high"
+created: "2026-02-11"
+tags: [windows, hang, async, utf8, powershell7]
+related_kb: [WIN_ENC_001, WIN_PROXY_003]
+---
+
+# PowerShell Async Hang
+
+> **TL;DR**: PowerShell 7 hangs on async stdin → use CMD
+> **Fix Time**: ~5 min | **Platform**: Windows 10/11
+
+---
+
+## 🔍 This Is Your Problem If:
+
+- [ ] Agent command hangs >10 seconds
+- [ ] PowerShell 7.4+ installed
+- [ ] WaitMsBeforeAsync > 0 used
+
+**Where to Check**: console, agent logs, Task Manager (powershell.exe hanging)
+
+---
+
+## ✅ SOLUTION (copy-paste)
+
+### 🎯 Integration Pattern: [Global Scope]
+
+```cmd
+# CMD wrapper to bypass PowerShell 7 bug
+cmd /c "chcp 65001 > nul && __YOUR_COMMAND__" // 🖍️ VAR
+```
+
+### ⚡ Critical (won't work without this):
+- ✓ **CMD only** - PowerShell 7.4+ has bug in async stdin handling
+- ✓ **UTF-8 before command** - `chcp 65001` required for Cyrillic
+- ✓ **WaitMsBeforeAsync: 0** - in run_command agent parameter
+
+### 📌 Versions:
+- **Works**: Windows 10/11, CMD.exe
+- **Doesn't Work**: PowerShell 7.4+, PowerShell 5 (sometimes)
+
+---
+
+## ✔️ Verification (<30 sec)
+
+```cmd
+cmd /c "chcp 65001 > nul && echo Test Cyrillic: Тест"
+```
+
+**Expected**:
+✓ Output: `Test Cyrillic: Тест` (correct, no "??????")
+
+**If it didn't work** → see Fallback below ⤵
+
+---
+
+## 🔄 Fallback (if main solution failed)
+
+### Option 1: CMD without UTF-8
+```cmd
+cmd /c "your_command"
+```
+**When**: English commands only, UTF-8 not critical
+
+### Option 2: Reinstall PowerShell
+```powershell
+winget uninstall Microsoft.PowerShell
+winget install Microsoft.PowerShell --version 7.3.9
+```
+**When**: last resort | **Risks**: PS version rollback
+
+---
+
+## 💡 Context (optional)
+
+**Root Cause**: PowerShell 7.4+ contains regression in async stdin handling when invoked via IPC
+
+**Side Effects**: all commands will run via CMD, not PowerShell (this is OK)
+
+**Best Practice**: add rule to user_rules "always use cmd /c for Windows"
+
+**Anti-Pattern**: ✗ Increasing WaitMsBeforeAsync - this masks the problem, doesn't solve it
+
+---
+
+**Applicable**: Windows 10/11, PowerShell 7.4+, AI agents with async execution
+**Frequency**: very common (every Windows user with PS7)

package/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "fixflow-mcp",
+    "version": "1.0.0",
+    "description": "Community Knowledge Base MCP Server — Stack Overflow for AI Agents",
+    "license": "MIT",
+    "bin": {
+        "fixflow-mcp": "./bin/cli.mjs"
+    },
+    "files": [
+        "bin/",
+        "fastmcp_docs_server/"
+    ],
+    "keywords": [
+        "mcp",
+        "knowledge-base",
+        "ai-agents",
+        "technical-docs",
+        "semantic-search",
+        "model-context-protocol"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mds-tech/fixflow-mcp"
+    },
+    "engines": {
+        "node": ">=18"
+    }
+}