openkrak-mcp 1.0.1 → 1.0.2

package/README.md

@@ -8,11 +8,14 @@ OpenKrak pre-computes your repository's structure and delivers a structured inte
 
 ## The Problem
 
-Every time you ask Claude Code, OpenCode, or Cursor to modify code, the LLM starts blind — reading raw files, burning tokens, guessing dependencies.
+Every time you ask your coding agent to modify code, the LLM starts blind — reading raw files, burning tokens, guessing dependencies.
 
-**Without OpenKrak:** LLM reads 50,000 tokens of raw files. Slow. Expensive. Blind.  
+**Without OpenKrak:** LLM reads 50,000+ tokens of raw files. Slow. Expensive. Blind.  
 **With OpenKrak:** LLM reads a pre-computed Mahadata brief. Precise. Cheap. Aware.
 
+For simple tasks, OpenKrak replaces 50+ file reads with a single tool call.  
+For complex refactors, it cuts token usage 20-30% and eliminates blind exploration — the LLM knows exactly which files matter before it reads a single line.
+
 ---
 
 ## How It Works
@@ -20,10 +23,39 @@ Every time you ask Claude Code, OpenCode, or Cursor to modify code, the LLM star
 OpenKrak runs the **Dorchester engine** — a 6-step static analysis pipeline:
 
 ```
-Repository → DeepStrike → Hotspot Registry → Correlation Engine → Blast Radius → Execution Gate → Mahadata
+Repository
+    │
+    ▼
+DeepStrike          — Full static analysis: every import, export, coupling resolved
+    │
+    ▼
+Hotspot Registry    — Files ranked by complexity, change frequency, cognitive load
+    │
+    ▼
+Correlation Engine  — Dependency chains traced across the entire codebase
+    │
+    ▼
+Blast Radius        — Ripple effects of any change mapped before commit
+    │
+    ▼
+Execution Gate      — Analysis validated and normalized
+    │
+    ▼
+Mahadata            — Structured intelligence brief delivered to your coding agent
 ```
 
-The result is delivered as a structured brief to your coding agent via MCP before any code is touched.
+Your codebase never leaves your machine. All analysis runs locally.
+
+---
+
+## Supported Agents
+
+| Agent | Status |
+|-------|--------|
+| **OpenCode** | ✅ Supported |
+| Claude Code | 🔜 Coming soon |
+| Codex | 🔜 Coming soon |
+| Cursor | 🔜 Coming soon |
 
 ---
 
@@ -33,73 +65,146 @@ The result is delivered as a structured brief to your coding agent via MCP befor
 npm install -g openkrak-mcp
 ```
 
-## Usage
+---
+
+## Setup — OpenCode
 
-### OpenCode
-```json
-// ~/.config/opencode/opencode.jsonc
+### Step 1 — Edit config
+
+Open `~/.config/opencode/opencode.jsonc` and add the `mcp` block:
+
+```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "openkrak": {
       "type": "local",
       "enabled": true,
-      "command": ["npx", "openkrak-mcp"]
+      "command": ["openkrak-mcp"]
     }
   }
 }
 ```
 
