@cocaxcode/ai-context-inspector 0.2.0 → 0.3.0

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.
Files changed (5) hide show
  1. package/README.md +330 -76
  2. package/dist/{chunk-UFTX3Z5M.js → chunk-T5N3KKUJ.js} +1068 -93
  3. package/dist/index.js +2 -2
  4. package/dist/{server-AOHGLJDI.js → server-EMQUALI5.js} +1 -1
  5. package/package.json +3 -2
package/README.md CHANGED
@@ -1,126 +1,380 @@
1
- # @cocaxcode/ai-context-inspector
1
+ <p align="center">
2
+ <h1 align="center">@cocaxcode/ai-context-inspector</h1>
3
+ <p align="center">
4
+ <strong>See everything your AI tools know about your project.</strong><br/>
5
+ 19 AI tools &middot; 6 scanners &middot; 3 MCP tools &middot; Dual mode: CLI + MCP server
6
+ </p>
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/@cocaxcode/ai-context-inspector"><img src="https://img.shields.io/npm/v/@cocaxcode/ai-context-inspector.svg?style=flat-square&color=cb3837" alt="npm version" /></a>
11
+ <a href="https://www.npmjs.com/package/@cocaxcode/ai-context-inspector"><img src="https://img.shields.io/npm/dm/@cocaxcode/ai-context-inspector.svg?style=flat-square" alt="npm downloads" /></a>
12
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License" /></a>
13
+ <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node" />
14
+ <img src="https://img.shields.io/badge/AI%20tools-19%20supported-blueviolet?style=flat-square" alt="19 AI tools" />
15
+ <img src="https://img.shields.io/badge/tests-33-brightgreen?style=flat-square" alt="33 tests" />
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="#the-problem">The Problem</a> &middot;
20
+ <a href="#the-solution">The Solution</a> &middot;
21
+ <a href="#installation">Installation</a> &middot;
22
+ <a href="#cli-usage">CLI Usage</a> &middot;
23
+ <a href="#mcp-server">MCP Server</a> &middot;
24
+ <a href="#what-it-detects">What It Detects</a> &middot;
25
+ <a href="#html-dashboard">HTML Dashboard</a> &middot;
26
+ <a href="#architecture">Architecture</a>
27
+ </p>
28
+
29
+ ---
30
+
31
+ ## The Problem
32
+
33
+ Your project has AI configuration scattered everywhere:
34
+
35
+ - `CLAUDE.md` with project instructions, `.cursorrules` with coding rules, `AGENTS.md` with universal guidelines
36
+ - MCP servers configured in `.mcp.json`, `~/.claude.json`, `.vscode/mcp.json` — each with different tools
37
+ - Custom skills installed via `npx skills add`, custom agents in `~/.claude/agents/`
38
+ - Persistent memories in engram, Claude memory files, agent-specific memory stores
39
+ - **You don't know the full picture.** Each tool sees only its own slice.
40
+
41
+ ## The Solution
42
+
43
+ **AI Context Inspector** scans your entire AI ecosystem in one shot:
2
44
 
