# llm-toolkit

MCP server toolkit with payload library, WAF bypass generator, rate limiter, plugin system, and inter-MCP bridge for security testing.

> **Disclaimer:** For authorized security testing only. Obtain written permission before testing any system you do not own. Unauthorized access is illegal.

## Features

### Payload Library

80+ curated payloads across 8 vulnerability categories:

| Category | File | Description |
|----------|------|-------------|
| XSS | `payloads/xss.json` | Cross-site scripting vectors |
| SQLi | `payloads/sqli.json` | SQL injection payloads |
| SSRF | `payloads/ssrf.json` | Server-side request forgery |
| SSTI | `payloads/ssti.json` | Server-side template injection |
| LFI | `payloads/lfi.json` | Local file inclusion |
| XXE | `payloads/xxe.json` | XML external entity injection |
| CMDi | `payloads/cmdi.json` | Command injection |
| NoSQLi | `payloads/nosqli.json` | NoSQL injection |

Each payload entry includes metadata: `id`, `name`, `payload`, `category`, `context`, `riskLevel`, optional `description`, and `tags`.

### WAF Bypass Engine

Generates WAF-specific bypass variants with strategy tables per provider:

| WAF | Techniques |
|-----|-----------|
| **Cloudflare** | Unicode normalization, HTTP parameter pollution, JSON nesting, case alternation, whitespace alternatives |
| **ModSecurity** | MySQL version comments (`/*!50000...*/`), case alternation, null byte injection, whitespace alternatives, generic comment insertion |
| **AWS WAF** | Encoding chains (URL + Base64), regex evasion with character classes, deep JSON nesting, Unicode fullwidth, token breaker |
| **Generic** | Case mutation, whitespace mutation, comment injection, URL/hex/base64/HTML entity encoding, token breaker, Unicode mutation |

Also includes payload type detection (XSS, SQLi, SSTI, XXE, SSRF, LFI, CMDi, NoSQLi) and bypass strategy suggestions.

### Payload Generator

Six mutation types that can be applied individually or chained:

| Mutation | Description |
|----------|-------------|
| `caseMutation` | Random case alternation per character |
| `whitespaceMutation` | Replace spaces with `%09`, `%0a`, `%0b`, `%0c`, `%0d`, `%a0` |
| `commentMutation` | Insert SQL comments between characters (`/**/`) or MySQL style (`/*!50000...*/`) |
| `encodingMutation` | URL, hex, Base64, or HTML entity encoding |
| `tokenBreaker` | Split keywords at random positions with encoded delimiters |
| `unicodeMutation` | Fullwidth Unicode character substitution |

### Rate Limiter

Token bucket implementation with configurable limits. Defaults to 20 requests per minute per client. Applied before every MCP tool execution.

### Plugin System

Dynamic plugin loading from `~/.llm-toolkit/plugins.json`. Plugins can register custom MCP tools, extend payload generation, or add new WAF strategies.

### Inter-MCP Bridge

Connect to other MCP servers via stdio or in-memory transport. Call remote tools, list available tools, and disconnect. Enables chaining multiple MCP servers into a single workflow.

### Content Attachments

Link reference materials (articles, videos, PDFs, tweets) to vulnerability techniques. Validates URLs are reachable and fetches content for context.

### CLI Installer

Install and manage security testing tools:

| Tool | Category | Description |
|------|----------|-------------|
| `nuclei` | Scanner | Fast vulnerability scanner based on templates |
| `subfinder` | Recon | Subdomain discovery tool |
| `httpx` | Recon | Fast HTTP toolkit |
| `ffuf` | Fuzzing | Fast web fuzzer |
| `katana` | Recon | Next-gen crawling and spidering |

Auto-detects OS (macOS via Homebrew, Linux via Go install) and installs the correct package.

## Quick Start

### Prerequisites

- Node.js 20+
- npm

### Install

```bash
npm install
```

### Development

```bash
npm run dev        # tsup watch mode
npm run typecheck  # TypeScript type checking (strict mode)
```

### Build

```bash
npm run build      # tsup ESM output to dist/
```

### Test

```bash
npm test            # vitest run (48 tests)
npm run test:watch  # vitest watch mode
npm run test:coverage  # with coverage
```

### OpenCode Integration

#### Automated Setup (Recommended)

No manual config editing needed. Run one of these commands:

```bash
# Development mode — uses tsx to run source directly
npm run setup:opencode

# Production mode — uses compiled dist/index.js
npm run setup:opencode:prod
```

