coreclaw webscraper

El servicio MCP de CoreClaw expone los flujos de trabajo públicos de CoreClaw OpenAPI v2 a través del Model Context Protocol (MCP). Una vez conectado, el Agente de IA puede descubrir Workers de CoreClaw, ver esquemas de entrada, ejecutar Workers o tareas guardadas, consultar estados de ejecución, leer registros y exportar resultados estructurados.

Arquitectura

用户对话 -> AI Agent -> MCP 协议 -> CoreClaw MCP 服务 -> CoreClaw OpenAPI v2
                              HTTP       mcp.coreclaw.com      openapi.coreclaw.com

El punto de entrada HTTP transmisible alojado es:

https://mcp.coreclaw.com/mcp

Priorice el punto de entrada alojado. Solo se necesita ejecutar coreclaw-mcp-server localmente durante el desarrollo, la depuración o cuando el cliente solo admita stdio local.

Requisitos previos

• Cuenta de CoreClaw. Si aún no tiene una, regístrese primero.
• Clave de API de CoreClaw, disponible en Consola -> Configuración -> API e integraciones.
• Un cliente compatible con MCP. Consulte Plataformas compatibles a continuación.

Inicio rápido

Agregue la siguiente configuración en su cliente MCP:

{
  "mcpServers": {
    "coreclaw": {
      "url": "https://mcp.coreclaw.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CORECLAW_API_KEY"
      }
    }
  }
}

Después de guardar la configuración, si el cliente solicita reiniciar o recargar, complete la acción correspondiente. Después de eso, el Agente de IA puede invocar las herramientas de CoreClaw en la conversación.

Métodos de autenticación

El servicio MCP alojado utiliza autenticación Authorization: Bearer <token> — el mismo encabezado que CoreClaw OpenAPI v2. Para compatibilidad con integraciones antiguas, los encabezados api-key y X-API-Key aún se aceptan:

• Authorization: Bearer YOUR_CORECLAW_API_KEY (recomendado)
• api-key: YOUR_CORECLAW_API_KEY (heredado)
• X-API-Key: YOUR_CORECLAW_API_KEY (heredado)

El servicio MCP reenvía la información de autenticación a CoreClaw OpenAPI v2, y las solicitudes ascendentes usan Authorization: Bearer <token> de manera uniforme.

No confíe claves de API al sistema de control de versiones. Cuando el cliente admita almacenamiento seguro de credenciales, priorice esa capacidad.

Herramientas disponibles

El servicio MCP de CoreClaw expone 42 herramientas — 39 operaciones de OpenAPI v2 (1:1) más 3 asistentes de orquestación. Las interfaces de creación/actualización de versiones de Worker y las interfaces de detalles internos de Worker son internas y no se exponen a través de MCP.

Descubrimiento y verificación previa

Herramienta	Descripción	API correspondiente
list_proxy_regions	Consultar códigos y nombres de regiones de proxy	GET /api/v2/proxy/region
list_store_workers	Buscar Workers públicos de Store	GET /api/v2/store
list_workers	Listar Workers propiedad de la cuenta actual	GET /api/v2/workers
get_worker	Obtener metadatos, versión, README e información de parámetros del Worker	GET /api/v2/workers/{workerId}
get_worker_input_schema	Obtener el esquema de entrada público del Worker	GET /api/v2/workers/{workerId}/input-schema
get_account_info	Consultar saldo de cuenta, cuota de tráfico y tiempo de expiración	GET /api/v2/users/account

Tareas de Worker (plantillas de tareas guardadas)

Herramienta	Descripción	API correspondiente
list_worker_tasks	Listar tareas de Worker guardadas de la cuenta actual	GET /api/v2/worker-tasks
get_worker_task	Obtener detalles de una tarea guardada	GET /api/v2/worker-tasks/{workerTaskId}
get_worker_task_input	Obtener la carga útil de entrada de una tarea guardada	GET /api/v2/worker-tasks/{workerTaskId}/input
create_worker_task	Crear una tarea guardada (programación opcional)	POST /api/v2/worker-tasks
update_worker_task	Actualizar metadatos/programación de la tarea	PUT /api/v2/worker-tasks/{workerTaskId}
update_worker_task_input	Actualizar solo la carga útil de entrada de la tarea	PUT /api/v2/worker-tasks/{workerTaskId}/input
delete_worker_task	Eliminar una tarea guardada	DELETE /api/v2/worker-tasks/{workerTaskId}

Asistentes de orquestación

Tres herramientas convenientes que combinan múltiples llamadas de API en una sola invocación de herramienta.

