@offgridsec/kira-lite-mcp 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to Kira-Lite MCP Server will be documented in this file.
+
+## [0.2.0] - 2026-02-20
+
+### Added
+- **Configurable scan frequency** — new `scanMode` setting with three modes:
+  - `"every-edit"` (default) — scan on every tool call
+  - `"on-save"` — only scan via `scan_file`; `scan_code`/`scan_diff` return instantly
+  - `"manual"` — all scans skipped; post-write hook also skipped
+- **`get_config` tool** — view current Kira-Lite configuration
+- **`set_config` tool** — change scan mode and persist to `~/.kira-lite/config.json`
+- Configuration file at `~/.kira-lite/config.json`
+- Hook respects `"manual"` mode (exits immediately without scanning)
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release
+- `scan_code` — scan code snippets before writing to disk
+- `scan_file` — scan existing files on disk
+- `scan_diff` — compare original vs modified code for new vulnerabilities
+- `fix_vulnerability` — get detailed fix guidance by vulnerability ID or CWE
+- Post-write hook for Claude Code (`hook.mjs`)
+- JavaScript/TypeScript and Python rule sets
+- Regex-based scanning engine
+- Kira-Core Go binary integration with regex fallback
+- PostHog telemetry (opt-out via `KIRA_TELEMETRY=off`)

package/INSTALL.md

