kollguard-mcp 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -3
- package/index.mjs +162 -18
- package/package.json +20 -4
- package/server.json +30 -0
package/README.md
CHANGED
|
@@ -5,8 +5,11 @@ SOC 2 / HIPAA security findings and posture as tools, so an AI agent in **any**
|
|
|
5
5
|
client — Claude Code, Cursor, VS Code (Cline/Continue), Windsurf, Zed — can read
|
|
6
6
|
your live KollGuard data and suggest or apply fixes in your repo.
|
|
7
7
|
|
|
8
|
-
Read-only by
|
|
9
|
-
`
|
|
8
|
+
Read-only by default: authenticated with a `kgr_` API key, the read tools only issue
|
|
9
|
+
`GET` requests. If you create the key **with write scopes** (`issues:write` /
|
|
10
|
+
`epics:write` / `tickets:write`), the Developer Tools write tools let your coding
|
|
11
|
+
agent file and update issues, epics, and support tickets on your behalf. A key with
|
|
12
|
+
no write scope gets a `403` from those tools — reads stay untouched either way.
|
|
10
13
|
|
|
11
14
|
## Setup
|
|
12
15
|
|
|
@@ -33,15 +36,32 @@ Override the endpoint with `KOLLGUARD_API_URL` (defaults to `https://api.kollgua
|
|
|
33
36
|
|
|
34
37
|
## Tools
|
|
35
38
|
|
|
39
|
+
### Read (any `kgr_` key)
|
|
40
|
+
|
|
36
41
|
| Tool | What it returns |
|
|
37
42
|
|---|---|
|
|
38
43
|
| `kollguard_list_findings` | Findings (filter by `severity` / `status` / `framework`), each mapped to controls + remediation |
|
|
39
44
|
| `kollguard_get_posture` | Open findings, risk score, per-framework gaps, top risks |
|
|
40
45
|
| `kollguard_list_scans` | Recent scan runs with severity counts |
|
|
41
46
|
| `kollguard_stats` | Headline stats (open findings, by severity/framework, scans last 7d) |
|
|
47
|
+
| `kollguard_list_issues` / `kollguard_list_epics` | Developer Tools tracker items |
|
|
48
|
+
| `kollguard_list_tickets` | Support tickets — requires a key with `tickets:read` or `tickets:write` (ticket text can be sensitive, so the base read scope doesn't cover it) |
|
|
49
|
+
|
|
50
|
+
### Write (require a key with the matching scope)
|
|
51
|
+
|
|
52
|
+
| Tool | Scope | Action |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `kollguard_create_issue` | `issues:write` | File a new issue (optionally under an epic) |
|
|
55
|
+
| `kollguard_update_issue` | `issues:write` | Patch an issue (status, priority, assignee…) |
|
|
56
|
+
| `kollguard_comment_issue` | `issues:write` | Add a comment to an issue |
|
|
57
|
+
| `kollguard_link_issue_to_epic` | `issues:write` | Link/move an issue under an epic |
|
|
58
|
+
| `kollguard_create_epic` | `epics:write` | Create an epic |
|
|
59
|
+
| `kollguard_create_ticket` | `tickets:write` | Open a support ticket |
|
|
60
|
+
| `kollguard_update_ticket` | `tickets:write` | Patch a ticket (status, priority…) |
|
|
42
61
|
|
|
43
62
|
## Example prompts
|
|
44
63
|
|
|
45
64
|
- "Pull my open critical and high KollGuard findings and propose fixes for the repo."
|
|
46
65
|
- "What's my SOC 2 posture? Which controls are failing and why?"
|
|
47
|
-
- "
|
|
66
|
+
- "File this bug as a KollGuard issue linked to the auth epic."
|
|
67
|
+
- "Update ticket TICKET-20260703-0004 to resolved and comment a summary of the fix."
|
package/index.mjs
CHANGED
|
@@ -3,8 +3,11 @@
|
|
|
3
3
|
// as MCP tools, so an AI agent in ANY MCP client (Claude Code, Cursor, VS Code,
|
|
4
4
|
// Windsurf, Zed) can read live KollGuard data and suggest/apply fixes in-repo.
|
|
5
5
|
//
|
|
6
|
-
// Auth: a
|
|
7
|
-
//
|
|
6
|
+
// Auth: a `kgr_` API key (Settings -> API keys). Read-only by default — the
|
|
7
|
+
// read tools only issue GET requests. If the key was created with write scopes
|
|
8
|
+
// (issues:write / epics:write / tickets:write), the Developer Tools write tools
|
|
9
|
+
// let a coding agent file & update issues, epics, and support tickets on your
|
|
10
|
+
// behalf; without the matching scope the API returns 403 and the tool surfaces it.
|
|
8
11
|
//
|
|
9
12
|
// Env:
|
|
10
13
|
// KOLLGUARD_API_KEY required — your kgr_ read key
|
|
@@ -28,6 +31,17 @@ async function kgGet(path) {
|
|
|
28
31
|
return text;
|
|
29
32
|
}
|
|
30
33
|
|
|
34
|
+
async function kgSend(method, path, body) {
|
|
35
|
+
const res = await fetch(API_URL + path, {
|
|
36
|
+
method,
|
|
37
|
+
headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
|
|
38
|
+
body: body === undefined ? undefined : JSON.stringify(body),
|
|
39
|
+
});
|
|
40
|
+
const text = await res.text();
|
|
41
|
+
if (!res.ok) throw new Error(`KollGuard API ${res.status}: ${text.slice(0, 300)}`);
|
|
42
|
+
return text;
|
|
43
|
+
}
|
|
44
|
+
|
|
31
45
|
const TOOLS = [
|
|
32
46
|
{
|
|
33
47
|
name: 'kollguard_list_projects',
|
|
@@ -64,6 +78,101 @@ const TOOLS = [
|
|
|
64
78
|
description: 'Headline stats: open findings, breakdown by severity and framework, and scans in the last 7 days.',
|
|
65
79
|
inputSchema: { type: 'object', properties: {} },
|
|
66
80
|
},
|
|
81
|
+
// ---- Developer Tools trackers (read) ----
|
|
82
|
+
{
|
|
83
|
+
name: 'kollguard_list_issues',
|
|
84
|
+
description: 'List issues in the Developer Tools issue tracker. Optionally filter by epicId or status.',
|
|
85
|
+
inputSchema: { type: 'object', properties: { epicId: { type: 'string' }, status: { type: 'string' } } },
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
name: 'kollguard_list_epics',
|
|
89
|
+
description: 'List epics (parent containers for issues) in the Developer Tools tracker.',
|
|
90
|
+
inputSchema: { type: 'object', properties: {} },
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
name: 'kollguard_list_tickets',
|
|
94
|
+
description: 'List support tickets. Optionally filter by status or category.',
|
|
95
|
+
inputSchema: { type: 'object', properties: { status: { type: 'string' }, category: { type: 'string' } } },
|
|
96
|
+
},
|
|
97
|
+
// ---- Developer Tools trackers (write — require a key with the matching scope) ----
|
|
98
|
+
{
|
|
99
|
+
name: 'kollguard_create_issue',
|
|
100
|
+
description: 'Create an issue (requires an API key with issues:write). Optionally link to an epic.',
|
|
101
|
+
inputSchema: {
|
|
102
|
+
type: 'object',
|
|
103
|
+
properties: {
|
|
104
|
+
title: { type: 'string' },
|
|
105
|
+
description: { type: 'string' },
|
|
106
|
+
issueType: { type: 'string', enum: ['bug', 'task', 'feature', 'chore'] },
|
|
107
|
+
priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
|
|
108
|
+
epicId: { type: 'string' },
|
|
109
|
+
labels: { type: 'array', items: { type: 'string' } },
|
|
110
|
+
},
|
|
111
|
+
required: ['title'],
|
|
112
|
+
},
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
name: 'kollguard_update_issue',
|
|
116
|
+
description: 'Update an issue by id — status, priority, assignee, etc. (requires issues:write).',
|
|
117
|
+
inputSchema: {
|
|
118
|
+
type: 'object',
|
|
119
|
+
properties: {
|
|
120
|
+
issueId: { type: 'string' },
|
|
121
|
+
patch: { type: 'object', description: 'Fields to change, e.g. {"status":"in_progress","priority":"high"}' },
|
|
122
|
+
},
|
|
123
|
+
required: ['issueId', 'patch'],
|
|
124
|
+
},
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
name: 'kollguard_comment_issue',
|
|
128
|
+
description: 'Add a comment to an issue (requires issues:write).',
|
|
129
|
+
inputSchema: { type: 'object', properties: { issueId: { type: 'string' }, body: { type: 'string' } }, required: ['issueId', 'body'] },
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
name: 'kollguard_link_issue_to_epic',
|
|
133
|
+
description: 'Link (or move) an issue under an epic (requires issues:write). Pass epicId=null to unlink.',
|
|
134
|
+
inputSchema: { type: 'object', properties: { issueId: { type: 'string' }, epicId: { type: ['string', 'null'] } }, required: ['issueId'] },
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
name: 'kollguard_create_epic',
|
|
138
|
+
description: 'Create an epic (requires an API key with epics:write).',
|
|
139
|
+
inputSchema: {
|
|
140
|
+
type: 'object',
|
|
141
|
+
properties: {
|
|
142
|
+
title: { type: 'string' },
|
|
143
|
+
description: { type: 'string' },
|
|
144
|
+
priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
|
|
145
|
+
},
|
|
146
|
+
required: ['title'],
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
{
|
|
150
|
+
name: 'kollguard_create_ticket',
|
|
151
|
+
description: 'Create a support ticket (requires an API key with tickets:write).',
|
|
152
|
+
inputSchema: {
|
|
153
|
+
type: 'object',
|
|
154
|
+
properties: {
|
|
155
|
+
title: { type: 'string' },
|
|
156
|
+
description: { type: 'string' },
|
|
157
|
+
category: { type: 'string', enum: ['general', 'feature', 'bug', 'billing', 'account', 'other'] },
|
|
158
|
+
priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
|
|
159
|
+
requesterEmail: { type: 'string' },
|
|
160
|
+
},
|
|
161
|
+
required: ['title'],
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
name: 'kollguard_update_ticket',
|
|
166
|
+
description: 'Update a support ticket by id — status, priority, category, assignee (requires tickets:write).',
|
|
167
|
+
inputSchema: {
|
|
168
|
+
type: 'object',
|
|
169
|
+
properties: {
|
|
170
|
+
ticketId: { type: 'string' },
|
|
171
|
+
patch: { type: 'object', description: 'Fields to change, e.g. {"status":"resolved"}' },
|
|
172
|
+
},
|
|
173
|
+
required: ['ticketId', 'patch'],
|
|
174
|
+
},
|
|
175
|
+
},
|
|
67
176
|
];
|
|
68
177
|
|
|
69
178
|
const server = new Server({ name: 'kollguard', version: '0.1.0' }, { capabilities: { tools: {} } });
|
|
@@ -72,23 +181,58 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
|
|
|
72
181
|
|
|
73
182
|
server.setRequestHandler(CallToolRequestSchema, async (req) => {
|
|
74
183
|
const { name, arguments: args = {} } = req.params;
|
|
75
|
-
let path;
|
|
76
|
-
if (name === 'kollguard_list_projects') {
|
|
77
|
-
path = '/projects';
|
|
78
|
-
} else if (name === 'kollguard_list_findings') {
|
|
79
|
-
const qs = new URLSearchParams();
|
|
80
|
-
for (const k of ['projectId', 'severity', 'status', 'framework']) if (args[k]) qs.set(k, String(args[k]));
|
|
81
|
-
path = '/findings' + (qs.toString() ? `?${qs.toString()}` : '');
|
|
82
|
-
} else if (name === 'kollguard_get_posture') {
|
|
83
|
-
path = '/posture';
|
|
84
|
-
} else if (name === 'kollguard_list_scans') {
|
|
85
|
-
path = '/scans';
|
|
86
|
-
} else if (name === 'kollguard_stats') {
|
|
87
|
-
path = '/stats';
|
|
88
|
-
} else {
|
|
89
|
-
return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
|
|
90
|
-
}
|
|
91
184
|
try {
|
|
185
|
+
// ---- write / mutating tools (Developer Tools trackers) ----
|
|
186
|
+
if (name === 'kollguard_create_issue') {
|
|
187
|
+
const body = { title: args.title, description: args.description, issueType: args.issueType, priority: args.priority, epicId: args.epicId, labels: args.labels };
|
|
188
|
+
return { content: [{ type: 'text', text: await kgSend('POST', '/dev/issues', body) }] };
|
|
189
|
+
}
|
|
190
|
+
if (name === 'kollguard_update_issue') {
|
|
191
|
+
return { content: [{ type: 'text', text: await kgSend('PUT', `/dev/issues/${args.issueId}`, args.patch || {}) }] };
|
|
192
|
+
}
|
|
193
|
+
if (name === 'kollguard_comment_issue') {
|
|
194
|
+
return { content: [{ type: 'text', text: await kgSend('POST', '/dev/comments', { resourceKind: 'issue', resourceId: args.issueId, body: args.body }) }] };
|
|
195
|
+
}
|
|
196
|
+
if (name === 'kollguard_link_issue_to_epic') {
|
|
197
|
+
return { content: [{ type: 'text', text: await kgSend('PUT', `/dev/issues/${args.issueId}`, { epicId: args.epicId ?? null }) }] };
|
|
198
|
+
}
|
|
199
|
+
if (name === 'kollguard_create_epic') {
|
|
200
|
+
return { content: [{ type: 'text', text: await kgSend('POST', '/dev/epics', { title: args.title, description: args.description, priority: args.priority }) }] };
|
|
201
|
+
}
|
|
202
|
+
if (name === 'kollguard_create_ticket') {
|
|
203
|
+
return { content: [{ type: 'text', text: await kgSend('POST', '/dev/tickets', { title: args.title, description: args.description, category: args.category, priority: args.priority, requesterEmail: args.requesterEmail }) }] };
|
|
204
|
+
}
|
|
205
|
+
if (name === 'kollguard_update_ticket') {
|
|
206
|
+
return { content: [{ type: 'text', text: await kgSend('PUT', `/dev/tickets/${args.ticketId}`, args.patch || {}) }] };
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// ---- read tools ----
|
|
210
|
+
let path;
|
|
211
|
+
if (name === 'kollguard_list_projects') {
|
|
212
|
+
path = '/projects';
|
|
213
|
+
} else if (name === 'kollguard_list_findings') {
|
|
214
|
+
const qs = new URLSearchParams();
|
|
215
|
+
for (const k of ['projectId', 'severity', 'status', 'framework']) if (args[k]) qs.set(k, String(args[k]));
|
|
216
|
+
path = '/findings' + (qs.toString() ? `?${qs.toString()}` : '');
|
|
217
|
+
} else if (name === 'kollguard_get_posture') {
|
|
218
|
+
path = '/posture';
|
|
219
|
+
} else if (name === 'kollguard_list_scans') {
|
|
220
|
+
path = '/scans';
|
|
221
|
+
} else if (name === 'kollguard_stats') {
|
|
222
|
+
path = '/stats';
|
|
223
|
+
} else if (name === 'kollguard_list_issues') {
|
|
224
|
+
const qs = new URLSearchParams();
|
|
225
|
+
for (const k of ['epicId', 'status']) if (args[k]) qs.set(k, String(args[k]));
|
|
226
|
+
path = '/dev/issues' + (qs.toString() ? `?${qs.toString()}` : '');
|
|
227
|
+
} else if (name === 'kollguard_list_epics') {
|
|
228
|
+
path = '/dev/epics';
|
|
229
|
+
} else if (name === 'kollguard_list_tickets') {
|
|
230
|
+
const qs = new URLSearchParams();
|
|
231
|
+
for (const k of ['status', 'category']) if (args[k]) qs.set(k, String(args[k]));
|
|
232
|
+
path = '/dev/tickets' + (qs.toString() ? `?${qs.toString()}` : '');
|
|
233
|
+
} else {
|
|
234
|
+
return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
|
|
235
|
+
}
|
|
92
236
|
return { content: [{ type: 'text', text: await kgGet(path) }] };
|
|
93
237
|
} catch (e) {
|
|
94
238
|
return { content: [{ type: 'text', text: `Error: ${e?.message || e}` }], isError: true };
|
package/package.json
CHANGED
|
@@ -1,21 +1,37 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kollguard-mcp",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "MCP server for KollGuard — read your SOC 2 / HIPAA security findings & posture from any MCP client (Claude Code, Cursor, VS Code, Windsurf, Zed).",
|
|
5
|
+
"mcpName": "com.kollguard/kollguard-mcp",
|
|
5
6
|
"type": "module",
|
|
6
7
|
"bin": {
|
|
7
8
|
"kollguard-mcp": "index.mjs"
|
|
8
9
|
},
|
|
9
10
|
"files": [
|
|
10
11
|
"index.mjs",
|
|
11
|
-
"README.md"
|
|
12
|
+
"README.md",
|
|
13
|
+
"server.json"
|
|
12
14
|
],
|
|
13
15
|
"engines": {
|
|
14
16
|
"node": ">=18"
|
|
15
17
|
},
|
|
16
18
|
"dependencies": {
|
|
17
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
19
|
+
"@modelcontextprotocol/sdk": "^1.30.0"
|
|
18
20
|
},
|
|
19
|
-
"
|
|
21
|
+
"overrides": {
|
|
22
|
+
"hono": ">=4.13.18",
|
|
23
|
+
"@hono/node-server": "^2.1.8"
|
|
24
|
+
},
|
|
25
|
+
"keywords": ["mcp", "model-context-protocol", "kollguard", "soc2", "hipaa", "compliance", "security", "grc", "devsecops"],
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "git+https://github.com/Kolltiech/kollguard.git",
|
|
29
|
+
"directory": "mcp"
|
|
30
|
+
},
|
|
31
|
+
"homepage": "https://kollguard.com/docs",
|
|
32
|
+
"bugs": {
|
|
33
|
+
"url": "https://github.com/Kolltiech/kollguard/issues"
|
|
34
|
+
},
|
|
35
|
+
"author": "Kollitech",
|
|
20
36
|
"license": "MIT"
|
|
21
37
|
}
|
package/server.json
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "com.kollguard/kollguard-mcp",
|
|
4
|
+
"title": "KollGuard (local, stdio)",
|
|
5
|
+
"description": "Read your SOC 2 / HIPAA findings, posture and scans in any MCP client. Read-only by default.",
|
|
6
|
+
"version": "0.2.1",
|
|
7
|
+
"websiteUrl": "https://kollguard.com/docs",
|
|
8
|
+
"packages": [
|
|
9
|
+
{
|
|
10
|
+
"registryType": "npm",
|
|
11
|
+
"registryBaseUrl": "https://registry.npmjs.org",
|
|
12
|
+
"identifier": "kollguard-mcp",
|
|
13
|
+
"version": "0.2.1",
|
|
14
|
+
"transport": { "type": "stdio" },
|
|
15
|
+
"environmentVariables": [
|
|
16
|
+
{
|
|
17
|
+
"name": "KOLLGUARD_API_KEY",
|
|
18
|
+
"description": "Your KollGuard kgr_ read API key. Create one in KollGuard > Settings > API keys (shown once).",
|
|
19
|
+
"isRequired": true,
|
|
20
|
+
"isSecret": true
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"name": "KOLLGUARD_API_URL",
|
|
24
|
+
"description": "Override the API base URL. Defaults to https://api.kollguard.com/v1.",
|
|
25
|
+
"isRequired": false
|
|
26
|
+
}
|
|
27
|
+
]
|
|
28
|
+
}
|
|
29
|
+
]
|
|
30
|
+
}
|