kollguard-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kollitech
+
+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,47 @@
+# kollguard-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **KollGuard**. It exposes your
+SOC 2 / HIPAA security findings and posture as tools, so an AI agent in **any** MCP
+client — Claude Code, Cursor, VS Code (Cline/Continue), Windsurf, Zed — can read
+your live KollGuard data and suggest or apply fixes in your repo.
+
+Read-only by design: it only issues `GET` requests, authenticated with a read-only
+`kgr_` API key, so it can never change anything in your account.
+
+## Setup
+
+1. In KollGuard → **Settings → API keys**, create a key and copy it (shown once).
+2. Add the server to your client's MCP config, with the key:
+
+```json
+{
+  "mcpServers": {
+    "kollguard": {
+      "command": "npx",
+      "args": ["-y", "kollguard-mcp"],
+      "env": { "KOLLGUARD_API_KEY": "kgr_your_key_here" }
+    }
+  }
+}
+```
+
+- **Claude Code**: `.mcp.json` in your project root (or `claude mcp add`).
+- **Cursor**: `.cursor/mcp.json`.
+- **VS Code (Cline/Continue)** / **Windsurf** / **Zed**: their MCP settings use the same shape.
+
+Override the endpoint with `KOLLGUARD_API_URL` (defaults to `https://api.kollguard.com/v1`).
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `kollguard_list_findings` | Findings (filter by `severity` / `status` / `framework`), each mapped to controls + remediation |
+| `kollguard_get_posture` | Open findings, risk score, per-framework gaps, top risks |
+| `kollguard_list_scans` | Recent scan runs with severity counts |
+| `kollguard_stats` | Headline stats (open findings, by severity/framework, scans last 7d) |
+
+## Example prompts
+
+- "Pull my open critical and high KollGuard findings and propose fixes for the repo."
+- "What's my SOC 2 posture? Which controls are failing and why?"
+- "List database findings and write the SQL migrations to remediate them."

package/index.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// KollGuard MCP server. Exposes a tenant's security/compliance findings & posture
+// as MCP tools, so an AI agent in ANY MCP client (Claude Code, Cursor, VS Code,
+// Windsurf, Zed) can read live KollGuard data and suggest/apply fixes in-repo.
+//
+// Auth: a read-only `kgr_` API key (Settings -> API keys). Read-only by design —
+// the server only ever issues GET requests, and the key itself can't mutate.
+//
+// Env:
+//   KOLLGUARD_API_KEY   required — your kgr_ read key
+//   KOLLGUARD_API_URL   optional — defaults to https://api.kollguard.com/v1
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const API_URL = (process.env.KOLLGUARD_API_URL || 'https://api.kollguard.com/v1').replace(/\/$/, '');
+const API_KEY = process.env.KOLLGUARD_API_KEY;
+if (!API_KEY) {
+  console.error('kollguard-mcp: KOLLGUARD_API_KEY is required (create a read key in Settings → API keys).');
+  process.exit(1);
+}
+
+async function kgGet(path) {
+  const res = await fetch(API_URL + path, { headers: { Authorization: `Bearer ${API_KEY}` } });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`KollGuard API ${res.status}: ${text.slice(0, 300)}`);
+  return text;
+}
+
+const TOOLS = [
+  {
+    name: 'kollguard_list_findings',
+    description:
+      'List your security/compliance findings from KollGuard scans (GitHub repos + databases), each mapped to SOC 2 / HIPAA and 10 more frameworks with remediation. Optionally filter.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], description: 'Filter by severity' },
+        status: { type: 'string', description: "Filter by status (e.g. 'open', 'acknowledged', 'remediated', 'accepted_risk')" },
+        framework: { type: 'string', description: "Filter to a framework (e.g. 'SOC2', 'HIPAA', 'ISO 27001')" },
+      },
+    },
+  },
+  {
+    name: 'kollguard_get_posture',
+    description: 'Aggregated security posture: open findings, weighted risk score, per-framework gaps, per-project gate, and top risks.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kollguard_list_scans',
+    description: 'List recent scan runs (GitHub + database) with per-severity finding counts and status.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kollguard_stats',
+    description: 'Headline stats: open findings, breakdown by severity and framework, and scans in the last 7 days.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+const server = new Server({ name: 'kollguard', version: '0.1.0' }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  let path;
+  if (name === 'kollguard_list_findings') {
+    const qs = new URLSearchParams();
+    for (const k of ['severity', 'status', 'framework']) if (args[k]) qs.set(k, String(args[k]));
+    path = '/findings' + (qs.toString() ? `?${qs.toString()}` : '');
+  } else if (name === 'kollguard_get_posture') {
+    path = '/posture';
+  } else if (name === 'kollguard_list_scans') {
+    path = '/scans';
+  } else if (name === 'kollguard_stats') {
+    path = '/stats';
+  } else {
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+  }
+  try {
+    return { content: [{ type: 'text', text: await kgGet(path) }] };
+  } catch (e) {
+    return { content: [{ type: 'text', text: `Error: ${e?.message || e}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`kollguard-mcp connected (API: ${API_URL})`);

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "kollguard-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for KollGuard — read your SOC 2 / HIPAA security findings & posture from any MCP client (Claude Code, Cursor, VS Code, Windsurf, Zed).",
+  "type": "module",
+  "bin": {
+    "kollguard-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "keywords": ["mcp", "kollguard", "soc2", "hipaa", "compliance", "security"],
+  "license": "MIT"
+}