# spectral

MCP server for website reconnaissance. Gives Claude the ability to fingerprint tech stacks, audit security headers, map endpoints, analyze SSL certificates, enumerate DNS records, and scan ports.

## Install

```bash
git clone https://github.com/zohaiblazuli/spectral.git
cd spectral
npm install
```

## Setup with Claude Desktop

Add this to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "spectral": {
      "command": "node",
      "args": ["/absolute/path/to/spectral/bin/spectral.js"]
    }
  }
}
```

Restart Claude Desktop. You'll see 6 new tools available.

## Setup with Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "spectral": {
      "command": "node",
      "args": ["/absolute/path/to/spectral/bin/spectral.js"]
    }
  }
}
```

## Tools

### `analyze_url`

Fingerprints a website's tech stack from response headers and HTML content.

Detects:
- Frameworks: React, Next.js, Vue, Nuxt, Angular, Svelte, Remix, Astro, jQuery
- CMS: WordPress, Drupal, Shopify, Squarespace, Wix, Ghost, Webflow
- CDN: Cloudflare, Fastly, Akamai, CloudFront, Vercel, Netlify
- Analytics: Google Analytics, GTM, Segment, Hotjar, Mixpanel, Plausible, PostHog
- Servers: nginx, Apache, Express, IIS, LiteSpeed, Caddy, Deno
- Security: reCAPTCHA, hCaptcha, Cloudflare Turnstile

```
> analyze_url({ url: "vercel.com" })

Tech Stack Report: https://vercel.com/
Status: 200

frameworks: React, Next.js
cdn: Vercel
analytics: Google Analytics

Server: not disclosed
X-Powered-By: not disclosed
```

### `check_headers`

Audits security headers and returns a letter grade (A through F).

Checks: Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, X-XSS-Protection, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy.

```
> check_headers({ url: "github.com" })

Security Header Audit: https://github.com/
Grade: A

[PASS] Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
[PASS] Content-Security-Policy: Set (428 chars). Directives look reasonable.
[PASS] X-Content-Type-Options: nosniff
[PASS] X-Frame-Options: deny
[PASS] Referrer-Policy: strict-origin-when-cross-origin
[INFO] Permissions-Policy: Not set — all browser features available by default.
[INFO] X-XSS-Protection: Not set — fine if CSP is present.
[INFO] Cross-Origin-Opener-Policy: Not set.
[INFO] Cross-Origin-Resource-Policy: Not set.
```

### `map_endpoints`

Crawls a page and extracts all links, forms, scripts, stylesheets, and API endpoint references.

```
> map_endpoints({ url: "example.com" })

Endpoint Map: https://example.com/

Internal links: 3
  /about
  /contact
  /docs

External links: 5
  https://cdn.example.com/...
  ...

API endpoints found: 2
  /api/v1/users
  /graphql

Forms: 1
  POST /api/login — 3 fields

Scripts: 4, Stylesheets: 2
```

### `ssl_info`

Analyzes a hostname's TLS certificate — issuer, validity, expiry countdown, protocol, cipher, SAN list, chain.

```
> ssl_info({ hostname: "github.com" })

SSL/TLS Report: github.com:443

Subject: github.com
Issuer: DigiCert Global G2 TLS RSA SHA256 2020 CA1 (DigiCert Inc)
Valid from: 2024-03-07T00:00:00.000Z
Valid to: 2025-03-07T23:59:59.000Z
Days until expiry: 187
Protocol: TLSv1.3
Cipher: TLS_AES_128_GCM_SHA256
Serial: 0E8BF3770D92D196F0BB61F93C4166BE

SAN entries (2):
  github.com
  www.github.com

Certificate chain (3 certs):
  1. github.com (issued by: DigiCert Global G2 TLS RSA SHA256 2020 CA1)
  2. DigiCert Global G2 TLS RSA SHA256 2020 CA1 (issued by: DigiCert Global Root G2)
  3. DigiCert Global Root G2 (issued by: DigiCert Global Root G2)
```

### `dns_lookup`

Enumerates DNS records for a hostname.

```
> dns_lookup({ hostname: "example.com" })

DNS Records: example.com

A:
  93.184.216.34
AAAA:
  2606:2800:220:1:248:1893:25c8:1946
MX:
  10 mail.example.com
NS:
  a.iana-servers.net
  b.iana-servers.net
TXT:
  v=spf1 -all
SOA:
  Primary NS: ns.icann.org
  Admin: noc.dns.icann.org
  Serial: 2024022834
```

### `port_scan`

Quick TCP port scan with service identification.

Default ports: 21 (FTP), 22 (SSH), 80 (HTTP), 443 (HTTPS), 3000, 3306 (MySQL), 5432 (PostgreSQL), 6379 (Redis), 8080, 8443, 27017 (MongoDB).

```
> port_scan({ hostname: "example.com" })

Port Scan: example.com
Scanned 11 ports — 2 open, 9 closed

Open:
  80/tcp   open  HTTP
  443/tcp  open  HTTPS

Closed:
  21/tcp   closed  FTP
  22/tcp   closed  SSH
  ...
```

Custom ports:

```
> port_scan({ hostname: "10.0.0.1", ports: [22, 80, 443, 8080, 9090] })
```

## How It Works

spectral is an MCP (Model Context Protocol) server that runs over stdio. When connected to Claude Desktop or Claude Code, it exposes 6 tools that Claude can call to gather information about websites and servers.

Under the hood:
- **Tech fingerprinting** matches 50+ signatures against response headers, HTML meta tags, script sources, and inline patterns
- **Header auditing** checks 9 security headers against best-practice rules and computes a weighted grade
- **Endpoint mapping** uses cheerio to parse HTML and regex to extract API references from inline scripts
- **SSL analysis** uses Node's `tls.connect()` to grab the peer certificate directly
- **DNS enumeration** uses `dns.promises` to query all standard record types
- **Port scanning** uses `net.Socket` with concurrent TCP connects and 2-second timeouts

No external APIs. No browser automation. No heavy dependencies. Just Node built-ins plus cheerio for HTML parsing.

## Requirements

- Node.js 18+ (for built-in `fetch`)
- Claude Desktop or Claude Code (for MCP integration)

## License

MIT