3
- [![npm](https://img.shields.io/npm/v/@cocaxcode/ai-context-inspector)](https://www.npmjs.com/package/@cocaxcode/ai-context-inspector)
4
- [![tests](https://img.shields.io/badge/tests-33%20passing-brightgreen)]()
5
- [![tools](https://img.shields.io/badge/AI%20tools-13%20supported-blue)]()
6
- [![license](https://img.shields.io/badge/license-MIT-green)]()
45
+ ```bash
46
+ npx @cocaxcode/ai-context-inspector
47
+ ```
7
48
 
8
- **Escanea cualquier proyecto para descubrir su ecosistema AI completo.** MCP servers, tools, archivos de contexto, skills, memorias — todo en un dashboard HTML interactivo.
49
+ It discovers **every** AI configuration file, MCP server (with live introspection), installed skill, custom agent, and persistent memory — then generates a beautiful HTML dashboard or exposes the data as an MCP server for your AI tools to consume.
9
50
 
10
- ## El problema
51
+ **Zero config. Zero dependencies.** Just run it.
11
52
 
12
- Tu proyecto tiene archivos de configuración AI dispersos: `CLAUDE.md`, `.cursorrules`, `.mcp.json`, `.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`... y no sabes exactamente qué tienes disponible ni qué tools exponen tus MCP servers.
53
+ ---
13
54
 
14
- ## La solución
55
+ ## Installation
56
+
57
+ ### CLI (one-shot, no install)
15
58
 
16
59
  ```bash
17
60
  npx @cocaxcode/ai-context-inspector
18
61
  ```
19
62
 
20
- Genera un **dashboard HTML interactivo** que muestra:
21
- - Todos los archivos de configuración AI encontrados (13 herramientas soportadas)
22
- - MCP servers configurados con sus tools, resources y prompts (introspección real)
23
- - Skills disponibles
24
- - Sistemas de memoria (engram, openspec, .atl)
25
-
26
- ## Instalacion
63
+ ### Claude Code (MCP server)
27
64
 
28
65
  ```bash
29
- # Uso directo (sin instalar)
30
- npx @cocaxcode/ai-context-inspector
66
+ claude mcp add ai-context-inspector -- npx -y @cocaxcode/ai-context-inspector@latest --mcp
67
+ ```
31
68
 
32
- # Instalar globalmente
33
- npm install -g @cocaxcode/ai-context-inspector
69
+ Or add to your `.mcp.json`:
34
70
 
35
- # Como MCP server en tu proyecto
36
- # .mcp.json:
71
+ ```json
37
72
  {
38
73
  "mcpServers": {
39
74
  "ai-context-inspector": {
75
+ "type": "stdio",
40
76
  "command": "npx",
41
- "args": ["-y", "@cocaxcode/ai-context-inspector", "--mcp"]
77
+ "args": ["-y", "@cocaxcode/ai-context-inspector@latest", "--mcp"]
42
78
  }
43
79
  }
44
80
  }
45
81
  ```
46
82
 
47
- ## Uso CLI
83
+ ### Claude Desktop
84
+
85
+ Add to `claude_desktop_config.json`:
86
+
87
+ ```json
88
+ {
89
+ "mcpServers": {
90
+ "ai-context-inspector": {
91
+ "command": "npx",
92
+ "args": ["-y", "@cocaxcode/ai-context-inspector@latest", "--mcp"]
93
+ }
94
+ }
95
+ }
96
+ ```
97
+
98
+ ### Cursor / Windsurf
99
+
100
+ Add to `.cursor/mcp.json` or equivalent:
101
+
102
+ ```json
103
+ {
104
+ "mcpServers": {
105
+ "ai-context-inspector": {
106
+ "command": "npx",
107
+ "args": ["-y", "@cocaxcode/ai-context-inspector@latest", "--mcp"]
108
+ }
109
+ }
110
+ }
111
+ ```
112
+
113
+ ### Codex CLI
114
+
115
+ ```bash
116
+ codex mcp add ai-context-inspector -- npx -y @cocaxcode/ai-context-inspector@latest --mcp
117
+ ```
118
+
119
+ ### VS Code
120
+
121
+ Add to `.vscode/mcp.json`:
122
+
123
+ ```json
124
+ {
125
+ "servers": {
126
+ "ai-context-inspector": {
127
+ "type": "stdio",
128
+ "command": "npx",
129
+ "args": ["-y", "@cocaxcode/ai-context-inspector@latest", "--mcp"]
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ ---
136
+
137
+ ## CLI Usage
48
138
 
49
139
  ```bash
50
- # Escanear directorio actual y generar HTML
140
+ # Scan current directory → generates HTML report
51
141
  npx @cocaxcode/ai-context-inspector
52
142
 
53
- # Escanear otro directorio
143
+ # Scan a specific directory
54
144
  npx @cocaxcode/ai-context-inspector --dir /path/to/project
55
145
 
56
- # Output JSON (para pipes o programatico)
57
- npx @cocaxcode/ai-context-inspector --json
146
+ # Include user-level configs (~/.claude, ~/.gemini, etc.)
147
+ npx @cocaxcode/ai-context-inspector --user
58
148
 
59
- # Sin conectar a MCP servers (solo archivos)
60
- npx @cocaxcode/ai-context-inspector --no-introspect
149
+ # Enable live MCP server introspection (connects to each server)
150
+ npx @cocaxcode/ai-context-inspector --introspect
61
151
 
62
- # Incluir configuracion del usuario (~/.claude/, ~/.gemini/, etc.)
63
- npx @cocaxcode/ai-context-inspector --include-user
152
+ # Set introspection timeout (default: 10000ms)
153
+ npx @cocaxcode/ai-context-inspector --introspect --timeout 15000
64
154
 
65
- # Guardar en ruta personalizada
66
- npx @cocaxcode/ai-context-inspector --output ./reports/scan.html
155
+ # Output raw JSON instead of HTML
156
+ npx @cocaxcode/ai-context-inspector --json
157
+
158
+ # Run as MCP server (for AI tool integration)
159
+ npx @cocaxcode/ai-context-inspector --mcp
67
160
 
68
- # Timeout personalizado para introspección MCP
69
- npx @cocaxcode/ai-context-inspector --timeout 5000
161
+ # All flags combined
162
+ npx @cocaxcode/ai-context-inspector --dir ./my-project --user --introspect --timeout 15000
70
163
  ```
71
164
 
72
- ## Uso como MCP Server
165
+ ### CLI Flags Reference
166
+
167
+ | Flag | Description | Default |
168
+ |------|-------------|---------|
169
+ | `--dir <path>` | Directory to scan | `.` (current) |
170
+ | `--user` | Include user-level configs (`~/`) | `false` |
171
+ | `--introspect` | Connect to MCP servers and list tools | `false` |
172
+ | `--timeout <ms>` | Introspection timeout per server | `10000` |
173
+ | `--json` | Output JSON instead of HTML | `false` |
174
+ | `--mcp` | Run as MCP server (stdio transport) | `false` |
175
+
176
+ ---
177
+
178
+ ## MCP Server
179
+
180
+ When running as an MCP server (`--mcp`), three tools are exposed:
181
+
182
+ ### `scan`
183
+
184
+ Scan a project directory to discover its complete AI ecosystem.
185
+
186
+ **Parameters:**
187
+
188
+ | Parameter | Type | Required | Description |
189
+ |-----------|------|----------|-------------|
190
+ | `directory` | string | No | Path to scan (default: cwd) |
191
+ | `include_user` | boolean | No | Include user-level configs |
192
+ | `introspect` | boolean | No | Live-connect to MCP servers |
193
+ | `timeout` | number | No | Introspection timeout (ms) |
194
+
195
+ **Example prompt:** _"Scan this project and tell me what AI tools are configured"_
196
+
197
+ ### `introspect_mcp`
198
+
199
+ Connect to a specific MCP server and list its tools, resources, and prompts.
200
+
201
+ **Parameters:**
202
+
203
+ | Parameter | Type | Required | Description |
204
+ |-----------|------|----------|-------------|
205
+ | `command` | string | Yes* | Command to launch the server |
206
+ | `args` | string[] | No | Arguments for the command |
207
+ | `env` | object | No | Environment variables |
208
+ | `url` | string | Yes* | URL for HTTP/SSE servers |
209
+ | `transport` | string | No | `stdio` (default) or `http` |
210
+ | `timeout` | number | No | Connection timeout (ms) |
211
+
212
+ *Either `command` (stdio) or `url` (http) is required.
213
+
214
+ **Example prompt:** _"Introspect the MCP server at npx @anthropic/mcp-server-memory"_
215
+
216
+ ### `generate_report`
217
+
218
+ Generate a standalone HTML dashboard from scan results.
219
+
220
+ **Parameters:**
221
+
222
+ | Parameter | Type | Required | Description |
223
+ |-----------|------|----------|-------------|
224
+ | `directory` | string | No | Path to scan |
225
+ | `include_user` | boolean | No | Include user-level configs |
226
+ | `introspect` | boolean | No | Introspect MCP servers |
227
+ | `timeout` | number | No | Introspection timeout (ms) |
228
+
229
+ **Example prompt:** _"Generate an HTML report of my project's AI context"_
230
+
231
+ ---
73
232
 
74
- Cuando se ejecuta con `--mcp`, expone 3 tools:
233
+ ## What It Detects
75
234
 
76
- | Tool | Descripcion |
77
- |------|-------------|
78
- | `scan` | Escanea un proyecto y retorna todo el ecosistema AI como JSON |
79
- | `introspect_mcp` | Introspecciona un MCP server específico por nombre |
80
- | `generate_report` | Genera el dashboard HTML interactivo |
235
+ ### 19 AI Coding Tools
81
236
 
82
- ## Herramientas AI Soportadas (13)
237
+ | Tool | Context Files | Description |
238
+ |------|--------------|-------------|
239
+ | **Claude Code** | `CLAUDE.md`, `.claude/`, `.mcp.json` | Project instructions + MCP config |
240
+ | **Cursor** | `.cursorrules`, `.cursor/rules/`, `.cursorignore` | Rules + ignore patterns |
241
+ | **Windsurf** | `.windsurfrules`, `.windsurf/rules/` | Codeium/Windsurf rules |
242
+ | **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/agents/` | Instructions + custom agents |
243
+ | **Gemini CLI** | `GEMINI.md`, `.gemini/`, `.geminiignore` | Google Gemini config |
244
+ | **OpenAI Codex** | `AGENTS.md`, `AGENT.md`, `.codex/` | Universal agent instructions |
245
+ | **OpenCode** | `OPENCODE.md`, `.opencode/`, `opencode.json` | OpenCode CLI config |
246
+ | **Aider** | `.aider.conf.yml`, `.aiderignore` | Aider config + model settings |
247
+ | **Cline** | `.clinerules`, `.clineignore` | Cline rules (file or directory) |
248
+ | **Roo Code** | `.roo/rules/`, `.roorules`, `.rooignore` | Roo Code rules |
249
+ | **Continue.dev** | `.continuerules`, `.continue/config.yaml` | Continue rules + config |
250
+ | **Amazon Q** | `.amazonq/rules/` | Amazon Q Developer rules |
251
+ | **Augment** | `.augment/rules/`, `.augment-guidelines` | Augment Code rules |
252
+ | **Replit** | `.replit.md` | Replit Agent instructions |
253
+ | **Firebase Studio** | `.idx/airules.md` | Firebase Studio AI rules |
254
+ | **VS Code** | `.vscode/mcp.json` | VS Code MCP configuration |
255
+ | **Tabnine** | `.tabnine.yaml` | Tabnine AI config |
256
+ | **Sourcegraph** | `.sourcegraph/` | Sourcegraph Cody config |
257
+ | **Universal** | `CONVENTIONS.md` | Multi-tool conventions |
83
258
 
84
- | Herramienta | Archivos detectados |
85
- |-------------|-------------------|
86
- | **Claude** | CLAUDE.md, .claude/, .mcp.json |
87
- | **Cursor** | .cursorrules, .cursor/rules/, .cursorignore |
88
- | **Windsurf** | .windsurfrules, .windsurf/rules/ |
89
- | **GitHub Copilot** | .github/copilot-instructions.md, .github/instructions/, .github/agents/ |
90
- | **Gemini** | GEMINI.md, .gemini/ |
91
- | **OpenAI Codex** | AGENTS.md, AGENT.md, .codex/ |
92
- | **Aider** | .aider.conf.yml, .aiderignore |
93
- | **Cline** | .clinerules, .clineignore |
94
- | **Continue** | ~/.continue/ |
95
- | **Amazon Q** | .amazonq/rules/ |
96
- | **Augment** | .augment/rules/, .augment-guidelines |
97
- | **Replit** | .replit.md |
98
- | **Firebase Studio** | .idx/airules.md |
259
+ Plus **user-level configs** (`~/.claude/`, `~/.gemini/`, `~/.codex/`, `~/.continue/`, `~/.aider.conf.yml`, `~/.augment/`, `~/.github/agents/`, `~/.codeium/`, `~/.opencode/`, `~/.tabnine/`).
99
260
 
100
- Ademas detecta: `.vscode/mcp.json`, `CONVENTIONS.md`, y configuraciones a nivel de usuario (`~/.claude/`, `~/.gemini/`, etc.)
261
+ ### MCP Servers
101
262
 
102
- ## Dashboard HTML
263
+ - Discovers servers from `.mcp.json`, `~/.claude.json`, `.vscode/mcp.json`, Claude Desktop config
264
+ - Groups by source: project, user, VS Code, desktop
265
+ - **Live introspection**: connects to each server, lists tools/resources/prompts with descriptions
266
+ - Shows transport type (stdio/http/sse), command, args, environment variables
103
267
 
104
- El dashboard generado es un archivo HTML single-file:
105
- - **Zero dependencias externas** — funciona offline, sin servidor
106
- - **Dark/Light mode** automatico (respeta prefers-color-scheme)
107
- - **Busqueda global** — filtra tools, archivos y skills
108
- - **Secciones colapsables** — navega rapido por el contenido
109
- - **Preview de archivos** — ve el contenido sin abrir el editor
268
+ ### Custom Skills
110
269
 
111
- ## Arquitectura
270
+ - Scans `.claude/skills/` (project) and `~/.claude/skills/` (user)
271
+ - Follows symlinks (installed via `npx skills add`)
272
+ - Parses YAML frontmatter for name, description, triggers
273
+ - Falls back to `## Purpose` section parsing
112
274
 
275
+ ### Custom Agents
276
+
277
+ - Scans `.claude/agents/` (project) and `~/.claude/agents/` (user)
278
+ - Parses YAML frontmatter for name, description, model
279
+ - Detects if agent has persistent memory (via `~/.claude/agent-memory/`)
280
+
281
+ ### Persistent Memories
282
+
283
+ - **Claude Memory**: `~/.claude/projects/*/memory/MEMORY.md` with preview
284
+ - **Agent Memory**: `~/.claude/agent-memory/` files and directories
285
+ - **Engram**: detected as MCP server or Claude Code plugin
286
+ - **OpenSpec**: `openspec/` directory with specs and changes count
287
+ - **ATL**: `.atl/` directory with file count
288
+
289
+ ---
290
+
291
+ ## HTML Dashboard
292
+
293
+ The CLI generates a **self-contained HTML file** (no external dependencies) with:
294
+
295
+ - **Dark/light mode** — auto-detects system preference
296
+ - **Summary badges** — total MCPs, tools, files, skills, agents, memories at a glance
297
+ - **Collapsible sections** — expand/collapse each category
298
+ - **Search** — filter across all sections in real-time
299
+ - **File previews** — inline preview of context file contents
300
+ - **MCP tool details** — full tool listings with descriptions and input schemas
301
+ - **Tool badges** — color-coded by AI tool (Claude, Cursor, Copilot, etc.)
302
+
303
+ ---
304
+
305
+ ## Architecture
306
+
307
+ ```
308
+ src/
309
+ ├── index.ts # Entry: CLI vs MCP mode routing
310
+ ├── cli.ts # CLI arg parsing + orchestration
311
+ ├── server.ts # createServer() MCP factory
312
+ ├── scanner/
313
+ │ ├── types.ts # All TypeScript interfaces
314
+ │ ├── catalog.ts # AI_FILE_CATALOG (50+ entries, 19 tools)
315
+ │ ├── index.ts # runAllScanners() orchestrator
316
+ │ ├── context-files.ts # Scan context files (.md, rules, configs)
317
+ │ ├── mcp-configs.ts # Parse .mcp.json, ~/.claude.json, etc.
318
+ │ ├── mcp-introspect.ts # Connect to MCP servers, list tools/resources
319
+ │ ├── skills.ts # Scan skill directories + parse frontmatter
320
+ │ ├── agents.ts # Scan agent directories + detect memory
321
+ │ └── memories.ts # Detect engram, openspec, .atl, claude memory
322
+ ├── report/
323
+ │ ├── generator.ts # generateHtml(ScanResult) → string
324
+ │ ├── sections.ts # HTML section renderers
325
+ │ ├── styles.ts # CSS (dark/light mode)
326
+ │ └── scripts.ts # JS (collapse, search, preview)
327
+ ├── tools/
328
+ │ ├── scan.ts # MCP tool: scan project
329
+ │ ├── introspect.ts # MCP tool: introspect specific MCP
330
+ │ └── report.ts # MCP tool: generate HTML report
331
+ └── __tests__/
332
+ ├── fixtures/ # Test projects (full, empty, mcp-only)
333
+ ├── helpers.ts # fixture() path helper
334
+ └── *.test.ts # 7 test files, 33 tests
113
335
  ```
114
- Scanner modular → ScanResult (JSON) → HTML Dashboard
115
- ↑ ↑ ↑
116
- 5 scanners Usado por CLI Template literals
117
- en paralelo y MCP tools CSS/JS inline
336
+
337
+ ### 6 Parallel Scanners
338
+
339
+ | Scanner | Detects | Sources |
340
+ |---------|---------|---------|
341
+ | `context-files` | Config files for 19 AI tools | Project + user dirs |
342
+ | `mcp-configs` | MCP server definitions | `.mcp.json`, `~/.claude.json`, VS Code, Desktop |
343
+ | `mcp-introspect` | Live tool/resource/prompt listings | stdio/http connections |
344
+ | `skills` | Custom Claude Code skills | `.claude/skills/` + symlinks |
345
+ | `agents` | Custom Claude Code agents | `.claude/agents/` + memory detection |
346
+ | `memories` | Persistent memory systems | engram, openspec, .atl, claude memory |
347
+
348
+ All scanners run in parallel via `Promise.all()` for maximum speed.
349
+
350
+ ---
351
+
352
+ ## Stack
353
+
354
+ - **TypeScript 5.x** — strict mode, ESM
355
+ - **@modelcontextprotocol/sdk** — MCP client + server
356
+ - **Zod** — schema validation for MCP tool inputs
357
+ - **tsup** — build (ESM output with shebang)
358
+ - **Vitest** — testing (33 tests)
359
+
360
+ **Zero runtime dependencies** beyond MCP SDK and Zod.
361
+
362
+ ---
363
+
364
+ ## Contributing
365
+
366
+ ```bash
367
+ git clone https://github.com/cocaxcode/ai-context-inspector.git
368
+ cd ai-context-inspector
369
+ npm install
370
+ npm test # Run all tests
371
+ npm run build # Build with tsup
372
+ npm run typecheck # TypeScript check
373
+ npm run lint # ESLint
118
374
  ```
119
375
 
120
- - **33 tests** | **3 MCP tools** | **13 AI tools** | **40+ archivos detectados**
121
- - TypeScript 5.x + ESM + Node 20+
122
- - Zero runtime dependencies beyond MCP SDK + Zod
376
+ ---
123
377
 
124
378
  ## License
125
379
 
126
- MIT
380
+ MIT &copy; [cocaxcode](https://github.com/cocaxcode)