@@ -0,0 +1,330 @@
+# Kira-Lite — Installation Guide
+
+Kira-Lite by [Offgrid Security](https://offgridsec.com) scans code for vulnerabilities before it's written to disk, integrating directly into AI coding assistants via MCP.
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 18
+- An MCP-compatible AI coding assistant (Claude Code, Cursor, Windsurf, etc.)
+
+---
+
+## Step 1: Install
+
+```bash
+npm install -g @offgridsec/kira-lite-mcp
+```
+
+Or use `npx` to run without installing:
+
+```bash
+npx @offgridsec/kira-lite-mcp
+```
+
+---
+
+## Step 2: Register MCP Server (One-Time, Global)
+
+This registers kira-lite globally so it's available in every project.
+
+### Claude Code
+
+```bash
+claude mcp add --scope user kira-lite -- npx -y @offgridsec/kira-lite-mcp
+```
+
+### Cursor / Windsurf / Other MCP Clients
+
+Add to your MCP configuration file:
+
+```json
+{
+  "kira-lite": {
+    "command": "npx",
+    "args": ["-y", "@offgridsec/kira-lite-mcp"]
+  }
+}
+```
+
+### Verify
+
+Start your AI assistant and check MCP tools. You should see 6 tools:
+- `scan_code` — scan code before writing
+- `scan_file` — scan an existing file
+- `scan_diff` — compare original vs new code
+- `fix_vulnerability` — get fix guidance
+- `get_config` — view current configuration
+- `set_config` — change scan frequency
+
+---
+
+## Step 3: Per-Project Setup (Claude Code)
+
+Navigate to your project directory first, then follow the scenarios below.
+
+```bash
+cd /path/to/your-project
+```
+
+---
+
+### Scenario A: New Project (No Existing CLAUDE.md or Settings)
+
+#### macOS / Linux
+
+```bash
+cp $(npm root -g)/@offgridsec/kira-lite-mcp/config/CLAUDE.md .
+mkdir -p .claude
+cp $(npm root -g)/@offgridsec/kira-lite-mcp/config/settings.local.json .claude/settings.local.json
+```
+
+#### Windows (PowerShell)
+
+```powershell
+$pkg = (npm root -g) + "\@offgridsec\kira-lite-mcp"
+Copy-Item "$pkg\config\CLAUDE.md" .
+New-Item -ItemType Directory -Force .claude | Out-Null
+Copy-Item "$pkg\config\settings.local.json" .claude\settings.local.json
+```
+
+---
+
+### Scenario B: Project Already Has a CLAUDE.md
+
+**Do not overwrite** — append the kira-lite instructions to the end.
+
+#### macOS / Linux
+
+```bash
+echo "" >> CLAUDE.md
+cat $(npm root -g)/@offgridsec/kira-lite-mcp/config/CLAUDE.md >> CLAUDE.md
+```
+
+#### Manual Option
+
+Add this block to the bottom of your existing `CLAUDE.md`:
+
+```markdown
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY single Edit or Write tool call. No exceptions. This is not optional.
+
+## How it works
+
+1. Before you use Edit or Write, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+
+## Rules
+
+- EVERY Edit/Write MUST be preceded by a scan_code call
+- If scan returns critical or high findings, DO NOT write the code
+- Tell the user what you found and what you fixed
+- This applies to ALL files: .js, .ts, .py, .go, .java, .rb, .php, .yaml, .tf, Dockerfile, etc.
+```
+
+---
+
+### Scenario C: Project Already Has .claude/settings.local.json
+
+**Do not overwrite** — merge the kira-lite permissions and hooks into the existing file.
+
+#### What to Add
+
+Open `.claude/settings.local.json` and merge these two sections:
+
+**1. Add to `permissions.allow` array:**
+
+```json
+"mcp__kira-lite__scan_code",
+"mcp__kira-lite__scan_file",
+"mcp__kira-lite__scan_diff",
+"mcp__kira-lite__fix_vulnerability",
+"mcp__kira-lite__get_config",
+"mcp__kira-lite__set_config"
+```
+
+**2. Add to `hooks` object:**
+
+```json
+"PostToolCall": [
+  {
+    "matcher": "Write|Edit",
+    "hooks": [
+      {
+        "type": "command",
+        "command": "npx --yes @offgridsec/kira-lite-mcp/hook.mjs"
+      }
+    ]
+  }
+]
+```
+
+#### Example: Before
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)"
+    ]
+  }
+}
+```
+
+#### Example: After
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "mcp__kira-lite__scan_code",
+      "mcp__kira-lite__scan_file",
+      "mcp__kira-lite__scan_diff",
+      "mcp__kira-lite__fix_vulnerability",
+      "mcp__kira-lite__get_config",
+      "mcp__kira-lite__set_config"
+    ]
+  },
+  "hooks": {
+    "PostToolCall": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --yes @offgridsec/kira-lite-mcp/hook.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+### Scenario D: Both CLAUDE.md and settings.local.json Already Exist
+
+Combine Scenario B + Scenario C:
+
+1. Append kira-lite instructions to `CLAUDE.md` (Scenario B)
+2. Merge permissions and hooks into `.claude/settings.local.json` (Scenario C)
+
+---
+
+## Step 4: Configure Scan Frequency (Optional)
+
+By default, Kira-Lite scans on every tool call (`"every-edit"` mode). You can change this to reduce overhead.
+
+### Using the MCP tool
+
+```
+set_config({ scanMode: "on-save" })
+```
+
+### Or create the config file manually
+
+Create `~/.kira-lite/config.json`:
+
+```json
+{
+  "scanMode": "on-save"
+}
+```
+
+### Available modes
+
+| Mode | `scan_code` | `scan_diff` | `scan_file` | Hook |
+|------|-------------|-------------|-------------|------|
+| `"every-edit"` | scans | scans | scans | active |
+| `"on-save"` | skipped | skipped | scans | active |
+| `"manual"` | skipped | skipped | skipped | skipped |
+
+> `fix_vulnerability` always works regardless of mode.
+
+### Check current config
+
+```
+get_config()
+```
+
+---
+
+## What Each File Does
+
+| File | Purpose | Scope |
+|------|---------|-------|
+| `CLAUDE.md` | Instructs the AI to call `scan_code` before every Edit/Write | Per-project |
+| `.claude/settings.local.json` | Auto-allows kira-lite tools + post-write hook enforcement | Per-project |
+| `~/.kira-lite/config.json` | Scan frequency configuration | User-wide |
+| `~/.kira-lite/device-id` | Anonymous device ID for telemetry | User-wide |
+
+> **Important:** Hooks (`PostToolCall`) only work in **project-level** `.claude/settings.local.json`. Do NOT add hooks to the user-level `~/.claude/settings.local.json`.
+
+---
+
+## Uninstall
+
+### Remove from a single project
+
+```bash
+# Remove CLAUDE.md kira-lite section (or delete if it only has kira-lite)
+# Remove kira-lite entries from .claude/settings.local.json
+```
+
+### Remove globally
+
+```bash
+# Claude Code
+claude mcp remove --scope user kira-lite
+
+# npm
+npm uninstall -g @offgridsec/kira-lite-mcp
+```
+
+### Remove config
+
+```bash
+rm -rf ~/.kira-lite
+```
+
+---
+
+## Troubleshooting
+
+### "Settings Error: PostToolCall: Invalid key in record"
+
+You have hooks in the **user-level** settings file (`~/.claude/settings.local.json`). Hooks only work at project level. Remove the `hooks` section from the user-level file.
+
+### MCP not showing in `/mcp`
+
+Re-register globally:
+
+```bash
+claude mcp add --scope user kira-lite -- npx -y @offgridsec/kira-lite-mcp
+```
+
+### Claude doesn't scan before writing
+
+1. Check that `CLAUDE.md` exists in the project root with the kira-lite instructions
+2. Verify the hook is in `.claude/settings.local.json` — this is the enforcement layer
+3. Start a **new** session (CLAUDE.md is read at session start)
+
+### Scans returning "Skipped"
+
+Your scan mode is set to `"on-save"` or `"manual"`. Check with `get_config()` and change with `set_config({ scanMode: "every-edit" })`.
+
+### Hook fails silently
+
+Make sure Node.js can find the hook script:
+
+```bash
+node $(npm root -g)/@offgridsec/kira-lite-mcp/hook.mjs
+```
+
+If it exits with no output, it's working. If it throws an error, check the path.

package/LICENSE

@@ -0,0 +1,96 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2025-2026 Offgrid Security
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your
+licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/PRIVACY.md

@@ -0,0 +1,54 @@
+# Privacy Policy
+
+**Kira-Lite MCP Server** by [Offgrid Security](https://offgridsec.com)
+
+Last updated: February 20, 2026
+
+---
+
+## What we collect
+
+Kira-Lite collects **anonymous, non-personalized** usage telemetry to help us improve the product. This includes:
+
+- **Tool usage** — which scan tools are called (e.g. `scan_code`, `scan_file`)
+- **Scan statistics** — number of lines scanned, number of findings, severity counts, scan duration
+- **Vulnerability rule IDs** — which rules triggered (e.g. `KIRA-JS-SQLI-001`, `CWE-89`)
+- **Environment metadata** — Node.js version, platform (win32/linux/darwin), Kira-Lite version
+- **Anonymous device ID** — a randomly generated UUID stored locally at `~/.kira-lite/device-id`
+
+## What we do NOT collect
+
+- **No source code** — your code never leaves your machine
+- **No file paths** — we do not log file names or directory structures
+- **No personal information** — no names, emails, IP addresses, or account identifiers
+- **No code snippets** — scan findings reference rule IDs only, not your actual code
+- **No project metadata** — no repository names, branch names, or commit hashes
+
+## How it works
+
+Telemetry is sent to [PostHog](https://posthog.com) (US region) using an anonymous device ID. This ID is a random UUID generated on first run and stored locally. It cannot be traced back to you.
+
+## How to opt out
+
+Set the `KIRA_TELEMETRY` environment variable to disable all telemetry:
+
+```bash
+# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
+export KIRA_TELEMETRY=off
+```
+
+Or on Windows (PowerShell):
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("KIRA_TELEMETRY", "off", "User")
+```
+
+When telemetry is off, **no data is sent anywhere**. Kira-Lite functions exactly the same.
+
+## Data retention
+
+Anonymous telemetry data is retained for product analytics only. Since no personal data is collected, there is nothing to delete or request under GDPR/CCPA.
+
+## Contact
+
+Questions about privacy? Reach us at [contact@offgridsec.com](mailto:contact@offgridsec.com).