v1.0.0 — ShantyCrawl MCP

🚀 v1.0.0 — ShantyCrawl MCP

Firecrawl with a chill token footprint. A drop-in replacement for firecrawl-mcp that saves ~18,000 tokens per session by lazy-loading 22 advanced tools.

✨ Since v0.5.2

🎯 Implicit Tool Activation (The Big One)

Advanced tools now auto-activate on first use — call map directly without tool_enable and it works for that call, then auto-deactivates. Explicit tool_enable still persists until tool_disable. Best of both worlds: zero friction for one-off use, full control for heavy sessions.

🔧 Monitor Tools — v2 API Compliance

• monitor_create body format updated to Firecrawl v2 (targets: [{type:"scrape", urls: [...]}], schedule: {text|cron})
• monitor_update now has a dedicated buildBody mapper — no more raw-arg fallback

🧪 Full Test Suite

10 test files covering: smoke test, state persistence, activation lifecycle, prompts, error handling, scrape, search, crawl, advanced tools, and monitor CRUD. Zero external test frameworks — pure JSON-RPC over stdio.

🤖 CodeRabbit Automation

• scripts/coderabbit-loop.ts polls PR issues for early green light (avoids waiting for full review)
• Infinite loop bug in the polling logic fixed
• Enforced green-light rule before merge

🧹 And More

• Zero third-party wrappers — native fetch, pure TypeScript
• FIRECRAWL_API_URL auto-detects local vs cloud from FIRECRAWL_API_KEY presence
• All routes target Firecrawl v2 API

🔌 Quick Start

FIRECRAWL_API_URL=http://localhost:3002 npx shantycrawl-mcp

⚙️ Claude Desktop

{
  "mcpServers": {
    "shantycrawl": {
      "command": "npx",
      "args": ["shantycrawl-mcp"],
      "env": { "FIRECRAWL_API_URL": "http://localhost:3002" }
    }
  }
}

📦 Install

npm install -g shantycrawl-mcp

🙏 Special Thanks

To the Firecrawl team for the excellent API, and to everyone who beta-tested the 0.x releases.

---

Full changelog: v0.5.2...v1.0.0

v0.5.2 — compact JSON responses (token economy)

Replace JSON.stringify(d, null, 2) with JSON.stringify(d) in all 21 response handlers. Saves ~40% tokens in JSON responses with zero semantic change.

v0.5.1 — fix coderabbit-loop infinite loop + enforce green light rule

Changes

• coderabbit-loop.ts: add processed comment cache (prevents re-applying fixes), fallback green light detection
• AGENTS.md: add CodeRabbit Green Light Rule — no merge without exit 0
• skills/git-merge/SKILL.md: add Guard Clause 2 — verify green light before merge

v0.5.0 — tool_enable hint in core output

scrape/crawl/search output now appends hint: Need more? Call tool_enable() to list and activate advanced tools.

v0.4.0 — CodeRabbit Auto-Fix Loop

What's New

• scripts/coderabbit-loop.ts — Automated CodeRabbit fix loop for PRs
  • Polls GitHub API for reviews, applies inline suggestions, commits/pushes
  • Supports suggestion, ts, and plain code fences
  • Descending line order per file prevents index shift
  • MAX_LOOPS=5 safeguard with PR comment for manual intervention
  • Detects CodeRabbit no-action signal when review body is edited in-place
  • Uses execFileSync/argv (no shell injection) + paginated API calls
• AGENTS.md updated with coderabbit-loop work guidance entry

v0.3.2

Changes

Full migration to Firecrawl v2 API with buildBody architecture.

Fixes monitor_create sending v1-shaped body to v2 endpoint (closes #12).

Infrastructure

• buildBody argument shaping for all POST/PATCH tools — fallback-safe
• Selective field copy prevents unknown args from reaching API

Path fixes (v1→v2)

• crawl, map, check_crawl_status, monitor_delete

Route/method fixes

• interact: /v2/browser → /v2/scrape
• interact_stop: POST → DELETE
• search_feedback: /v2/feedback → /v2/search/{id}/feedback
• All research tools: POST /v1/research/* → GET /v2/search/research/*

buildBody mappers

• scrape (formats strings→objects), crawl, search, map, extract, agent, parse, interact, monitor_create

Schema

• monitor_create: added optional schedule field

Diff

• 2 files changed, 140 insertions, 19 deletions

v0.3.1

• promote check_crawl_status to base tool
• tool_enable/tool_disable: no-arg lists available/active tools
• isBaseTool guard, invalid name suggestions
• keep prompts feature (shantycrawl-setup)

v0.3.0 – Cloud API Key Support

What's new

• Cloud API key support: set FIRECRAWL_API_KEY env var to authenticate with Firecrawl Cloud
• Smart default URL: automatically selects https://api.firecrawl.dev when a key is detected, http://localhost:3002 otherwise
• FIRECRAWL_API_URL always overrides the default

Docs

• New README with comparison table, token savings (~18k per session), and known issues section
• AGENTS.md contracts updated for authentication and tool count

v0.2.0 — Tool discovery improvements

🚀 Enhancements

• MCP Prompts: New shantycrawl-setup prompt with full usage guide for lazy-loading tools, accessible via GetPromptRequestSchema.
• tool_enable Discovery: Description now lists all advanced tool categories (map, extract, parse, agent, interact, research_*, monitor_*) so agents discover them naturally.
• Call without args: tool_enable() lists all 22 advanced tools with status; tool_disable() lists active tools.

🛡️ Guardrails

• Base tools locked: scrape, crawl, search, check_crawl_status, tool_enable, tool_disable cannot be enabled/disabled.
• Invalid name suggestions: tool_enable("typo") returns available tool names.

🤖 Workflow & DX

• Git skills split: Separated git-workflow (branch → PR) from git-merge (merge → version → publish) for cleaner automation.
• SKILL.md shipped: OpenCode skill included in npm package — triggers on web scraping, mapping, extraction tasks.

📖 Documentation

• AGENTS.md guidance: Two lines in Work Guidance reminding agents to use tool_enable for advanced tools.
• src/AGENTS.md: Updated file map and work guidance reflecting the new prompts capability.

v0.1.4

🐛 Bug Fixes & Agent Corrections

• npx Execution: Made the dist/index.js file executable to ensure the binary works correctly across environments (chmod +x).
• npm Compatibility: Removed the ./ prefix from the bin path in package.json to guarantee correct path resolution by npm.

🤖 Workflow & DX

• Safe Automation: Added the git-workflow skill and updated AGENTS.md to structure the AI agent's workflow and protect the main branch from direct commits.

🎨 Docs & Assets

• Branding: Final update of the official project avatar (ShantyCrawl mascot).
• Documentation: Minor formatting adjustments in README.md.