Task402 Agent Evidence Tools
Evidencia de pago por llamada para agentes de IA: indexación de PDF en texto nativo y herramientas de citación, evidencia web pública, análisis de contratos OpenAPI y datos Base de solo lectura a través de x402 USDC.
Servidor MCP alojado
npx add-mcp 'https://task402.xyz/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
Task402 Agent Evidence Tools
Proporciona a los agentes evidencia acotada de PDFs, páginas web públicas, contratos OpenAPI y datos de la cadena Base. Conéctate al servicio MCP alojado de 20 herramientas en https://task402.xyz/mcp; no se necesita servidor local, clave API ni billetera para el descubrimiento. Las llamadas de pago usan x402 v2 USDC en Base. Conectar un host MCP no le otorga automáticamente un firmante de pagos.
Conecta tu agente
Para Cursor, fusiona examples/cursor.mcp.json en .cursor/mcp.json. Para VS Code, fusiona examples/vscode.mcp.json en .vscode/mcp.json. Otros clientes Streamable HTTP pueden usar:
{
"mcpServers": {
"task402": { "url": "https://task402.xyz/mcp" }
}
}
Inicializa la conexión y ejecuta tools/list para inspeccionar los esquemas ejecutables. Con Node.js 24 y las dependencias de este repositorio instaladas, npm run discover realiza el descubrimiento a través del SDK oficial de MCP e imprime solo los nombres de las herramientas. Nunca llama a una herramienta de pago ni firma un pago.
Cada herramienta alojada anuncia un esquema de salida específico, descripciones de parámetros y anotaciones de seguridad MCP. Los agentes pueden planificar la forma del resultado y el comportamiento de reintento desde tools/list antes de aprobar cualquier pago x402.
| Herramientas | Facturación en la verificación en vivo del 12 de octubre de 2026 |
|---|---|
generate_pdf | $0.01 por PDF |
web_evidence | $0.005 por página HTTPS pública |
inspect_openapi | $0.001 por especificación |
plan_api_request, diff_openapi | $0.002 por llamada |
get_chain_balance, get_chain_transaction, get_erc20_balance | $0.001 por lectura |
get_pdf_job | Incluido con la generación; requiere la capacidad de trabajo |
inspect_pdf, get_document_map, search_document, batch_search_document, prepare_document_context, extract_document_fields, read_document, verify_document_citation, compare_pdfs, validate_pdf_text, render_pdf_page_region | Incluido después de la indexación de PDF de pago; requiere capacidades de documento |
La indexación de PDF es la operación REST separada POST /v1/documents ($0.01 por PDF); la carga binaria no es una herramienta MCP. La descarga de PDF generado también es solo REST. Lee /v1/pricing y el desafío de pago para conocer los términos actuales antes de aprobar el pago. Las herramientas de PDF de texto nativo no proporcionan OCR ni verifican la veracidad de los hechos.
Comienza con docs/FIRST-PAID-CALL.md para un flujo de trabajo de desafío, reintento firmado y resultado. Usa docs/PUBLISHING.md para publicar el repositorio y los metadatos MCP remotos.
Arquitectura del servicio
Este proyecto convierte Markdown en archivos PDF paginados a través de un servicio compartido utilizado por REST y MCP. El ejecutor local usa Playwright Chromium y SQLite; el adaptador de Cloudflare Worker usa Browser Run Quick Actions, D1 y R2. La ruta de pago en vivo usa el cliente facilitador oficial del SDK x402, verifica antes de renderizar y liquida solo después de que se almacena un artefacto PDF.
Las operaciones de pago son generate_pdf, ingest_document, web_evidence, inspección/planificación/diferenciación de OpenAPI y lecturas de cadena Base de método fijo. La recuperación, citación, búsqueda por lotes, preparación de contexto acotado y coincidencia de campos con etiquetas explícitas están incluidas después de la indexación. La evidencia web es solo HTML/texto HTTPS público, las herramientas OpenAPI aceptan solo JSON proporcionado por el llamador y referencias locales, y las herramientas de cadena nunca firman ni envían transacciones. El HTML de entrada no se ejecuta, las imágenes remotas y otros recursos externos se omiten o bloquean, y los hipervínculos se conservan en los PDF generados pero nunca se obtienen durante el renderizado.
Los metadatos de distribución, la guía de conversión y el texto listo para canales están en docs/MARKETING.md y docs/LAUNCH-KIT.md; los metadatos públicos del directorio MCP están en server.json, glama.json y lhm.plugin.json para LobeHub.
La guía detallada de agente, descubrimiento, operaciones, implementación, estadísticas de operador y seguridad es docs/AGENT-GUIDE.md.
Usa el servidor MCP alojado
No se requiere ningún proceso local. Agrega el endpoint Streamable HTTP a un cliente compatible con MCP:
{
"mcpServers": {
"task402": {
"type": "http",
"url": "https://task402.xyz/mcp"
}
}
}
El servidor se puede descubrir sin pago. Las operaciones de pago devuelven un desafío x402 v2; el cliente debe inspeccionar la red, el activo USDC, el destinatario, el monto, el recurso y el tiempo de espera, obtener la aprobación explícita de la billetera y luego reintentar la misma solicitud con el pago firmado. Task402 nunca recibe una clave privada y nunca firma ni envía transacciones por el llamador. Comienza con la primera llamada de pago y luego usa examples/agent-flow.ts para un flujo completo con firmante inyectado.
Qué está incluido
| Capacidad | Pago | Interfaz |
|---|---|---|
| Generar un PDF paginado desde Markdown | $0.01 | REST, MCP |
| Indexar un PDF de texto nativo | $0.01 | REST |
| Buscar, citar, comparar, validar, mapear, leer, extraer campos, preparar contexto y renderizar | Incluido después de la indexación | REST, MCP |
| Evidencia acotada de páginas públicas | $0.005 | REST, MCP |
| Inspección de OpenAPI, plan de solicitud y diferenciación | $0.001–$0.002 | REST, MCP |
| Datos de solo lectura de saldo, transacciones y ERC-20 en Base | $0.001 | REST, MCP |
Los precios, límites, esquemas y términos de pago son legibles por máquina en /v1/pricing. El servicio no proporciona OCR, renderizado de páginas JavaScript, ejecución arbitraria de API, firma de transacciones ni redacción visual/legal de PDF.
Los metadatos del servidor MCP remoto son la versión 0.3.2 en server.json. En la auditoría del 12 de octubre de 2026, el Registro oficial sirvió 0.2.0; publicar los nuevos metadatos requiere la clave de prueba del editor del dominio, que intencionalmente no se almacena en este espacio de trabajo. Vuelve a verificar el registro en vivo antes de afirmar que la versión está publicada. Los desafíos REST y MCP de pago incluyen metadatos de descubrimiento de x402 Bazaar, y el facilitador de producción es https://facilitator.openx402.ai.
Las páginas públicas de descubrimiento están disponibles en https://task402.xyz/, /docs#first-paid-call, /llms.txt, /demo, /v1/tools, /openapi.json, /v1/pricing, /.well-known/x402.json, /.well-known/mcp/server-card.json, /.well-known/ai-plugin.json y /sitemap.xml. Proporcionan a los agentes y rastreadores de directorios un punto de entrada claro sin requerir pago ni credencial de operador. La publicación en el Registro mejora la capacidad de descubrimiento para los clientes que sincronizan el Registro MCP; no crea tráfico sintético ni garantiza llamadas.
La guía de inicio rápido pública incluye flujos de trabajo enfocados para verificación de citas, comparación de revisiones de PDF y reducción del contexto de PDF antes de las llamadas al modelo. Los archivos de cliente para copiar y pegar están en examples/agent-flow.ts, examples/cursor.mcp.json y examples/vscode.mcp.json. El ejemplo de TypeScript obtiene desafíos de generación e indexación sin firmar y expone métodos de reintento explícitos para una carga útil de billetera aprobada por separado; nunca firma ni envía un pago automáticamente.
Cuando estés listo para un pago en vivo controlado, sigue docs/TEST-TRANSACTION.md. Requiere un firmante de billetera externo y nunca solicita una clave privada.
Para una billetera de prueba local desechable, el repositorio también incluye un asistente de terminal protegido: npm run test:live. Valida el desafío en vivo de Base/USDC antes de firmar, requiere TASK402_CONFIRM=YES, descarga el PDF y nunca imprime la carga útil de pago ni la capacidad. Consulta la sección de terminal de la guía de pruebas para la configuración y limpieza.
Para reproducir un agente MCP exactamente, usa npm run test:agent; realiza el descubrimiento, recibe el desafío x402 estructurado, firma a través del cliente EVM oficial, reintenta con _meta["x402/payment"], verifica el trabajo a través de get_pdf_job y descarga el resultado.
Desarrollo local
Usa Node.js 24 o más reciente (verificado con Node 24.13; el estado duradero local usa node:sqlite). Desde este directorio:
npm ci
Copy-Item .dev.vars.example .dev.vars
npm run setup:browser
npm run dev
El servidor local se vincula solo a 127.0.0.1:8787 y acepta solo la autoridad de Host de loopback/localhost coincidente (más la autoridad pública configurada en modo en vivo). El adaptador de evidencia web local resuelve cada nombre de host antes de obtener y rechaza destinos DNS privados, de loopback, de enlace local y reservados; el Worker alojado depende de su límite de salida de plataforma más las mismas verificaciones de URL. El ejemplo .dev.vars habilita una omisión explícita de desarrollo sin pago, y la omisión existe solo en src/local.ts; src/worker.ts la rechaza incondicionalmente. Si .dev.vars está ausente, el servidor se inicia con pagos no configurados y la generación de pago falla de forma segura. Los trabajos y artefactos locales son duraderos bajo .data/ y son ignorados por Git.
Si Playwright no puede encontrar su descarga de Chromium fijada en tu máquina, apúntalo a un ejecutable de Chromium instalado antes de iniciar el proceso local:
$env:BROWSER_EXECUTABLE_PATH = "C:\path\to\chrome.exe"
npm run dev
Genera y descarga un PDF de muestra:
$body = @{ title = "Quarterly Report"; markdown = "# Summary`n`n| Metric | Value |`n| --- | ---: |`n| Revenue | 42 |" } | ConvertTo-Json
$job = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/pdf `
-Headers @{ "Idempotency-Key" = "report-2026-q3-0001" } `
-ContentType "application/json" -Body $body
$job | Format-List
Invoke-WebRequest -Uri $job.downloadUrl `
-Headers @{ Authorization = "Bearer $($job.capability)" } `
-OutFile .\report.pdf
La capacidad es un secreto portador. Mantenlo en memoria, no lo registres y envíalo solo a las URL de estado/descarga devueltas. El acceso al estado y la descarga requiere Authorization: Bearer <capability> (o X-Job-Capability); un ID de trabajo o clave de idempotencia por sí solo no autoriza el acceso.
API y límites
| Ruta | Propósito |
|---|---|
GET /v1/pricing | Operación legible por máquina, precio, modo de pago y límites de tamaño/TTL |
GET /.well-known/x402 | Mismo documento de descubrimiento en una ruta conocida |
GET / y GET /docs | Descripción general pública del servicio y guía de inicio rápido del agente |
GET /llms.txt y GET /sitemap.xml | Metadatos compactos legibles por agente y descubrimiento de rastreadores |
POST /v1/pdf | Genera un PDF; requiere Idempotency-Key; el modo en vivo usa x402 v2 PAYMENT-SIGNATURE |
GET /v1/jobs/{jobId} | Lee el estado autorizado del trabajo |
GET /v1/jobs/{jobId}/download | Descarga un PDF completado autorizado |
GET /v1/admin/stats | Estadísticas agregadas de herramientas protegidas por contraseña; ?hours=24 opcional |
GET /admin | Formulario de contraseña compatible con móviles para ver el endpoint de estadísticas protegido |
POST /mcp | Endpoint MCP Streamable HTTP con herramientas de PDF, web, OpenAPI y lectura de Base |
POST /v1/documents | Indexación de PDF sin procesar de pago para operaciones deterministas de texto nativo |
GET /v1/documents/{documentId} y /map | Inspecciona los metadatos del documento o lee su mapa de páginas |
POST /v1/documents/{documentId}/search, /batch-search, /context, /fields, /read, /citation, /validate | Buscar, construir contexto citado, leer páginas seleccionadas, verificar una cita de texto o validar expectativas declaradas |
POST /v1/documents/compare | Compara dos PDFs autorizados por separado por página y texto nativo normalizado |
GET /v1/documents/{documentId}/pages/{page}/render | Renderiza un recorte de página acotado a PNG |
POST /v1/web/evidence | Extracción de página HTTPS pública de pago con texto acotado, enlaces, hash de fuente y advertencia de inyección de indicaciones |
POST /v1/openapi/inspect | Inspección de pago de operación OpenAPI, parámetros, cuerpo de solicitud, seguridad y referencias locales |
POST /v1/openapi/request-plan y /v1/openapi/diff | Planificación segura de solicitudes de pago y comparación determinista de contratos API; no se ejecutan solicitudes |
POST /v1/chain/balance, /v1/chain/transaction, /v1/chain/erc20-balance | Utilidades RPC de solo lectura de pago en Base; sin firma ni movimiento de fondos |
Los límites predeterminados son un cuerpo de solicitud de 256 KiB, Markdown normalizado de 240 KiB, 160 caracteres de título, 20,000 líneas de Markdown, salida de PDF de 20 MiB, una vida útil del artefacto de 24 horas y un plazo de renderizado de 90 segundos. El PDF usa diseño A4, repite los encabezados de tabla, mantiene las filas juntas cuando es posible e incluye números de página. La limpieza se ejecuta cada hora en Cloudflare y al inicio y cada hora en el proceso local. Los lotes de limpieza están acotados; las capacidades caducadas dejan de funcionar inmediatamente, mientras que la eliminación física puede requerir lotes adicionales. Los asentamientos inciertos conservan sus artefactos para la conciliación del operador.
Inspección y recuperación local de PDF
El Worker desplegado expone las operaciones deterministas de documentos PDF a través de un analizador aislado de Cloudflare Container. El Worker mantiene las capacidades, los metadatos de D1, los objetos de origen/índice de R2, la validación y la limpieza; el Container realiza la extracción nativa de PDF.js y el renderizado de páginas acotado con Internet saliente deshabilitado. El desarrollo local continúa usando las mismas operaciones directamente a través del analizador de Node.js.
Sube un PDF sin procesar con una clave de idempotencia generada por el llamador y un secreto de recuperación separado de alta entropía (el secreto de recuperación limita esa clave al llamador). Guarda la capacidad devuelta y el secreto de recuperación en el almacén de secretos del llamador; el servidor nunca devuelve el secreto de recuperación. Reutiliza ambas claves solo para recuperar la misma subida después de una respuesta perdida. La clave de idempotencia por sí sola no puede revelar una capacidad de documento existente.
$recovery = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLowerInvariant()
$doc = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/documents `
-Headers @{ "Idempotency-Key" = "research-pdf-2026-0001"; "X-Document-Recovery-Key" = $recovery; "X-File-Name" = "research.pdf" } `
-ContentType "application/pdf" -InFile .\research.pdf
$headers = @{ Authorization = "Bearer $($doc.capability)" }
Invoke-RestMethod -Uri $doc.inspectUrl -Headers $headers
Invoke-RestMethod -Method Post -Uri "$($doc.inspectUrl)/search" -Headers $headers `
-ContentType "application/json" -Body '{"query":"revenue","limit":5}'
Invoke-RestMethod -Method Post -Uri "$($doc.inspectUrl)/read" -Headers $headers `
-ContentType "application/json" -Body '{"pages":[1,2]}'
La capacidad devuelta es un secreto de portador. Mantenlo privado y envíalo solo en el encabezado Authorization a las URLs devueltas. La subida binaria acepta como máximo 20 MiB y 100 páginas. El análisis construye un índice local acotado que contiene metadatos, etiquetas y tamaños de página, marcadores, bloques de texto nativos con cuadros delimitadores normalizados, nombres/tipos/valores de campos de formulario, recuentos de anotaciones y nombres/tamaños de archivos adjuntos incrustados. El índice está limitado a 8 MiB y 50,000 bloques de texto. GET .../map?page=1 incluye hasta 500 bloques posicionados para esa página; el mapa predeterminado devuelve resúmenes de página compactos. Los bytes del PDF fuente y el índice extraído se almacenan de forma duradera en .data/document-objects/ y .data/documents.sqlite y se eliminan al vencimiento; la retención predeterminada es de 24 horas (DOCUMENT_TTL_SECONDS puede extenderla hasta un máximo de siete días).
El endpoint MCP agrega inspect_pdf, get_document_map, search_document, batch_search_document, prepare_document_context, extract_document_fields, read_document, verify_document_citation, compare_pdfs, validate_pdf_text y render_pdf_page_region cuando el Container del analizador desplegado está configurado. MCP no sube contenido binario; primero usa la subida REST y luego pasa su ID de documento y capacidad a las herramientas.
La búsqueda es coincidencia exacta sin distinción de mayúsculas y minúsculas después de la normalización de espacios en blanco. La lectura está limitada a 10 páginas y 32,000 caracteres de salida. Las comprobaciones de citas establecen solo que el texto normalizado aparece en la página indicada y devuelven bloques de texto cercanos y sus cuadros delimitadores; no establecen la verdad ni el orden visual de lectura. La comparación informa cambios de texto normalizado a nivel de página y no inspecciona diferencias de imagen, visuales, metadatos o firmas. La validación comprueba la legibilidad del analizador, el recuento opcional de páginas y el texto requerido únicamente. Los recortes de página usan fracciones de página normalizadas y están limitados a cuatro millones de píxeles ráster y 4 MiB de salida PNG.
No se proporciona OCR, extracción/consulta de estructura de tablas, llenado de formularios, descarga de archivos adjuntos, prueba de conformidad PDF/A ni validación criptográfica de firmas. El texto nativo disperso se informa como advertencia; las páginas escaneadas no reciben texto inventado. Los enlaces PDF se conservan como texto y nunca se obtienen. Un marcador de firma PDF se muestra solo como metadato; la confianza y la validez no se verifican.
El análisis y renderizado nativo de PDF se ejecutan en el Container del analizador aislado. El Worker admite una tarea de analizador a la vez, aplica un plazo de inicio/procesamiento de 60 segundos y destruye el Container después de cada tarea para restablecer el estado del proceso y del sistema de archivos. Las subidas o renderizados concurrentes reciben 503 y deben reintentar poco después con las mismas claves de recuperación/idempotencia. También se aplican límites de memoria de subida, página, texto, índice, salida e instancia; el Container no tiene acceso a Internet saliente y no recibe secretos de pago ni de capacidad. El OCR, la comparación semántica visual, la conformidad PDF/A y la verificación criptográfica de firmas siguen sin ser compatibles y la herramienta de validación los informa explícitamente.
La clave de idempotencia está limitada al pagador verificado en modo en vivo y está vinculada a la entrada normalizada y al payload de pago. Reutilizarla con contenido o pago diferente devuelve 409; una autorización de pago duplicada exacta se rechaza usando el nonce de red/activo/pagador/autorización de EVM. Los tombstone de reproducción de pago se conservan durante al menos 30 días después del vencimiento del artefacto y del vencimiento de la autorización. La misma solicitud completada puede recuperar su capacidad original durante la vida útil del trabajo sin otro renderizado o liquidación.
Los clientes REST reciben los términos x402 v2 en una respuesta 402 y un encabezado PAYMENT-REQUIRED estándar. Los clientes MCP reciben el mismo objeto PaymentRequired como resultado de herramienta isError: true y envían el pago a través de params._meta["x402/payment"]; un resultado de herramienta liquidado incluye _meta["x402/payment-response"].
Cliente MCP con una billetera protegida
examples/mcp-client.ts demuestra el cliente HTTP Streamable del SDK MCP oficial y los campos de transporte x402 MCP. Toma un adaptador ApprovedWallet del llamador y no tiene campo de clave privada, clave de entorno ni implementación de firma. Implementa ese adaptador con una billetera de hardware, HSM, KMS o un servicio de billetera separado en sandbox; haz que el firmante aplique la red esperada, el activo USDC, el destinatario, el límite de monto y la política de nonce antes de firmar. No agregues una clave privada de larga duración al cliente MCP o al repositorio.
El ejemplo realiza una llamada no pagada para obtener el desafío, pide al firmante inyectado un payload, reintenta con _meta["x402/payment"] y luego devuelve la capacidad del trabajo para una descarga autenticada. Este es un ejemplo mínimo de ruta feliz: un cliente de producción debe persistir la clave de idempotencia y el payload de pago firmado exacto de forma segura para poder reintentar la misma solicitud, y debe conservar los detalles de recuperación devueltos después de una liquidación incierta. La omisión de desarrollo local no crea ni liquida pagos en cadena; usa una billetera de prueba configurada correctamente y un facilitador de testnet para una transferencia x402 de extremo a extremo.
Despliegue en Cloudflare
El punto de entrada del Worker es src/worker.ts. El wrangler.toml verificado contiene los enlaces de producción de D1, R2, Browser Run y el Durable Object/Container del analizador. Al desplegar en una cuenta diferente, reemplaza esos identificadores de recursos y aprovisiona los recursos correspondientes. Construir la imagen del analizador requiere un motor Docker en ejecución y una CLI de Docker en PATH. Aprovisiona los recursos usando tu cuenta de Cloudflare:
npx wrangler login
npx wrangler d1 create x402-docs-mvp
npx wrangler r2 bucket create x402-docs-mvp
Copia el database_id de D1 impreso por Wrangler en wrangler.toml y luego aplica el esquema verificado:
npx wrangler d1 migrations apply x402-docs-mvp --remote
El endpoint de estadísticas usa la tabla tool_stats_daily de la migración 0002_tool_stats.sql. Instala su contraseña como secreto del Worker antes de servir tráfico:
npx wrangler secret put STATS_PASSWORD
npx wrangler secret put DOCUMENT_CONTAINER_TOKEN
Habilita Browser Run para la cuenta y mantén el enlace [browser] en wrangler.toml. Este proyecto llama a la API documentada BROWSER.quickAction("pdf", ...). Browser Run está disponible para cuentas Workers Paid, pero el plan Paid no garantiza un máximo duro de cinco dólares: Browser Run, D1, R2 y el uso del Worker pueden generar cargos medidos. Revisa la facturación/precios actuales de Cloudflare y configura presupuestos/alertas de cuenta antes de desplegar.
Para la vista previa del lado del Worker, las Quick Actions de Browser Run requieren npx wrangler dev --remote (el wrangler dev local no implementa quickAction). El comando regular npm run dev sigue siendo completamente local y usa Playwright Chromium en su lugar.
Establece variables de Worker no secretas en el panel o en las variables de Wrangler:
PAYMENTS_MODE=live
PUBLIC_BASE_URL=https://task402.xyz
PRICE_USD=0.01
PRICE_DOCUMENT_USD=0.01
PRICE_WEB_EVIDENCE_USD=0.005
PRICE_OPENAPI_USD=0.001
PRICE_CHAIN_USD=0.001
X402_NETWORK=eip155:8453
X402_ASSET=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
X402_PAY_TO=0xAEA6fDF13ca10aD6B906884ffAcBb58a0e9E144A
X402_FACILITATOR_URL=https://facilitator.openx402.ai
MCP_ALLOWED_ORIGINS=https://<your-approved-mcp-client-origin>
STATS_PASSWORD es obligatorio en los despliegues del Worker y debe contener entre 20 y 256 caracteres. Usa un secreto aleatorio único de alta entropía. No es una credencial de pago y debe mantenerse separado de los secretos de billetera y facilitador. DOCUMENT_CONTAINER_TOKEN es un secreto interno separado que se usa solo entre el Worker y el Container del analizador. La ruta de operador protegida es GET /v1/admin/stats; para acceso telefónico, abre la página móvil en /admin. Consulta docs/AGENT-GUIDE.md.
La configuración desplegada usa USDC de Base mainnet (eip155:8453) y https://facilitator.openx402.ai. Su respuesta pública de capacidades compatibles anuncia pagos EVM exactos de Base mainnet y la extensión de descubrimiento, lo que habilita el catálogo de Bazaar cuando los clientes repiten la extensión de pago. Trata al facilitador como una dependencia de pago: revisa su disponibilidad, términos, red compatible, comportamiento de descubrimiento y comportamiento de liquidación antes de cambiar el tráfico de producción. El servicio convierte PRICE_USD a unidades USDC de seis decimales.
Instala el secreto HMAC de capacidad y, si tu facilitador lo requiere, su token de portador como secretos del Worker. Genera un secreto aleatorio de al menos 32 caracteres y no lo confirmes ni lo pegues en el archivo TOML:
npx wrangler secret put CAPABILITY_SECRET
npx wrangler secret put X402_FACILITATOR_BEARER_TOKEN
El token del facilitador es opcional para un facilitador que no requiere autenticación. Ejecuta las comprobaciones locales y luego inspecciona un paquete de despliegue antes de elegir desplegar:
npm ci
npm run typecheck
npm test
npm run deploy:dry-run
# npx wrangler deploy # explicit operator action after reviewing account config and costs
No se incluyen credenciales de billetera ni secretos de facilitador en este repositorio. La configuración de Wrangler verificada contiene los identificadores de recursos de despliegue necesarios para este proyecto; reemplázalos al desplegar en otra cuenta. El Worker requiere configuración de pago en vivo y falla cerrado si falta; no tiene omisión de desarrollo. Establece el PUBLIC_BASE_URL del Worker al origen HTTPS confiable exacto, sin ruta, credenciales, consulta o fragmento, para que los resultados MCP contengan URLs de estado/descarga absolutas sin confiar en un encabezado Host controlado por el llamador. La URL del facilitador puede contener una ruta, pero debe usar HTTPS sin credenciales de URL, consulta o fragmento.
Recuperación de liquidación
Si la liquidación agota el tiempo o el facilitador devuelve un resultado pendiente/ambiguo, el trabajo se convierte en settlement_unknown. La respuesta incluye el ID del trabajo y la capacidad para que su estado siga siendo observable. El servicio conserva el PDF renderizado y no reintentará automáticamente la liquidación con la misma autorización. Verifica el estado de la transacción del facilitador y la red de destino antes de tomar una acción de operador. No vuelvas a enviar la misma autorización: un tiempo de espera puede significar que la transacción en cadena fue aceptada incluso cuando se perdió la respuesta. Este MVP no incluye un endpoint de conciliación/administración; un operador debe conciliar contra el facilitador/red y registrar el resultado a través de un proceso operativo auditado.
Comprobaciones
npm test cubre límites de entrada, saneamiento de HTML/script/URL, idempotencia de pago y manejo de reproducción, resultados de facilitador inciertos y definitivos, análisis de PDF real, recuperación de documentos con capacidad, mapa/búsqueda/lectura/cita/comparación/validación, renderizado de recortes acotado, limpieza de vencimiento y llamadas oficiales de initialize/list/tool del SDK MCP. La generación de PDF y la paginación visual también se probaron con Chromium local contra fixtures de tablas largas/tokens largos. Estas pruebas no envían un pago real de blockchain ni validan enlaces de Cloudflare específicos de la cuenta.
Preparación para distribución
Los metadatos de directorio verificados están en server.json, glama.json y lhm.plugin.json; la evidencia de descubrimiento y la lista de verificación de publicación están en docs/DISTRIBUTION-AUDIT.md. Antes de reclamar disponibilidad en el directorio, verifica el registro en vivo del MCP Registry, el recurso de Bazaar del facilitador y cualquier URL de listado de terceros contra el contrato /v1/pricing actual. Estos archivos preparan la presentación; los directorios externos aún requieren su propio flujo de trabajo de publicador o repositorio.
Los agentes deben preferir /v1/pricing para precios actuales, /openapi.json para esquemas REST y MCP tools/list para esquemas de entrada ejecutables. Las páginas públicas /docs, /llms.txt y /sitemap.xml están intencionalmente libres de credenciales para que los rastreadores puedan entender el servicio antes de cualquier pago.