The script:
1. Resolves the absolute path to this project
2. Reads (or creates) `~/.config/opencode/opencode.json`
3. Adds/updates the `llm-toolkit` MCP entry automatically
4. Prints the resulting config block for verification

After setup, restart OpenCode. Tools will appear as `llm-toolkit-{tool-name}` — for example: `llm-toolkit-get-payloads`, `llm-toolkit-bypass-waf`, `llm-toolkit-health`.

#### Manual Setup

If you prefer to edit config manually, add to `~/.config/opencode/opencode.json`:

**Development Mode (source)**

```json
{
  "mcp": {
    "llm-toolkit": {
      "type": "local",
      "command": ["npx", "tsx", "/absolute/path/to/llm-toolkit/src/server.ts"],
      "cwd": "/absolute/path/to/llm-toolkit",
      "enabled": true
    }
  }
}
```

**Production Mode (build)**

```json
{
  "mcp": {
    "llm-toolkit": {
      "type": "local",
      "command": ["node", "/absolute/path/to/llm-toolkit/dist/index.js"],
      "cwd": "/absolute/path/to/llm-toolkit",
      "enabled": true
    }
  }
}
```

## MCP Server Usage

### Add to MCP Client Config

```json
{
  "mcpServers": {
    "llm-toolkit": {
      "command": "node",
      "args": ["/absolute/path/to/llm-toolkit/dist/index.js"]
    }
  }
}
```

Or use `npx` after publishing:

```json
{
  "mcpServers": {
    "llm-toolkit": {
      "command": "npx",
      "args": ["llm-toolkit"]
    }
  }
}
```

### Available Tools

| Tool | Description |
|------|-------------|
| `get-payloads` | Fetch payloads from a JSON file with optional filters (category, context, riskLevel) |
| `generate-payload` | Generate payload variants with mutations |
| `bypass-waf` | Generate WAF-specific bypass variants |
| `analyze-payload` | Analyze a payload to detect attack type and suggest bypass strategies |
| `encode` | Encode data (url, doubleUrl, hex, base64, htmlEntity, unicode) |
| `decode` | Decode data (url, hex, base64, htmlEntity, unicode, jwt) |
| `jwt-encode` | Create JWT tokens with optional secret and algorithm |
| `fetch-reference` | Fetch content from a URL reference |
| `validate-reference` | Validate that a content reference URL is reachable |
| `connect-mcp` | Connect to another MCP server via stdio transport |
| `call-mcp-tool` | Call a tool on a connected MCP server |
| `list-mcp-tools` | List tools available on a connected MCP server |
| `disconnect-mcp` | Disconnect from an MCP server |
| `list-connected-servers` | List all connected MCP servers |

### Example Tool Calls

**Fetch XSS payloads filtered by risk level:**

```json
{
  "name": "get-payloads",
  "arguments": {
    "filepath": "payloads/xss.json",
    "filters": { "riskLevel": "high" }
  }
}
```

**Generate payload variants with chained mutations:**

```json
{
  "name": "generate-payload",
  "arguments": {
    "payload": "<script>alert(1)</script>",
    "options": {
      "mutations": ["caseMutation", "whitespaceMutation", "commentMutation"],
      "chainMutations": true,
      "encoding": "url"
    }
  }
}
```

**Generate Cloudflare bypass variants:**

```json
{
  "name": "bypass-waf",
  "arguments": {
    "payload": "' OR 1=1 --",
    "wafType": "cloudflare"
  }
}
```

**Analyze a payload:**

```json
{
  "name": "analyze-payload",
  "arguments": {
    "payload": "{{7*7}}"
  }
}
```

**Connect to another MCP server and call a tool:**

```json
{
  "name": "connect-mcp",
  "arguments": {
    "command": "npx",
    "args": ["-y", "@some/mcp-server"],
    "name": "remote-server"
  }
}
```

## CLI Usage

```bash
# List available security tools
llm-toolkit list

# Install a specific tool
llm-toolkit install nuclei
llm-toolkit install subfinder
llm-toolkit install httpx
llm-toolkit install ffuf
llm-toolkit install katana

# Check what's installed
llm-toolkit status

# Uninstall a tool
llm-toolkit uninstall nuclei

# Start MCP server directly
llm-toolkit
# or
node dist/cli.js
```

## Architecture