Herramienta	Descripción	Llamadas subyacentes
poll_run	Sondea la ejecución hasta el estado final (o tiempo de espera)	Repetir GET /api/v2/worker-runs/{runId}
verify_run	Devuelve un veredicto estructurado ( PASS / NO_DATA / FAILED / ERROR_RECORD / RUNNING / SUBMIT_FAIL ) — verifica el estado de ejecución y luego inspecciona la primera línea de resultados para distinguir datos reales de registros de solo diagnóstico	get_worker_run + list_worker_run_results
run_workers_batch	Ejecuta hasta 50 Workers en una sola llamada, devolviendo resúmenes y veredictos individuales. Concurrencia 1–10, verify opcional por elemento	Por elemento: POST /api/v2/workers/{workerId}/runs + poll_run (+ verify_run opcional)

poll_run acepta timeout_seconds (1–900, predeterminado 300) y poll_interval_seconds (1–60, predeterminado 5), y en caso de éxito puede obtener una vista previa de resultados parciales ( limit ). Úselo para Workers cuyo tiempo de ejecución exceda la ventana de una sola llamada MCP. verify_run se usa para distinguir el éxito real de los falsos positivos de "CAPTCHA/403 llenó la lista pero sin carga útil real" — marca estos últimos como ERROR_RECORD . get_worker_run_log también admite grep en proceso (separado por tubería, sin distinción de mayúsculas y minúsculas) más context_lines y max_matches .

Ejecución

Herramienta	Descripción	API correspondiente
run_worker	Ejecutar un Worker con entrada JSON temporal	POST /api/v2/workers/{workerId}/runs
run_worker_task	Ejecutar una tarea de Worker guardada	POST /api/v2/worker-tasks/{workerTaskId}/runs

Cola de ejecución

Herramienta	Descripción	API correspondiente
queue_worker_run	Poner una ejecución en cola, esperando activación explícita en lugar de ejecución inmediata	POST /api/v2/workers/{workerId}/queued-runs
list_run_queue_items	Listar ejecuciones en cola esperando activación	GET /api/v2/run-queue/items
activate_run_queue_items	Activar una ejecución en cola para ejecutarla	POST /api/v2/run-queue/items/activate
release_run_queue_items	Devolver una ejecución en cola a la cola	POST /api/v2/run-queue/items/release
release_run_queue_item	Liberar una sola ejecución en cola	POST /api/v2/run-queue/items/{queueId}/release

Consulta de ejecuciones

Herramienta	Descripción	API correspondiente
list_worker_runs	Consultar historial de ejecuciones	GET /api/v2/worker-runs
get_last_worker_run	Consultar la ejecución más reciente de la cuenta actual	GET /api/v2/worker-runs/last
get_worker_run	Consultar una ejecución específica mediante run_id	GET /api/v2/worker-runs/{runId}
get_worker_last_run	Consultar la ejecución más reciente de un Worker específico	GET /api/v2/workers/{workerId}/runs/last

Resultados, exportación y registros

Herramienta	Descripción	API correspondiente
list_last_worker_run_results	Ver el resultado de la ejecución más reciente de la cuenta actual	GET /api/v2/worker-runs/last/result
export_last_worker_run_results	Exportar el resultado de la ejecución más reciente de la cuenta actual	GET /api/v2/worker-runs/last/export
get_last_worker_run_log	Ver los registros de la ejecución más reciente de la cuenta actual	GET /api/v2/worker-runs/last/log
list_worker_run_results	Ver el resultado de una ejecución específica	GET /api/v2/worker-runs/{runId}/result
export_worker_run_results	Exportar el resultado de una ejecución específica	GET /api/v2/worker-runs/{runId}/result/export
get_worker_run_log	Ver los registros de una ejecución específica	GET /api/v2/worker-runs/{runId}/log
list_worker_last_run_results	Ver el resultado de la ejecución más reciente de un Worker específico	GET /api/v2/workers/{workerId}/runs/last/result
export_worker_last_run_results	Exportar el resultado de la ejecución más reciente de un Worker específico	GET /api/v2/workers/{workerId}/runs/last/export
get_worker_last_run_log	Ver los registros de la ejecución más reciente de un Worker específico	GET /api/v2/workers/{workerId}/runs/last/log

Reejecución y control

