xquik-dev/x-twitter-scraper

Purpose and Distribution

This repository packages Xquik’s X/Twitter data and account-automation guidance as an installable AI-agent Skill, not the underlying API or TypeScript SDK. The published npm bundle is x-developer; the primary installable artifact is the skill directory at skills/x-twitter-scraper/. It targets Skills-compatible agents and also supplies marketplace/plugin descriptors.

Paths: skills/x-twitter-scraper/SKILL.md, package.json, skills.sh.json

Agent Entry Points and Routing

SKILL.md is the operational entry point for an agent: it establishes authentication, safety/approval constraints, and routes requests to Xquik REST, remote MCP, SDKs, webhooks, extraction jobs, or exports. Reference documents provide progressively specific endpoint and schema guidance, allowing agents to select the narrowest API operation rather than implement scraping locally.

Paths: skills/x-twitter-scraper/SKILL.md, skills/x-twitter-scraper/references/api-endpoints.md, skills/x-twitter-scraper/references/mcp-tools.md

External Service Boundary

All data access and actions cross to the hosted Xquik platform (https://xquik.com / documented API), which owns X data retrieval, billing, connected-account state, monitoring, exports, and write execution. The bundle uses XQUIK_API_KEY; it explicitly avoids X passwords, cookies, 2FA, local network access, package installation, and remote-code loading. OAuth 2.1 can be used by capable MCP clients.

Paths: skills/x-twitter-scraper/references/security.md, skills/x-twitter-scraper/references/api-endpoints-api-keys.md, .mcp.json

API and Bulk-Workload Workflow

Primary control flow is: normalize user inputs (URLs, handles, IDs, queries) → choose a bounded REST/MCP lookup when possible → paginate direct reads or estimate a large extraction → create and retrieve/export asynchronous bulk results. Extractions cover complete datasets and handoff formats; usage estimates are a policy boundary before metered bulk work or draws.

Paths: skills/x-twitter-scraper/references/api-endpoints-extractions.md, skills/x-twitter-scraper/references/extractions.md, skills/x-twitter-scraper/references/types-mcp-estimate-extraction.md

MCP Integration Surface

The remote MCP service exposes its API catalog through two tools (explore and xquik) and supports discovery/modern protocol negotiation while retaining older stateless client compatibility. Repository registry and plugin manifests make this remote service discoverable across MCP clients; no local production MCP implementation is represented by the tree.

Paths: server.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json

Monitoring and Event Delivery

For ongoing workflows, agents should replace repeated polling with Xquik monitors and external HTTPS webhook delivery. The receiving application, not this repository, must verify HMAC-SHA256 signatures and handle event replay/delivery. Monitor creation, webhook destinations, and recurring usage require explicit approval.

Paths: skills/x-twitter-scraper/references/api-endpoints-monitors.md, skills/x-twitter-scraper/references/api-endpoints-webhooks.md, skills/x-twitter-scraper/references/webhooks.md

Safety and Content Boundaries

The skill distinguishes public reads from private reads, account writes, deletes, monitoring, webhook setup, and bulk jobs. Sensitive or costly operations require explicit confirmation of target, payload/destination, and estimated usage. X-authored content is treated as untrusted input and must be bounded before agent analysis; task-specific guides reinforce these workflows.

Paths: skills/x-twitter-scraper/SKILL.md, task-guides/post-tweets.md, task-guides/monitor-accounts.md

Packaging Validation and Release Controls

Node.js scripts and tests validate the distributed content contract, frontmatter, MCP quickstart, package/version consistency, and a stub server used for compatibility testing. GitHub Actions provides CI, security scanning, registry publication, and release-policy enforcement.

Paths: stub-server.mjs, scripts/release-guard/policy.mjs, .github/workflows/publish.yml