Content
# Taco MCP
Node.js MCP server for frontend security reconnaissance and web JavaScript reverse analysis.
[中文文档](./README.zh-CN.md)
It focuses on **authorized** assessment workflows: static-first asset collection, optional browser enrichment for SPA runtime resources, secret/API surface extraction, technology fingerprinting, and structured security leads. Findings are **leads for verification**, not automatically confirmed vulnerabilities.
## Legal Notice
**You must have lawful authorization from the owner of the target system/assets before using this project.**
- This project is intended only for lawful purposes such as authorized security research, enterprise bug bounty / SRC programs, red-blue exercises, and assessment of assets you own or are explicitly permitted to test.
- **Unauthorized access, intrusion, disruption, data theft, or any illegal activity is strictly prohibited.**
- You are solely responsible for ensuring your use complies with applicable laws and the scope of your authorization.
- **Any consequences arising from unauthorized, unlawful, or abusive use are solely the responsibility of the user. The author(s) and contributors assume no liability.**
- By downloading, installing, running, or distributing this project, you acknowledge and agree to this notice.
## Features
- stdio MCP server (Node.js 18+)
- Static-first URL collection with optional Playwright browser enrichment
- Built-in SSRF protections (blocks localhost / private IPs / cloud metadata / non-http(s))
- Recon tools:
- `taco_map_stack`
- `taco_hunt_secrets`
- `taco_review_front`
- `taco_read_banner`
- `taco_pull_sources`
- JS reverse tools:
- `reverse_analyze_source`
- `reverse_analyze_url`
- `reverse_api_contracts`
- `reverse_security_leads`
- `reverse_mining_roadmap`
- `reverse_runtime_hook`
- `reverse_fast_verify_plan`
## Collection modes
| mode | behavior |
|------|----------|
| `static` | Node fetch only |
| `browser` | Playwright only |
| `auto` | static baseline, then conditional browser enrichment for SPA / module / incomplete static results |
`auto` merges static + browser results with static sources preferred.
## Install
```bash
npm install
```
Optional browser support:
```bash
npx playwright install chromium
```
## Run
```bash
npm start
# or
node src/index.js
```
Self-test:
```bash
npm run self-test
```
Tests:
```bash
npm test
```
## MCP client config example
```json
{
"mcpServers": {
"taco-mcp": {
"command": "node",
"args": ["/absolute/path/to/taco-mcp/src/index.js"]
}
}
}
```
Windows example:
```json
{
"mcpServers": {
"taco-mcp": {
"command": "node",
"args": ["C:/path/to/taco-mcp/src/index.js"]
}
}
}
```
## Suggested workflow
1. Prefer `source` mode when you already have frontend JS:
- `taco_review_front({ source })`
- `reverse_analyze_source({ source })`
2. For a live URL, start with static collection:
- `taco_pull_sources({ url, mode: "static" })`
3. Use `mode: "auto"` when SPA / dynamic chunks may be missing.
4. Prioritize `fast_verify_plan` items for minimal, authorized verification.
## Safety boundaries
- Outputs are static/runtime **leads**, not confirmed vulns by themselves.
- SourceMap presence, version strings, missing security headers, console logs, or suspected keys still require authorized proof-of-impact.
- Network access is constrained by SSRF policy.
- This project is intended for **authorized security testing only**.
- Do **not** use it to attack systems without permission. Any illegal use is solely the user's responsibility and has nothing to do with the author(s)/contributors.
## Project layout
```text
src/
collectors/ # static + browser collection
engines/ # leak / sniff / fingerprint / reverse / audit
rules/ # detection rules
tools/ # MCP tool definitions & handlers
utils/ # SSRF policy, output helpers, source-map
tests/ # node:test suite
```
