[!WARNING] This is ALPHA software. Do not use it in production before testing.

Claudii Exploratores is a very early (alpha), community-maintained port of the Exploratores toolkit. It has been functionally tested, but it has not been hardened or validated for production or operational use. Search URLs, validators and the tool catalog may contain errors inherited from upstream or introduced by the port. Verify every output independently, test thoroughly in a safe environment, and validate results against trusted sources before relying on them. Use at your own risk — see Disclaimer.

Table of Contents

• About
• Features
• How it works
• Repository layout
• Requirements
• Installation
  • Agent Skill
  • MCP Server
• Usage
• Available MCP tools
• Rebuilding the catalog
• Project status
• Roadmap
• Contributing
• Security & responsible use
• Disclaimer
• License
• Acknowledgements

🔎 About

Claudii Exploratores turns the Exploratores OSINT Toolkit — a static web application of curated OSINT search links — into two AI-native distributions:

1. An Agent Skill (skill/) — a drop-in skill for Claude (Opus/Sonnet) in Claude Code, Cowork or the Agent SDK. It teaches the model professional OSINT tradecraft (analytic standards, the 5W1H method, OPSEC) and gives it a CLI that turns any indicator into a curated set of search links.
2. An MCP server (mcp/) — a Model Context Protocol server (Python / FastMCP) exposing the same engine as callable tools for Claude Desktop or any MCP-compatible client.

Both share one language-neutral core: a catalog of 898 OSINT tools across 24 categories, an indicator classifier, input validators, an offline IBAN verifier and a reversible PII redactor — all ported from the original toolkit.

[!IMPORTANT] These tools build OSINT search URLs; they never open pages by themselves. Opening and reading stays with the operator (or an explicitly-invoked browser agent), so OPSEC — VPN, sterile browser profile — remains under human control.

✨ Features

• 898 curated OSINT tools across 24 categories (people, usernames, email, domains, IP, phones, companies, crypto, IBAN, maps, media, social platforms…).
• Indicator classifier — auto-detects whether a value is a domain, email, IP, username, person name, phone, coordinates, IBAN, crypto address, VIN, and more.
• Curated URL builder — fills and URL-encodes only the tools that fit the indicator, so you get a relevant, scoped set instead of 898 raw links.
• Cross-platform pivoting — one username fans out to the right search across every social/community platform that supports it.
• Offline IBAN verifier — ISO 13616 mod-97 check against a 71-country table.
• Reversible PII redactor — strip emails, IPs, phones, IBANs, cards, URLs and crypto addresses before sending case text to an external model; restore afterwards.
• No mandatory dependencies for the skill — standard-library Python 3.9+.
• Single source of truth — one shared engine + catalog, synced into both deliverables by a build script; regenerable from the upstream toolkit.

🧭 How it works

indicator ──▶ classify ──▶ build fields ──▶ select matching tools ──▶ URL-encode ──▶ curated link set
 "Mario Rossi"   PERSON_NAME   {firstname,lastname,…}   names + records          %20…        grouped Markdown / JSON

The engine is a faithful Python port of the toolkit's original JavaScript logic (indicator-classifier.js, validators.js, main.js), so generated URLs match what the web toolkit produces.

📦 Repository layout

Claudii-Exploratores/
├── skill/claudii-exploratores/   # the Agent Skill (SKILL.md + scripts + references)
│   ├── SKILL.md
│   ├── scripts/                  # exploratores.py CLI + engine + catalog.json
│   └── references/               # methodology.md, catalog_overview.md
├── mcp/                          # the MCP server (Python, FastMCP)
│   ├── exploratores_osint_mcp/   # package: server.py + engine + catalog.json
│   ├── pyproject.toml
│   ├── config.example.json
│   └── README.md
├── shared/                       # single source of truth for the engine + catalog
│   ├── osint_core.py             # classifier, field builder, URL renderer
│   ├── iban_tools.py, redactor.py, _iban_countries.py
│   └── catalog.json              # 898 tools (generated)
├── scripts/                      # build, extraction & verification tooling
│   ├── extract_catalog.js        # (re)generate catalog.json from the web toolkit
│   ├── build_release.sh          # sync engine into skill+mcp, package .skill
│   ├── classify_queries.py       # desk classification (auth/VPN) -> CSV
│   ├── build_verification_worklist.py  # group queries by host for live checks
│   ├── record_verification.py    # merge live-probe results into the worklist
│   ├── generate_live_report.py   # render the live-verification report
│   └── generate_access_guide.py  # render the user-facing access guide
├── docs/                         # INSTALL, DISTRIBUTION, access & auth/VPN guides
├── dist/                         # build outputs (.skill archive) — git-ignored
├── LICENSE                       # AGPL-3.0 (inherited from Exploratores)
└── NOTICE

shared/ is authoritative. scripts/build_release.sh copies the engine + catalog into both skill/ and mcp/ so each is independently installable.

⚙️ Requirements

