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

npm install

Development

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

Build

npm run build      # tsup ESM output to dist/

Test

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:

# 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)

{
  "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)

{
  "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

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

Or use npx after publishing:

{
  "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:

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

Generate payload variants with chained mutations:

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

Generate Cloudflare bypass variants:

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

Analyze a payload:

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

Connect to another MCP server and call a tool:

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

CLI Usage

# 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:

[
  {
    "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:

[
  {
    "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

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