-### Claude Code
-```json
-// ~/.claude/mcp.json
-{
-  "mcpServers": {
-    "openkrak": {
-      "command": "npx",
-      "args": ["openkrak-mcp"],
-      "env": { "OPENKRAK_KEY": "your-license-key" }
-    }
-  }
-}
+> **Windows path:** `C:\Users\<username>\.config\opencode\opencode.jsonc`  
+> **Mac/Linux path:** `~/.config/opencode/opencode.jsonc`
+
+### Step 2 — Restart OpenCode
+
+Close and reopen OpenCode. You should see **openkrak Connected** in the top-right MCP panel.
+
+### Step 3 — Use it
+
+Just open a repo and ask your agent anything. OpenKrak automatically runs before the LLM touches your files.
+
+Or call it explicitly:
+
+```
+Use analyze_repo on /path/to/your/repo with objective "refactor the auth module"
 ```
 
-### Activate Pro (optional)
-```bash
-OPENKRAK_KEY=your-key npx openkrak-mcp
+---
+
+## Turning OpenKrak On / Off
+
+Change `"enabled"` in your config:
+
+```jsonc
+// ON
+"enabled": true
+
+// OFF
+"enabled": false
+```
+
+Then restart OpenCode. That's it.
+
+**Quick toggle scripts (optional):**
+
+Save these two files anywhere on your machine.
+
+`mcp-on.ps1` (Windows PowerShell):
+```powershell
+$config = Get-Content "$env:USERPROFILE\.config\opencode\opencode.jsonc" | ConvertFrom-Json -AsHashtable
+$config.mcp.openkrak.enabled = $true
+$config | ConvertTo-Json -Depth 10 | Set-Content "$env:USERPROFILE\.config\opencode\opencode.jsonc"
+Write-Host "OpenKrak: ON"
+```
+
+`mcp-off.ps1` (Windows PowerShell):
+```powershell
+$config = Get-Content "$env:USERPROFILE\.config\opencode\opencode.jsonc" | ConvertFrom-Json -AsHashtable
+$config.mcp.openkrak.enabled = $false
+$config | ConvertTo-Json -Depth 10 | Set-Content "$env:USERPROFILE\.config\opencode\opencode.jsonc"
+Write-Host "OpenKrak: OFF"
+```
+
+Run with:
+```powershell
+powershell -File mcp-on.ps1
+powershell -File mcp-off.ps1
 ```
 
 ---
 
 ## Tools
 
-| Tool | Description |
+Once connected, your coding agent has access to 4 tools:
+
+| Tool | When to use |
 |------|-------------|
-| `analyze_repo` | Full Dorchester pipeline — dependency graph, hotspots, blast radius, threat matrix |
-| `get_mahadata` | Compact 500-token intelligence brief for fast LLM context |
-| `get_hotspots` | Ranked list of high-risk files by complexity, coupling, change frequency |
-| `blast_radius` | Ripple effect map of modifying a specific file |
+| `analyze_repo` | Before any coding task — runs full Dorchester pipeline, returns dependency graph, hotspots, blast radius, threat matrix |
+| `get_mahadata` | Quick 500-token intelligence brief — repo structure, entry points, constraints, risk score |
+| `get_hotspots` | Which files are most dangerous to touch — ranked by complexity, coupling, change frequency |
+| `blast_radius` | Ripple effect of modifying a specific file — which files, modules, APIs will be affected |
 
 ---
 
-## Pricing
+## Pro License (optional)
+
+Free tier gives you **15 calls per 24 hours** — no account needed.
+
+For unlimited calls, get a Pro key at **[openkrak.dev](https://openkrak.dev)**:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "openkrak": {
+      "type": "local",
+      "enabled": true,
+      "command": ["openkrak-mcp"],
+      "env": {
+        "OPENKRAK_KEY": "your-license-key"
+      }
+    }
+  }
+}
+```
 
 | Plan | Price | Limit |
 |------|-------|-------|
-| Free | $0 | 15 calls / 24h |
+| Free | $0 | 15 calls / 24h rolling |
 | Pro Monthly | $8/month | Unlimited |
 | Pro Annual | $67.20/year | Unlimited |
 
-Get a Pro key at **[openkrak.dev](https://openkrak.dev)**
+---
+
+## Privacy
+
+- Your codebase **never leaves your machine**
+- Analysis runs 100% locally via the Dorchester engine
+- Only license validation calls hit the network (to verify your key)
+- No telemetry, no file uploads
 
 ---
 
 ## Tech
 
-- Protocol: MCP (Model Context Protocol) — open standard
-- Analysis: Static, deterministic — not AI/probabilistic
-- Privacy: Codebase never leaves your machine (Phase 1)
-- Compatible: Any MCP-compatible agent (OpenCode, Claude Code, Cursor, Codex)
+- **Protocol:** MCP (Model Context Protocol) — open standard by Anthropic
+- **Analysis:** Static, deterministic — not AI/probabilistic
+- **Runtime:** Node.js ≥ 18
+- **License:** MIT
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openkrak-mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "OpenKrak MCP Server — AI coding intelligence via Dorchester engine",
   "type": "module",
   "bin": {