karukia-mcp 3.0.2 → 3.0.3
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 +313 -313
- package/dist/http.js +76 -76
- package/dist/index.js +77 -77
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,313 +1,313 @@
|
|
|
1
|
-
# KARUKIA MCP
|
|
2
|
-
|
|
3
|
-
```
|
|
4
|
-
██╗ ██╗ █████╗ ██████╗ ██╗ ██╗██╗ ██╗ ██╗ █████╗
|
|
5
|
-
██║ ██╔╝██╔══██╗██╔══██╗██║ ██║██║ ██╔╝ ██║██╔══██╗
|
|
6
|
-
█████╔╝ ███████║██████╔╝██║ ██║█████╔╝ ██║███████║
|
|
7
|
-
██╔═██╗ ██╔══██║██╔══██╗██║ ██║██╔═██╗ ██║██╔══██║
|
|
8
|
-
██║ ██╗██║ ██║██║ ██║╚██████╔╝██║ ██╗ ██║██║ ██║
|
|
9
|
-
╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝
|
|
10
|
-
AI methodology for highly regulated industries · Made in Guadeloupe 🇬🇵
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
**The complete AI-assisted development methodology, delivered via MCP.**
|
|
14
|
-
|
|
15
|
-
**Latest: v3.0.
|
|
16
|
-
|
|
17
|
-
27 tools, 20 skills, 1673+ checkpoints across 11 audit dimensions. Works with any AI platform (Claude Code, Cursor, Windsurf, Copilot...) through the Model Context Protocol.
|
|
18
|
-
|
|
19
|
-
## What is KARUKIA?
|
|
20
|
-
|
|
21
|
-
KARUKIA is a structured development methodology built around specialized AI personas. Each persona (Neo for security, Jeffrey for architecture, Viper for pentesting, Opo for quality...) comes with its own workflow, guard rails, and knowledge base.
|
|
22
|
-
|
|
23
|
-
When you call a KARUKIA tool, the MCP server returns a complete prompt — persona identity, workflow, checklists, templates — that transforms your AI assistant into that specialist for the session.
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
You: "Run a security audit"
|
|
27
|
-
-> AI calls neo tool
|
|
28
|
-
-> MCP returns full Neo persona prompt + 445 security controls inline
|
|
29
|
-
-> AI becomes Neo, follows the methodology, produces structured findings
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
## The 11 Audit Dimensions
|
|
33
|
-
|
|
34
|
-
```
|
|
35
|
-
SECURITY → Neo (445 pts) "Is my code secure?"
|
|
36
|
-
QUALITY → Opquast (245 pts) "Is my app well-built?"
|
|
37
|
-
OFFENSIVE → Viper (245+ tests) "How would a hacker break in?"
|
|
38
|
-
TS → ts_quality (118) "Is my TypeScript clean?"
|
|
39
|
-
CSS → css_quality (55) "Is my design system maintainable?"
|
|
40
|
-
ARCHI → archi (70) "Is my architecture sound?"
|
|
41
|
-
TESTS → test_coverage (68) "Am I testing the right things?"
|
|
42
|
-
PERF → perf (90) "Where are the bottlenecks?"
|
|
43
|
-
DEBT → debt (55) "What's slowing us down?"
|
|
44
|
-
HDS/ISO → audit_expert (200+)"Am I ready for certification?"
|
|
45
|
-
SCAN → karukia_scan "Run all 11 dimensions at once"
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## Quick Start
|
|
51
|
-
|
|
52
|
-
**Prerequisites:** [Node.js](https://nodejs.org/) 22 or later.
|
|
53
|
-
|
|
54
|
-
### Step 1 — Add KARUKIA to your project
|
|
55
|
-
|
|
56
|
-
Create or edit `.mcp.json` at the root of your project:
|
|
57
|
-
|
|
58
|
-
```json
|
|
59
|
-
{
|
|
60
|
-
"mcpServers": {
|
|
61
|
-
"karukia": {
|
|
62
|
-
"command": "npx",
|
|
63
|
-
"args": ["karukia-mcp"]
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
> **Note:** If the file already exists and has other MCP servers, just add the `"karukia"` key inside the existing `"mcpServers"` object.
|
|
70
|
-
|
|
71
|
-
### Step 2 — Restart your AI client
|
|
72
|
-
|
|
73
|
-
Restart Claude Code (`/quit` then relaunch) or your IDE. The 27 KARUKIA tools are now available.
|
|
74
|
-
|
|
75
|
-
> On first launch, `npx` downloads the package automatically (~175 KB). Subsequent launches use the cached version.
|
|
76
|
-
|
|
77
|
-
### Step 3 — Configure your project
|
|
78
|
-
|
|
79
|
-
Tell your AI:
|
|
80
|
-
|
|
81
|
-
> "karukia install"
|
|
82
|
-
|
|
83
|
-
KARUKIA scans your project, detects your stack, and generates configuration files (security scope, CLAUDE.md, memory structure).
|
|
84
|
-
|
|
85
|
-
### Step 4 — Start working
|
|
86
|
-
|
|
87
|
-
Just describe what you need in natural language:
|
|
88
|
-
|
|
89
|
-
> "karukia: add user authentication"
|
|
90
|
-
> "karukia: audit security"
|
|
91
|
-
> "karukia: run a pentest"
|
|
92
|
-
|
|
93
|
-
The orchestrator (`auto`) analyzes your request and routes to the right specialists automatically.
|
|
94
|
-
|
|
95
|
-
> **Tip:** You only need two commands: `karukia install` (once) then `karukia` + your request (always). For direct control, ask for a specific skill: "karukia neo", "karukia viper", "karukia jeffrey". Say "karukia start" anytime for a full guide.
|
|
96
|
-
|
|
97
|
-
### Where to put the config
|
|
98
|
-
|
|
99
|
-
| Client | File | Scope |
|
|
100
|
-
|--------|------|-------|
|
|
101
|
-
| **Claude Code CLI** | `.mcp.json` at project root | This project only |
|
|
102
|
-
| **Claude Code CLI** | `~/.claude.json` (home directory) | All your projects |
|
|
103
|
-
| **Claude Desktop** | `claude_desktop_config.json` | Global |
|
|
104
|
-
| **Cursor** | `.cursor/mcp.json` at project root | This project only |
|
|
105
|
-
| **Windsurf** | MCP settings panel | Global |
|
|
106
|
-
|
|
107
|
-
---
|
|
108
|
-
|
|
109
|
-
## Global Installation (optional)
|
|
110
|
-
|
|
111
|
-
If you want KARUKIA available in all your projects without adding `.mcp.json` each time:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
npm install -g karukia-mcp
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
Then add to your global AI config (`~/.claude.json` for Claude Code):
|
|
118
|
-
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"mcpServers": {
|
|
122
|
-
"karukia": {
|
|
123
|
-
"command": "karukia-mcp"
|
|
124
|
-
}
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
## 27 Tools
|
|
132
|
-
|
|
133
|
-
### Essential (start here)
|
|
134
|
-
|
|
135
|
-
| Tool | Description |
|
|
136
|
-
|------|-------------|
|
|
137
|
-
| `install` | **[FIRST STEP]** Configure KARUKIA for your project — run once |
|
|
138
|
-
| `auto` | **[MAIN TOOL]** Describe what you need — KARUKIA routes to the right skills |
|
|
139
|
-
| `start` | Quick-start guide — explains all skills at 3 progressive levels |
|
|
140
|
-
|
|
141
|
-
### Core Skills (AI Personas)
|
|
142
|
-
|
|
143
|
-
Each skill returns a complete prompt that transforms your AI into a specialist.
|
|
144
|
-
|
|
145
|
-
| Tool | Persona | What it does |
|
|
146
|
-
|------|---------|-------------|
|
|
147
|
-
| `neo` | Security Auditor | Defensive audit against 6 frameworks (OWASP, HDS, ISO 27001, SOC 2, PCI-DSS, HIPAA) |
|
|
148
|
-
| `viper` | Pentest Brigade | Offensive testing with 16 agents, CVSS v4 scoring, MITRE ATT&CK mapping |
|
|
149
|
-
| `jeffrey` | Full-Stack Architect | Feature implementation with TDD and security validation |
|
|
150
|
-
| `opo` | Quality Validator | Web quality against 245 Opquast rules |
|
|
151
|
-
| `audit_opquast` | Quality Auditor | Deep Opquast compliance audit with 14 thematic checklists |
|
|
152
|
-
| `ebios_rm_audit` | Risk Analyst | EBIOS Risk Manager methodology (ANSSI) — formal risk analysis |
|
|
153
|
-
| `security_hardening` | Hardening Planner | Security improvement chantiers |
|
|
154
|
-
| `doc_refactor` | Doc Auditor | Documentation accuracy audit vs actual code |
|
|
155
|
-
|
|
156
|
-
### Dimensional Skills (v3.0 New)
|
|
157
|
-
|
|
158
|
-
| Tool | Checkpoints | What it does |
|
|
159
|
-
|------|-------------|-------------|
|
|
160
|
-
| `ts_quality` | 118 | TypeScript audit — type safety, strict config, generics, async patterns |
|
|
161
|
-
| `css_quality` | 55 | CSS/Design System — maintainability, accessibility, metrics |
|
|
162
|
-
| `archi` | 70 | Architecture — module structure, coupling, layering |
|
|
163
|
-
| `test_coverage` | 68 | Test inventory — frontend/backend coverage quality |
|
|
164
|
-
| `perf` | 90 | Performance — frontend, backend, build/bundle |
|
|
165
|
-
| `debt` | 55 | Technical debt — dead code, dependency health, code smells |
|
|
166
|
-
| `karukia_scan` | 1673+ | **Global scan** — all 11 dimensions in parallel |
|
|
167
|
-
| `audit_expert_hds` | 200+ | Expert HDS 2.0/ISO 27001 — 8 domains, certification readiness |
|
|
168
|
-
| `change_report` | — | Change management report (ISO 27001 A.8.32) |
|
|
169
|
-
|
|
170
|
-
### Utilities
|
|
171
|
-
|
|
172
|
-
| Tool | Description |
|
|
173
|
-
|------|-------------|
|
|
174
|
-
| `list_checklists` | Browse all 31 checklists by category |
|
|
175
|
-
| `suggest_checklists` | Describe your project — get a prioritized audit plan |
|
|
176
|
-
| `generate_report` | Compile audit results into a scored Markdown report |
|
|
177
|
-
|
|
178
|
-
### Memory & Config
|
|
179
|
-
|
|
180
|
-
| Tool | Description |
|
|
181
|
-
|------|-------------|
|
|
182
|
-
| `init_memory` | Initialize KARUKIA memory structure in a project |
|
|
183
|
-
| `get_session_template` | Get pre-filled session templates for any skill |
|
|
184
|
-
| `get_config_template` | Get configuration templates (security scope, CLAUDE.md, analytics) |
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## 31 Checklists
|
|
189
|
-
|
|
190
|
-
### Defensive Security (Neo) — 6 checklists, 445 controls
|
|
191
|
-
|
|
192
|
-
| Checklist | Points | Scope |
|
|
193
|
-
|-----------|--------|-------|
|
|
194
|
-
| **OWASP Security Baseline** | 62 | Every web app |
|
|
195
|
-
| **HDS 2.0** | 52 | Health data, France |
|
|
196
|
-
| **ISO 27001:2022** | 93 | Enterprise ISMS |
|
|
197
|
-
| **SOC 2 Type II** | 74 | SaaS, US market |
|
|
198
|
-
| **PCI-DSS v4.0** | 97 | Payment processing |
|
|
199
|
-
| **HIPAA** | 67 | Health data, US |
|
|
200
|
-
|
|
201
|
-
### Web Quality (Opquast) — 14 checklists, 245 rules
|
|
202
|
-
|
|
203
|
-
Content, personal data, e-commerce, forms, identity, images, internationalization, links, navigation, newsletter, presentation, security UX, server performance, and code structure.
|
|
204
|
-
|
|
205
|
-
Based on [Opquast](https://www.opquast.com/) — the French web quality reference used by 15,000+ professionals.
|
|
206
|
-
|
|
207
|
-
### Offensive Security (Viper) — 4 checklists, 245+ tests
|
|
208
|
-
|
|
209
|
-
| Checklist | Tests | Scope |
|
|
210
|
-
|-----------|-------|-------|
|
|
211
|
-
| **OWASP WSTG v5** | 100 | Web penetration testing |
|
|
212
|
-
| **Cloud Platform** | 80+ | Firebase, GCP, AWS, Azure |
|
|
213
|
-
| **Healthcare** | 50+ | PHI, encryption, medical data |
|
|
214
|
-
| **Attack Scenarios** | 15+ | PTES templates, MITRE ATT&CK |
|
|
215
|
-
|
|
216
|
-
### Dimensional Quality (New in v3.0) — 7 checklists, 656+ checkpoints
|
|
217
|
-
|
|
218
|
-
| Checklist | Points | Scope |
|
|
219
|
-
|-----------|--------|-------|
|
|
220
|
-
| **TypeScript Quality** | 118 | Type safety, strict config, patterns |
|
|
221
|
-
| **CSS / Design System** | 55 | Maintainability, a11y, metrics |
|
|
222
|
-
| **Architecture** | 70 | Module structure, coupling, layering |
|
|
223
|
-
| **Test Coverage** | 68 | Frontend/backend inventory, quality |
|
|
224
|
-
| **Performance** | 90 | Frontend, backend, build/bundle |
|
|
225
|
-
| **Technical Debt** | 55 | Dead code, deps, code smells |
|
|
226
|
-
| **Expert HDS/ISO 27001** | 200+ | Certification readiness — 8 domains |
|
|
227
|
-
|
|
228
|
-
---
|
|
229
|
-
|
|
230
|
-
## Usage Examples
|
|
231
|
-
|
|
232
|
-
### Full security audit
|
|
233
|
-
|
|
234
|
-
> "Run a security audit on my project"
|
|
235
|
-
|
|
236
|
-
Your AI calls `neo` — becomes the Neo security auditor — follows the methodology — produces structured findings with severity, file:line references, and remediation steps.
|
|
237
|
-
|
|
238
|
-
### Build a feature with guardrails
|
|
239
|
-
|
|
240
|
-
> "karukia jeffrey: implement user authentication"
|
|
241
|
-
|
|
242
|
-
Your AI calls `jeffrey` — becomes the Jeffrey architect — implements with TDD, then chains to Neo for security validation (rejection loop: if Neo rejects, Jeffrey fixes, max 3 iterations).
|
|
243
|
-
|
|
244
|
-
### Pentest your app
|
|
245
|
-
|
|
246
|
-
> "karukia viper"
|
|
247
|
-
|
|
248
|
-
Your AI calls `viper` — deploys the Brigade methodology with 16 specialized agents across Recon, Surface Analysis, and Exploitation phases.
|
|
249
|
-
|
|
250
|
-
### Orchestrate everything
|
|
251
|
-
|
|
252
|
-
> "karukia: add a logout button and audit security"
|
|
253
|
-
|
|
254
|
-
Your AI calls `auto` — analyzes the request — routes to the right skill(s) — manages the chain.
|
|
255
|
-
|
|
256
|
-
---
|
|
257
|
-
|
|
258
|
-
## Documentation
|
|
259
|
-
|
|
260
|
-
- [Livre Blanc (Français)](./LIVRE-BLANC.md) — Document technique détaillé : architecture, méthodologie, cas d'usage
|
|
261
|
-
- [Whitepaper (English)](./WHITEPAPER.md) — Technical deep-dive: architecture, methodology, use cases
|
|
262
|
-
|
|
263
|
-
---
|
|
264
|
-
|
|
265
|
-
## Cloud / Enterprise
|
|
266
|
-
|
|
267
|
-
KARUKIA runs locally by default (stdio via `npx`). Free, zero infrastructure.
|
|
268
|
-
|
|
269
|
-
**For teams** — a managed KARUKIA server (waitlist): connect your whole team via a single API key, centralized audit trail, consistent checklists across all developers.
|
|
270
|
-
|
|
271
|
-
→ **contact@karukia.com** to join the waitlist.
|
|
272
|
-
|
|
273
|
-
---
|
|
274
|
-
|
|
275
|
-
## About
|
|
276
|
-
|
|
277
|
-
KARUKIA is developed by **[KARUK IA Solutions](https://karukia.com)**, a B2B SaaS studio specializing in regulated industries (healthcare, finance, pharma), based in Guadeloupe. 🇬🇵
|
|
278
|
-
|
|
279
|
-
Built from the experience of securing a healthcare SaaS application for HDS 2.0 / ISO 27001 certification. The methodology was made open to share what a real certification process actually requires — not just theory.
|
|
280
|
-
|
|
281
|
-
> *Made in Guadeloupe — AI doesn't replace the expert, it frees them.*
|
|
282
|
-
|
|
283
|
-
---
|
|
284
|
-
|
|
285
|
-
## Why KARUKIA
|
|
286
|
-
|
|
287
|
-
KARUKIA is a structured AI-assisted development methodology built around three principles:
|
|
288
|
-
|
|
289
|
-
1. **Separation of concerns** — Security, quality, and implementation are separate disciplines handled by separate AI personas.
|
|
290
|
-
2. **Formal checkpoints over gut feeling** — 1673+ documented checkpoints beat "I think it's fine."
|
|
291
|
-
3. **Defense in depth** — Defensive audit first, quality validation second, offensive testing last.
|
|
292
|
-
|
|
293
|
-
Built from real-world experience securing a healthcare SaaS application to HDS 2.0 / ISO 27001 standards.
|
|
294
|
-
|
|
295
|
-
---
|
|
296
|
-
|
|
297
|
-
## Privacy & Data Handling
|
|
298
|
-
|
|
299
|
-
- **KARUKIA MCP does not store any user data server-side.** In stdio mode (default via `npx`), the server is stateless — no data leaves your machine.
|
|
300
|
-
- **Generated prompts** are returned to your AI client (Claude, GPT, Cursor, etc.). Do not include real health data, credentials, or sensitive personal information in tool call arguments (e.g., the `scope`, `task`, or `period` fields).
|
|
301
|
-
- **HTTP mode** (`start:http`): request logs contain session metadata (tool name, duration, HTTP status) but never the content of requests or generated prompts. Sensitive headers (`Authorization`, `Mcp-Session-Id`) are automatically redacted in logs.
|
|
302
|
-
- **Session memory files** (stored in `karukia/memory/sessions/` on your machine): follow the retention policy documented in [`karukia/config/session-retention.md`](./karukia/config/session-retention.md). For teams in regulated sectors: do not store real patient data or PHI in session files.
|
|
303
|
-
- **For teams in regulated sectors (healthcare, finance)**: use stdio mode (local) for maximum data isolation, or contact contact@karukia.com for the managed offering.
|
|
304
|
-
|
|
305
|
-
---
|
|
306
|
-
|
|
307
|
-
## License
|
|
308
|
-
|
|
309
|
-
KARUKIA MCP is free for personal, educational, and internal professional use.
|
|
310
|
-
|
|
311
|
-
**Commercial use or resale requires written authorization.** Contact: contact@karukia.com
|
|
312
|
-
|
|
313
|
-
See [LICENSE](./LICENSE) for full terms.
|
|
1
|
+
# KARUKIA MCP
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
██╗ ██╗ █████╗ ██████╗ ██╗ ██╗██╗ ██╗ ██╗ █████╗
|
|
5
|
+
██║ ██╔╝██╔══██╗██╔══██╗██║ ██║██║ ██╔╝ ██║██╔══██╗
|
|
6
|
+
█████╔╝ ███████║██████╔╝██║ ██║█████╔╝ ██║███████║
|
|
7
|
+
██╔═██╗ ██╔══██║██╔══██╗██║ ██║██╔═██╗ ██║██╔══██║
|
|
8
|
+
██║ ██╗██║ ██║██║ ██║╚██████╔╝██║ ██╗ ██║██║ ██║
|
|
9
|
+
╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝
|
|
10
|
+
AI methodology for highly regulated industries · Made in Guadeloupe 🇬🇵
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
**The complete AI-assisted development methodology, delivered via MCP.**
|
|
14
|
+
|
|
15
|
+
**Latest: v3.0.3**
|
|
16
|
+
|
|
17
|
+
27 tools, 20 skills, 1673+ checkpoints across 11 audit dimensions. Works with any AI platform (Claude Code, Cursor, Windsurf, Copilot...) through the Model Context Protocol.
|
|
18
|
+
|
|
19
|
+
## What is KARUKIA?
|
|
20
|
+
|
|
21
|
+
KARUKIA is a structured development methodology built around specialized AI personas. Each persona (Neo for security, Jeffrey for architecture, Viper for pentesting, Opo for quality...) comes with its own workflow, guard rails, and knowledge base.
|
|
22
|
+
|
|
23
|
+
When you call a KARUKIA tool, the MCP server returns a complete prompt — persona identity, workflow, checklists, templates — that transforms your AI assistant into that specialist for the session.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
You: "Run a security audit"
|
|
27
|
+
-> AI calls neo tool
|
|
28
|
+
-> MCP returns full Neo persona prompt + 445 security controls inline
|
|
29
|
+
-> AI becomes Neo, follows the methodology, produces structured findings
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## The 11 Audit Dimensions
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
SECURITY → Neo (445 pts) "Is my code secure?"
|
|
36
|
+
QUALITY → Opquast (245 pts) "Is my app well-built?"
|
|
37
|
+
OFFENSIVE → Viper (245+ tests) "How would a hacker break in?"
|
|
38
|
+
TS → ts_quality (118) "Is my TypeScript clean?"
|
|
39
|
+
CSS → css_quality (55) "Is my design system maintainable?"
|
|
40
|
+
ARCHI → archi (70) "Is my architecture sound?"
|
|
41
|
+
TESTS → test_coverage (68) "Am I testing the right things?"
|
|
42
|
+
PERF → perf (90) "Where are the bottlenecks?"
|
|
43
|
+
DEBT → debt (55) "What's slowing us down?"
|
|
44
|
+
HDS/ISO → audit_expert (200+)"Am I ready for certification?"
|
|
45
|
+
SCAN → karukia_scan "Run all 11 dimensions at once"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Quick Start
|
|
51
|
+
|
|
52
|
+
**Prerequisites:** [Node.js](https://nodejs.org/) 22 or later.
|
|
53
|
+
|
|
54
|
+
### Step 1 — Add KARUKIA to your project
|
|
55
|
+
|
|
56
|
+
Create or edit `.mcp.json` at the root of your project:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"karukia": {
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": ["karukia-mcp"]
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
> **Note:** If the file already exists and has other MCP servers, just add the `"karukia"` key inside the existing `"mcpServers"` object.
|
|
70
|
+
|
|
71
|
+
### Step 2 — Restart your AI client
|
|
72
|
+
|
|
73
|
+
Restart Claude Code (`/quit` then relaunch) or your IDE. The 27 KARUKIA tools are now available.
|
|
74
|
+
|
|
75
|
+
> On first launch, `npx` downloads the package automatically (~175 KB). Subsequent launches use the cached version.
|
|
76
|
+
|
|
77
|
+
### Step 3 — Configure your project
|
|
78
|
+
|
|
79
|
+
Tell your AI:
|
|
80
|
+
|
|
81
|
+
> "karukia install"
|
|
82
|
+
|
|
83
|
+
KARUKIA scans your project, detects your stack, and generates configuration files (security scope, CLAUDE.md, memory structure).
|
|
84
|
+
|
|
85
|
+
### Step 4 — Start working
|
|
86
|
+
|
|
87
|
+
Just describe what you need in natural language:
|
|
88
|
+
|
|
89
|
+
> "karukia: add user authentication"
|
|
90
|
+
> "karukia: audit security"
|
|
91
|
+
> "karukia: run a pentest"
|
|
92
|
+
|
|
93
|
+
The orchestrator (`auto`) analyzes your request and routes to the right specialists automatically.
|
|
94
|
+
|
|
95
|
+
> **Tip:** You only need two commands: `karukia install` (once) then `karukia` + your request (always). For direct control, ask for a specific skill: "karukia neo", "karukia viper", "karukia jeffrey". Say "karukia start" anytime for a full guide.
|
|
96
|
+
|
|
97
|
+
### Where to put the config
|
|
98
|
+
|
|
99
|
+
| Client | File | Scope |
|
|
100
|
+
|--------|------|-------|
|
|
101
|
+
| **Claude Code CLI** | `.mcp.json` at project root | This project only |
|
|
102
|
+
| **Claude Code CLI** | `~/.claude.json` (home directory) | All your projects |
|
|
103
|
+
| **Claude Desktop** | `claude_desktop_config.json` | Global |
|
|
104
|
+
| **Cursor** | `.cursor/mcp.json` at project root | This project only |
|
|
105
|
+
| **Windsurf** | MCP settings panel | Global |
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Global Installation (optional)
|
|
110
|
+
|
|
111
|
+
If you want KARUKIA available in all your projects without adding `.mcp.json` each time:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npm install -g karukia-mcp
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Then add to your global AI config (`~/.claude.json` for Claude Code):
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"mcpServers": {
|
|
122
|
+
"karukia": {
|
|
123
|
+
"command": "karukia-mcp"
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## 27 Tools
|
|
132
|
+
|
|
133
|
+
### Essential (start here)
|
|
134
|
+
|
|
135
|
+
| Tool | Description |
|
|
136
|
+
|------|-------------|
|
|
137
|
+
| `install` | **[FIRST STEP]** Configure KARUKIA for your project — run once |
|
|
138
|
+
| `auto` | **[MAIN TOOL]** Describe what you need — KARUKIA routes to the right skills |
|
|
139
|
+
| `start` | Quick-start guide — explains all skills at 3 progressive levels |
|
|
140
|
+
|
|
141
|
+
### Core Skills (AI Personas)
|
|
142
|
+
|
|
143
|
+
Each skill returns a complete prompt that transforms your AI into a specialist.
|
|
144
|
+
|
|
145
|
+
| Tool | Persona | What it does |
|
|
146
|
+
|------|---------|-------------|
|
|
147
|
+
| `neo` | Security Auditor | Defensive audit against 6 frameworks (OWASP, HDS, ISO 27001, SOC 2, PCI-DSS, HIPAA) |
|
|
148
|
+
| `viper` | Pentest Brigade | Offensive testing with 16 agents, CVSS v4 scoring, MITRE ATT&CK mapping |
|
|
149
|
+
| `jeffrey` | Full-Stack Architect | Feature implementation with TDD and security validation |
|
|
150
|
+
| `opo` | Quality Validator | Web quality against 245 Opquast rules |
|
|
151
|
+
| `audit_opquast` | Quality Auditor | Deep Opquast compliance audit with 14 thematic checklists |
|
|
152
|
+
| `ebios_rm_audit` | Risk Analyst | EBIOS Risk Manager methodology (ANSSI) — formal risk analysis |
|
|
153
|
+
| `security_hardening` | Hardening Planner | Security improvement chantiers |
|
|
154
|
+
| `doc_refactor` | Doc Auditor | Documentation accuracy audit vs actual code |
|
|
155
|
+
|
|
156
|
+
### Dimensional Skills (v3.0 New)
|
|
157
|
+
|
|
158
|
+
| Tool | Checkpoints | What it does |
|
|
159
|
+
|------|-------------|-------------|
|
|
160
|
+
| `ts_quality` | 118 | TypeScript audit — type safety, strict config, generics, async patterns |
|
|
161
|
+
| `css_quality` | 55 | CSS/Design System — maintainability, accessibility, metrics |
|
|
162
|
+
| `archi` | 70 | Architecture — module structure, coupling, layering |
|
|
163
|
+
| `test_coverage` | 68 | Test inventory — frontend/backend coverage quality |
|
|
164
|
+
| `perf` | 90 | Performance — frontend, backend, build/bundle |
|
|
165
|
+
| `debt` | 55 | Technical debt — dead code, dependency health, code smells |
|
|
166
|
+
| `karukia_scan` | 1673+ | **Global scan** — all 11 dimensions in parallel |
|
|
167
|
+
| `audit_expert_hds` | 200+ | Expert HDS 2.0/ISO 27001 — 8 domains, certification readiness |
|
|
168
|
+
| `change_report` | — | Change management report (ISO 27001 A.8.32) |
|
|
169
|
+
|
|
170
|
+
### Utilities
|
|
171
|
+
|
|
172
|
+
| Tool | Description |
|
|
173
|
+
|------|-------------|
|
|
174
|
+
| `list_checklists` | Browse all 31 checklists by category |
|
|
175
|
+
| `suggest_checklists` | Describe your project — get a prioritized audit plan |
|
|
176
|
+
| `generate_report` | Compile audit results into a scored Markdown report |
|
|
177
|
+
|
|
178
|
+
### Memory & Config
|
|
179
|
+
|
|
180
|
+
| Tool | Description |
|
|
181
|
+
|------|-------------|
|
|
182
|
+
| `init_memory` | Initialize KARUKIA memory structure in a project |
|
|
183
|
+
| `get_session_template` | Get pre-filled session templates for any skill |
|
|
184
|
+
| `get_config_template` | Get configuration templates (security scope, CLAUDE.md, analytics) |
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 31 Checklists
|
|
189
|
+
|
|
190
|
+
### Defensive Security (Neo) — 6 checklists, 445 controls
|
|
191
|
+
|
|
192
|
+
| Checklist | Points | Scope |
|
|
193
|
+
|-----------|--------|-------|
|
|
194
|
+
| **OWASP Security Baseline** | 62 | Every web app |
|
|
195
|
+
| **HDS 2.0** | 52 | Health data, France |
|
|
196
|
+
| **ISO 27001:2022** | 93 | Enterprise ISMS |
|
|
197
|
+
| **SOC 2 Type II** | 74 | SaaS, US market |
|
|
198
|
+
| **PCI-DSS v4.0** | 97 | Payment processing |
|
|
199
|
+
| **HIPAA** | 67 | Health data, US |
|
|
200
|
+
|
|
201
|
+
### Web Quality (Opquast) — 14 checklists, 245 rules
|
|
202
|
+
|
|
203
|
+
Content, personal data, e-commerce, forms, identity, images, internationalization, links, navigation, newsletter, presentation, security UX, server performance, and code structure.
|
|
204
|
+
|
|
205
|
+
Based on [Opquast](https://www.opquast.com/) — the French web quality reference used by 15,000+ professionals.
|
|
206
|
+
|
|
207
|
+
### Offensive Security (Viper) — 4 checklists, 245+ tests
|
|
208
|
+
|
|
209
|
+
| Checklist | Tests | Scope |
|
|
210
|
+
|-----------|-------|-------|
|
|
211
|
+
| **OWASP WSTG v5** | 100 | Web penetration testing |
|
|
212
|
+
| **Cloud Platform** | 80+ | Firebase, GCP, AWS, Azure |
|
|
213
|
+
| **Healthcare** | 50+ | PHI, encryption, medical data |
|
|
214
|
+
| **Attack Scenarios** | 15+ | PTES templates, MITRE ATT&CK |
|
|
215
|
+
|
|
216
|
+
### Dimensional Quality (New in v3.0) — 7 checklists, 656+ checkpoints
|
|
217
|
+
|
|
218
|
+
| Checklist | Points | Scope |
|
|
219
|
+
|-----------|--------|-------|
|
|
220
|
+
| **TypeScript Quality** | 118 | Type safety, strict config, patterns |
|
|
221
|
+
| **CSS / Design System** | 55 | Maintainability, a11y, metrics |
|
|
222
|
+
| **Architecture** | 70 | Module structure, coupling, layering |
|
|
223
|
+
| **Test Coverage** | 68 | Frontend/backend inventory, quality |
|
|
224
|
+
| **Performance** | 90 | Frontend, backend, build/bundle |
|
|
225
|
+
| **Technical Debt** | 55 | Dead code, deps, code smells |
|
|
226
|
+
| **Expert HDS/ISO 27001** | 200+ | Certification readiness — 8 domains |
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## Usage Examples
|
|
231
|
+
|
|
232
|
+
### Full security audit
|
|
233
|
+
|
|
234
|
+
> "Run a security audit on my project"
|
|
235
|
+
|
|
236
|
+
Your AI calls `neo` — becomes the Neo security auditor — follows the methodology — produces structured findings with severity, file:line references, and remediation steps.
|
|
237
|
+
|
|
238
|
+
### Build a feature with guardrails
|
|
239
|
+
|
|
240
|
+
> "karukia jeffrey: implement user authentication"
|
|
241
|
+
|
|
242
|
+
Your AI calls `jeffrey` — becomes the Jeffrey architect — implements with TDD, then chains to Neo for security validation (rejection loop: if Neo rejects, Jeffrey fixes, max 3 iterations).
|
|
243
|
+
|
|
244
|
+
### Pentest your app
|
|
245
|
+
|
|
246
|
+
> "karukia viper"
|
|
247
|
+
|
|
248
|
+
Your AI calls `viper` — deploys the Brigade methodology with 16 specialized agents across Recon, Surface Analysis, and Exploitation phases.
|
|
249
|
+
|
|
250
|
+
### Orchestrate everything
|
|
251
|
+
|
|
252
|
+
> "karukia: add a logout button and audit security"
|
|
253
|
+
|
|
254
|
+
Your AI calls `auto` — analyzes the request — routes to the right skill(s) — manages the chain.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Documentation
|
|
259
|
+
|
|
260
|
+
- [Livre Blanc (Français)](./LIVRE-BLANC.md) — Document technique détaillé : architecture, méthodologie, cas d'usage
|
|
261
|
+
- [Whitepaper (English)](./WHITEPAPER.md) — Technical deep-dive: architecture, methodology, use cases
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## Cloud / Enterprise
|
|
266
|
+
|
|
267
|
+
KARUKIA runs locally by default (stdio via `npx`). Free, zero infrastructure.
|
|
268
|
+
|
|
269
|
+
**For teams** — a managed KARUKIA server (waitlist): connect your whole team via a single API key, centralized audit trail, consistent checklists across all developers.
|
|
270
|
+
|
|
271
|
+
→ **contact@karukia.com** to join the waitlist.
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## About
|
|
276
|
+
|
|
277
|
+
KARUKIA is developed by **[KARUK IA Solutions](https://karukia.com)**, a B2B SaaS studio specializing in regulated industries (healthcare, finance, pharma), based in Guadeloupe. 🇬🇵
|
|
278
|
+
|
|
279
|
+
Built from the experience of securing a healthcare SaaS application for HDS 2.0 / ISO 27001 certification. The methodology was made open to share what a real certification process actually requires — not just theory.
|
|
280
|
+
|
|
281
|
+
> *Made in Guadeloupe — AI doesn't replace the expert, it frees them.*
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## Why KARUKIA
|
|
286
|
+
|
|
287
|
+
KARUKIA is a structured AI-assisted development methodology built around three principles:
|
|
288
|
+
|
|
289
|
+
1. **Separation of concerns** — Security, quality, and implementation are separate disciplines handled by separate AI personas.
|
|
290
|
+
2. **Formal checkpoints over gut feeling** — 1673+ documented checkpoints beat "I think it's fine."
|
|
291
|
+
3. **Defense in depth** — Defensive audit first, quality validation second, offensive testing last.
|
|
292
|
+
|
|
293
|
+
Built from real-world experience securing a healthcare SaaS application to HDS 2.0 / ISO 27001 standards.
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Privacy & Data Handling
|
|
298
|
+
|
|
299
|
+
- **KARUKIA MCP does not store any user data server-side.** In stdio mode (default via `npx`), the server is stateless — no data leaves your machine.
|
|
300
|
+
- **Generated prompts** are returned to your AI client (Claude, GPT, Cursor, etc.). Do not include real health data, credentials, or sensitive personal information in tool call arguments (e.g., the `scope`, `task`, or `period` fields).
|
|
301
|
+
- **HTTP mode** (`start:http`): request logs contain session metadata (tool name, duration, HTTP status) but never the content of requests or generated prompts. Sensitive headers (`Authorization`, `Mcp-Session-Id`) are automatically redacted in logs.
|
|
302
|
+
- **Session memory files** (stored in `karukia/memory/sessions/` on your machine): follow the retention policy documented in [`karukia/config/session-retention.md`](./karukia/config/session-retention.md). For teams in regulated sectors: do not store real patient data or PHI in session files.
|
|
303
|
+
- **For teams in regulated sectors (healthcare, finance)**: use stdio mode (local) for maximum data isolation, or contact contact@karukia.com for the managed offering.
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## License
|
|
308
|
+
|
|
309
|
+
KARUKIA MCP is free for personal, educational, and internal professional use.
|
|
310
|
+
|
|
311
|
+
**Commercial use or resale requires written authorization.** Contact: contact@karukia.com
|
|
312
|
+
|
|
313
|
+
See [LICENSE](./LICENSE) for full terms.
|