Herramienta	Descripción	API correspondiente
rerun_last_worker_run	Reejecutar la ejecución más reciente de la cuenta actual	POST /api/v2/worker-runs/last/rerun
rerun_worker_run	Reejecutar una ejecución específica	POST /api/v2/worker-runs/{runId}/rerun
rerun_worker_last_run	Reejecutar la ejecución más reciente de un Worker específico	POST /api/v2/workers/{workerId}/runs/last/rerun
abort_last_worker_run	Detener la ejecución activa más reciente de la cuenta actual	POST /api/v2/worker-runs/last/abort
abort_worker_run	Detener una ejecución activa específica	POST /api/v2/worker-runs/{runId}/abort
abort_worker_last_run	Detener la ejecución activa más reciente de un Worker específico	POST /api/v2/workers/{workerId}/runs/last/abort

Flujos de trabajo típicos

Al ejecutar temporalmente un Worker, normalmente se invoca en este orden:

list_store_workers(keyword)
  -> get_worker_input_schema(worker_id)
    -> run_worker(worker_id, input_json, is_async=true)
      -> get_worker_run(run_id)
        -> list_worker_run_results(run_id) 或 export_worker_run_results(run_id)

Al ejecutar una tarea guardada, use:

list_worker_tasks(worker_id)
  -> run_worker_task(worker_task_id, is_async=true)
    -> get_worker_run(run_id)
      -> list_worker_run_results(run_id)

Si el esquema de entrada del Worker requiere una región de proxy, primero invoque list_proxy_regions . Solo use las herramientas rerun_* cuando el usuario solicite explícitamente reintentar o repetir una ejecución; solo use las herramientas abort_* cuando el usuario solicite explícitamente detener una ejecución.

Entrada del Worker

Al invocar run_worker , coloque los campos de negocio en input_json :

{
  "worker_id": "YOUR_WORKER_ID",
  "version": "latest",
  "input_json": "{\"keyword\":\"coffee\",\"limit\":10}",
  "is_async": true
}

El servicio MCP envuelve input_json como input.parameters.custom que usa CoreClaw. Los llamadores avanzados pueden pasar el objeto completo input de CoreClaw directamente a través de raw_input_json , pero no pueden pasar input_json y raw_input_json al mismo tiempo.

Plataformas compatibles

Plataforma	Método de configuración	Guía
Claude Desktop	Streamable HTTP	Guía de configuración
Claude CLI	Streamable HTTP	Guía de configuración
Codex Desktop	Streamable HTTP	Guía de configuración
Cursor	Streamable HTTP	Guía de configuración
ChatGPT	Streamable HTTP	Guía de configuración
VS Code	Streamable HTTP	Guía de configuración
Windsurf	Streamable HTTP	Guía de configuración
Cline	Streamable HTTP	Guía de configuración
n8n	Streamable HTTP	Guía de configuración
HTTP genérico	Cualquier cliente MCP Streamable HTTP o llamador de herramientas de estilo REST	Guía de configuración

Puntos finales compatibles con REST

Además del punto final MCP estándar /mcp , el servicio también ofrece un punto de entrada compatible con REST /mcp/<tool_name> , adecuado para plataformas que prefieren realizar solicitudes HTTP por herramienta:

curl -X POST https://mcp.coreclaw.com/mcp/list_store_workers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CORECLAW_API_KEY" \
  -d '{"keyword":"amazon","offset":1,"limit":5}'

Para más ejemplos de JSON-RPC y REST, consulte Cliente HTTP genérico .

Solución de problemas

Síntoma	Causa posible	Solución
Invalid API key	Clave faltante, incorrecta o caducada	Verifique la clave en Consola -> Configuración -> API e integraciones
Worker does not exist (50001)	Error de worker_id	Use list_store_workers o list_workers para obtener el slug/ruta devuelto
Las herramientas no aparecen	El cliente no cargó la configuración MCP de Streamable HTTP	Reinicie el cliente y verifique la ruta de configuración de MCP
La ejecución comenzó pero no hay líneas de resultado	La ejecución aún está en curso o falló	Sondee get_worker_run ; en caso de fallo, invoque get_worker_run_log
Región de proxy rechazada	Código de región de proxy no válido	Invoque list_proxy_regions y use los códigos de región devueltos

Notas de limitaciones

• El servicio alojado usa Streamable HTTP. Los clientes que solo admiten stdio local necesitan ejecutar coreclaw-mcp-server localmente.
• La autenticación se basa en clave de API; el punto de entrada alojado no requiere OAuth.
• Las interfaces internas no se exponen a través de MCP, incluidas la creación/actualización de versiones de Worker y los detalles internos de Worker.

Siguientes pasos

• Configurar Claude Desktop
• Configurar Codex Desktop
• Configurar HTTP genérico
• Leer la documentación de la API de CoreClaw