```
llm-toolkit/
├── src/
│   ├── index.ts              # Package entry point, exports
│   ├── server.ts             # Core MCP server, StreamableHTTP transport
│   ├── cli.ts                # CLI installer (nuclei, subfinder, etc.)
│   ├── encoding.ts           # Encode/decode utils (URL, hex, base64, HTML, Unicode, JWT)
│   ├── rate-limiter.ts       # Token bucket per client (20 req/min default)
│   ├── generator.ts          # Payload variant generator (6 mutation types)
│   ├── waf-bypass.ts         # WAF-specific bypass engine (CF, ModSec, AWS, Generic)
│   ├── plugin-manager.ts     # Dynamic plugin loading from ~/.llm-toolkit/plugins.json
│   ├── inter-mcp.ts          # Bridge to other MCP servers (StdioClientTransport)
│   ├── content-fetcher.ts    # Fetch/validate content references (articles, videos, PDFs)
│   └── tools/
│       └── index.ts          # MCP tool handlers (14 tools registered)
├── payloads/
│   ├── xss.json              # XSS payloads
│   ├── sqli.json             # SQLi payloads
│   ├── ssrf.json             # SSRF payloads
│   ├── ssti.json             # SSTI payloads
│   ├── lfi.json              # LFI payloads
│   ├── xxe.json              # XXE payloads
│   ├── cmdi.json             # Command injection payloads
│   └── nosqli.json           # NoSQLi payloads
├── tests/                    # Vitest test suite (48 tests)
├── scripts/                  # Build and utility scripts
├── dist/                     # tsup build output
│   ├── index.js              # ESM library entry
│   └── cli.js                # CLI binary entry
├── package.json
├── tsconfig.json
└── tsup.config.ts
```

## Payload JSON Schema

Each payload file is a JSON array of entries:

```json
[
  {
    "id": "xss-001",
    "name": "Basic script tag",
    "payload": "<script>alert('XSS')</script>",
    "category": "xss",
    "context": "unescaped HTML output",
    "riskLevel": "high",
    "description": "Standard script tag injection for reflected XSS",
    "tags": ["reflected", "script-tag", "alert"]
  }
]
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique identifier |
| `name` | string | Yes | Human-readable name |
| `payload` | string | Yes | The actual payload string |
| `category` | string | Yes | Vulnerability category |
| `context` | string | Yes | Where this payload applies |
| `riskLevel` | string | Yes | `low`, `medium`, `high`, `critical` |
| `description` | string | No | Explanation of the payload |
| `tags` | string[] | No | Classification tags |

## Extending

### Add New Payloads

Create a JSON file in `payloads/` following the schema above. Load it via `get-payloads` with the file path.

### Add Mutation Types

Edit `src/generator.ts`:

1. Add a new mutation function: `export function myMutation(str: string): string { ... }`
2. Add the type name to the `MutationType` union
3. Register it in the `mutationFn` record

### Add WAF Bypass Strategies

Edit `src/waf-bypass.ts`:

1. Create a `BypassStrategy[]` array for your WAF
2. Add it to the `WAF_STRATEGIES` record with a `WafType` key

### Create Plugins

Create `~/.llm-toolkit/plugins.json`:

```json
[
  {
    "name": "my-plugin",
    "path": "/path/to/plugin.js",
    "enabled": true
  }
]
```

Plugins export an object with a `register(server: McpServer)` method to add custom tools.

## Development

### Tech Stack

- **Runtime:** Node.js 20+, ESM module
- **Language:** TypeScript (strict mode)
- **Build:** tsup (outputs ESM to `dist/`)
- **Test:** Vitest (48 tests)
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.25.0
- **Validation:** Zod ^3.25.0

### Commands

```bash
npm install         # Install dependencies
npm run build       # Build with tsup
npm run dev         # Watch mode rebuild
npm run typecheck   # Type check (strict mode)
npm test            # Run test suite
npm run test:watch  # Watch mode tests
npm run test:coverage  # Run with coverage
npm start           # Start MCP server
```

### Project Structure Conventions

- All source in `src/`, compiled to `dist/`
- Payload JSON files in `payloads/`
- Tests colocated in `tests/`
- Main entry: `dist/index.js`
- CLI binary: `llm-toolkit` resolves to `dist/cli.js`

## Security

- Payloads are for authorized testing only
- Rate limiter prevents abuse (20 req/min default, configurable)
- No secrets or credentials stored in the toolkit
- Plugin loading restricted to user-controlled config at `~/.llm-toolkit/plugins.json`
- All tool inputs validated with Zod schemas

## License

MIT

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Run the test suite (`npm test`)
5. Ensure type checking passes (`npm run typecheck`)
6. Commit with a descriptive message
7. Push to your fork and open a Pull Request

### Guidelines

- Keep payloads focused on practical, tested vectors
- Write tests for new mutations or WAF strategies
- Follow existing TypeScript strict patterns
- No `any` types without justification
- Keep tool handlers under 30 lines where possible