• Python 3.9+ (standard library only for the skill; the MCP adds the mcp package).
• Node.js — only needed to regenerate the catalog from the upstream toolkit.
• A modern browser (and, recommended, a VPN + sterile profile) to open the generated links. Which sources need a login, a VPN (and which country), or Tor is documented in docs/access-requirements-guide.md (live-verified) and the desk analysis in docs/query-auth-vpn-classification.md.

🚀 Installation

Agent Skill (Claude Code / Cowork)

Copy the skill into your skills directory, or install the packaged archive from your client's UI:

mkdir -p ~/.claude/skills
cp -R skill/claudii-exploratores ~/.claude/skills/
# or install dist/claudii-exploratores.skill from your Claude client

Then simply ask, e.g. "Run OSINT on the domain example.com".

MCP Server (Claude Desktop)

cd mcp
pip install -e .            # or: uv pip install -e .

Add the server to your MCP client config (see mcp/README.md and docs/INSTALL.md):

{
  "mcpServers": {
    "claudii-exploratores": {
      "command": "python",
      "args": ["-m", "exploratores_osint_mcp.server"]
    }
  }
}

💻 Usage

Drive the skill's CLI directly:

cd skill/claudii-exploratores

# Detect what an indicator is
python scripts/exploratores.py classify "john.doe@example.com"

# Build a curated OSINT link set (grouped Markdown by default)
python scripts/exploratores.py urls "example.com" --format markdown

# Force a type, add structured fields, or narrow to specific platforms
python scripts/exploratores.py urls "Mario Rossi" --type PERSON_NAME \
  --field firstname=Mario --field lastname=Rossi
python scripts/exploratores.py urls "johndoe" --categories x,instagram,vk

# Utilities
python scripts/exploratores.py iban "GB82 WEST 1234 5698 7654 32"
python scripts/exploratores.py redact "Contact john@x.com from 8.8.8.8"
python scripts/exploratores.py search "wayback"

🛠 Available MCP tools

🔄 Rebuilding the catalog

If the upstream toolkit is updated, regenerate everything from it:

scripts/build_release.sh /path/to/Exploratores-3.4.1

This re-extracts catalog.json (with human-readable labels harvested from the toolkit's HTML pages), re-syncs the engine into both deliverables, and repackages the .skill archive.

🧪 Project status

Alpha (v1.0.0-alpha). The suite is functional and has passed an internal QA pass (catalog integrity, URL encoding, IBAN and redaction round-trips, MCP tool registration). It has not been hardened for production. Known limitations:

• A small number of URL templates are inherited verbatim from upstream and may be imperfect (e.g. dork operators with literal spaces; one degenerate short-URL template).
• Phone-number field derivation is best-effort and does not replicate the full libphonenumber logic of the original web toolkit.
• Offline bank-name resolution for IBANs is not ported (only structural validation); that dataset lives in the original web toolkit.

Please test in a controlled environment and report issues before any operational use.

🗺 Roadmap

• Automated test suite (pytest) covering classifier, renderer, IBAN, redactor.
• CI (GitHub Actions) for lint + tests on every push.
• Optional PyPI release of the MCP server.
• Fuller phone-number parsing parity with the upstream toolkit.
• Optional bank-name resolution for IBANs.

🤝 Contributing

Contributions and bug reports are welcome.

1. Open an issue describing the bug or proposal.
2. Fork the repo and create a feature branch.
3. Keep the engine changes in shared/ (the single source of truth) and run scripts/build_release.sh to sync them into skill/ and mcp/.
4. Open a pull request with a clear description and, where relevant, before/after examples.

Please follow the conventions in the upstream AGENTS.md and preserve attribution.

🛡 Security & responsible use

• For authorised, lawful investigation only — research, security, journalism, due diligence. Do not use it for stalking, harassment or doxxing.
• The tools build links; they do not fetch data. Opening pages exposes your IP and fingerprint to target-controlled infrastructure — use a VPN and a sterile browser profile, and prefer cached/archived views for first contact.
• Treat all outputs as leads to verify, never as conclusions. Corroborate across independent sources and record provenance.
• Some catalog entries are Tor hidden services (.onion) and require Tor Browser; exclude them with --no-onion / include_onion=false.

To report a security concern, please open a private security advisory on GitHub rather than a public issue.

⚠️ Disclaimer

This software is provided "as is", without warranty of any kind, express or implied. It is beta and not intended for production use. The authors and contributors accept no liability for any damage, loss, legal consequence or misuse arising from its use. You are solely responsible for ensuring your use complies with all applicable laws, regulations and third-party terms of service, and for independently verifying every result before acting on it.

📄 License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — the same licence as the original work. See LICENSE and NOTICE.

🙏 Acknowledgements

Derived from the Exploratores OSINT Toolkit by Ramingo (SOsintOps). This project ports its search catalog, classifier, validators, IBAN table and redactor concept to a Python engine packaged as a Claude skill and an MCP server. All credit for the original toolkit and its curation belongs to the upstream author.