@gnaws/mcp 0.1.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.
- package/LICENSE +661 -0
- package/README.md +170 -0
- package/dist/app.js +771 -0
- package/dist/logger.js +84 -0
- package/package.json +75 -0
package/README.md
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# @gnaws/mcp
|
|
2
|
+
|
|
3
|
+
> *Let your AI agent see what's beneath your cloud.*
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@gnaws/mcp)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](package.json)
|
|
8
|
+
|
|
9
|
+
MCP (Model Context Protocol) server for [@gnaws/core](https://www.npmjs.com/package/@gnaws/core) — expose AWS resource scanning, graph building, and unused resource detection as tools for AI agents.
|
|
10
|
+
|
|
11
|
+
## What is this?
|
|
12
|
+
|
|
13
|
+
An MCP server that gives AI agents (Claude, Kiro, Cursor, etc.) the ability to:
|
|
14
|
+
|
|
15
|
+
- **Scan** your AWS account and build a resource relationship graph
|
|
16
|
+
- **Load** previously dumped data for offline analysis
|
|
17
|
+
- **Detect** unused/orphaned resources (detached volumes, unassociated IPs, empty load balancers, etc.)
|
|
18
|
+
- **Export** the graph to GEXF (Gephi), JSON (sigma.js), or Markdown
|
|
19
|
+
- **Dump** raw resource data for later use
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install -g @gnaws/mcp
|
|
25
|
+
# or run without installing:
|
|
26
|
+
npx @gnaws/mcp
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Requires Node.js >= 24.
|
|
30
|
+
|
|
31
|
+
## MCP Client Configuration
|
|
32
|
+
|
|
33
|
+
### Kiro
|
|
34
|
+
|
|
35
|
+
Add to `.kiro/settings/mcp.json`:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"mcpServers": {
|
|
40
|
+
"gnaws": {
|
|
41
|
+
"command": "npx",
|
|
42
|
+
"args": ["@gnaws/mcp"]
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Claude Desktop
|
|
49
|
+
|
|
50
|
+
Add to `claude_desktop_config.json`:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"mcpServers": {
|
|
55
|
+
"gnaws": {
|
|
56
|
+
"command": "npx",
|
|
57
|
+
"args": ["@gnaws/mcp"]
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### VS Code (GitHub Copilot)
|
|
64
|
+
|
|
65
|
+
Add to `.vscode/mcp.json`:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"servers": {
|
|
70
|
+
"gnaws": {
|
|
71
|
+
"command": "npx",
|
|
72
|
+
"args": ["@gnaws/mcp"]
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Cursor
|
|
79
|
+
|
|
80
|
+
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"mcpServers": {
|
|
85
|
+
"gnaws": {
|
|
86
|
+
"command": "npx",
|
|
87
|
+
"args": ["@gnaws/mcp"]
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Available Tools
|
|
94
|
+
|
|
95
|
+
| Tool | Description | Requires |
|
|
96
|
+
|------|-------------|----------|
|
|
97
|
+
| `status` | Check server state (loaded? how many nodes/edges?) | — |
|
|
98
|
+
| `scan` | Scan AWS resources live with a profile | AWS credentials |
|
|
99
|
+
| `load` | Load from a dump directory (offline) | Dump path |
|
|
100
|
+
| `detect` | Find unused/orphaned resources | `scan` or `load` |
|
|
101
|
+
| `export` | Export graph to gexf/json/md | `scan` or `load` |
|
|
102
|
+
| `dump` | Save raw data for offline use | `scan` or `load` |
|
|
103
|
+
| `regions` | List enabled AWS regions | `scan` or `load` |
|
|
104
|
+
|
|
105
|
+
## Example Conversations
|
|
106
|
+
|
|
107
|
+
> **User:** Show me the unused resources in my AWS account
|
|
108
|
+
> **Agent:** calls `scan` with profile → calls `detect` → presents findings
|
|
109
|
+
|
|
110
|
+
> **User:** Load the dump from ./data and export a graph
|
|
111
|
+
> **Agent:** calls `load` with path → calls `export` with format "gexf"
|
|
112
|
+
|
|
113
|
+
> **User:** What's the state of the gnaws server?
|
|
114
|
+
> **Agent:** calls `status` → reports no data loaded, suggests `scan` or `load`
|
|
115
|
+
|
|
116
|
+
## Features
|
|
117
|
+
|
|
118
|
+
- **Progress notifications** — long-running scans report progress to the agent
|
|
119
|
+
- **Error handling** — every tool returns structured errors with actionable guidance
|
|
120
|
+
- **Workflow guidance** — tool responses tell the agent what to call next
|
|
121
|
+
- **Offline mode** — load from dumps without AWS credentials
|
|
122
|
+
- **65+ AWS services** — EC2, Lambda, S3, RDS, ECS, EKS, DynamoDB, and many more
|
|
123
|
+
|
|
124
|
+
## Log Level
|
|
125
|
+
|
|
126
|
+
All logging goes to stderr (safe for MCP stdio transport). Control verbosity with:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
LOG_LEVEL=debug npx @gnaws/mcp
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Available levels: `debug`, `info`, `warn`, `error`, `silent` (default: `info`).
|
|
133
|
+
|
|
134
|
+
## Development
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
# Build
|
|
138
|
+
npm run build
|
|
139
|
+
|
|
140
|
+
# Dev mode (tsx with hot reload)
|
|
141
|
+
npm run dev
|
|
142
|
+
|
|
143
|
+
# Type-check
|
|
144
|
+
npm run typecheck
|
|
145
|
+
|
|
146
|
+
# Lint
|
|
147
|
+
npm run lint
|
|
148
|
+
|
|
149
|
+
# Test with MCP Inspector
|
|
150
|
+
npx @modelcontextprotocol/inspector npx @gnaws/mcp
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Contributing
|
|
154
|
+
|
|
155
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
156
|
+
|
|
157
|
+
## Support
|
|
158
|
+
|
|
159
|
+
If GNAWS saves you money on your AWS bill, consider sponsoring the project.
|
|
160
|
+
|
|
161
|
+
[](https://github.com/sponsors/FabioDominio)
|
|
162
|
+
[](https://paypal.me/drdominiof)
|
|
163
|
+
|
|
164
|
+
## License
|
|
165
|
+
|
|
166
|
+
AGPL-3.0 — see [LICENSE](LICENSE).
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
*Not affiliated with or endorsed by Amazon Web Services.*
|