@karlangas12/openapi-to-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karlangas12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+# 🔌 openapi-to-mcp
+
+**Convierte cualquier especificación OpenAPI 3.x en un servidor MCP en vivo.**
+Apúntalo a una spec (fichero o URL) y cada endpoint se vuelve una herramienta
+validada que tu agente de IA puede invocar — sin código pegamento, sin escribir
+un servidor por cada API.
+
+[![CI](https://github.com/Karlangas12/openapi-to-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Karlangas12/openapi-to-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@karlangas12/openapi-to-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/@karlangas12/openapi-to-mcp)
+[![tests](https://img.shields.io/badge/tests-32%20passing-brightgreen)](#pruebas)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[English](README.md)
+
+</div>
+
+---
+
+## Por qué
+
+MCP permite a un agente invocar herramientas, pero alguien tiene que escribirlas.
+Si la capacidad que quieres ya existe como una API REST con especificación
+OpenAPI, escribir un servidor MCP a medida para ella es trabajo mecánico.
+
+`openapi-to-mcp` lee la especificación y hace el mapeo por ti: cada
+`MÉTODO /ruta` se convierte en una herramienta, cada parámetro y cuerpo de
+petición se vuelve una entrada **validada con Zod**, y cada llamada se traduce a
+una petición HTTP con tu cabecera de autenticación. La respuesta vuelve recortada
+para la ventana de contexto de un LLM.
+
+## Inicio rápido
+
+Sin instalación: ejecútalo directamente desde npm.
+
+```bash
+npx @karlangas12/openapi-to-mcp --spec https://api.example.com/openapi.json \
+  --auth-header "Authorization: Bearer TU_TOKEN"
+```
+
+Mira qué herramientas produce una spec sin arrancar el servidor:
+
+```bash
+npx @karlangas12/openapi-to-mcp --spec ./openapi.yaml --list
+```
+
+### Claude Desktop — `claude_desktop_config.json`
+
+```jsonc
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "npx",
+      "args": [
+        "-y", "@karlangas12/openapi-to-mcp",
+        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json",
+        "--auth-header", "Authorization: Bearer TU_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+Reinicia el cliente y los endpoints de la API aparecen como herramientas.
+
+## Cómo mapea
+
+| OpenAPI | Se convierte en |
+| --- | --- |
+| `operationId`, o `MÉTODO /ruta` si falta | Nombre de la herramienta (`get_pets_by_pet_id`) |
+| `summary` / `description` | Descripción de la herramienta |
+| Parámetros de ruta, query y cabecera | Propiedades de entrada (los de ruta son obligatorios) |
+| `requestBody` (`application/json`) | Una propiedad `body` |
+| Cada schema de entrada | Un validador **Zod** + un JSON Schema para `tools/list` |
+| `$ref` local (`#/components/...`) | Resuelto en línea |
+| `enum`, `minimum`/`maximum`, `required`, `nullable`, `oneOf`/`anyOf`/`allOf` | Exigidos en la entrada |
+
+Los argumentos se validan **antes** de que salga ninguna petición HTTP. Una
+respuesta `4xx`/`5xx` vuelve como resultado de error que el modelo puede leer y
+corregir, no como un fallo silencioso.
+
+## Emparejar con mcp-shield-proxy
+
+`openapi-to-mcp` habla con una **API de terceros** en tu nombre y con tus
+credenciales. Si quieres una política, enmascarado de credenciales y un registro
+de auditoría alrededor, envuélvelo con
+[mcp-shield-proxy](https://www.npmjs.com/package/mcp-shield-proxy) — se componen
+con una línea más:
+
+```jsonc
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-shield-proxy", "--",
+        "npx", "-y", "@karlangas12/openapi-to-mcp",
+        "--spec", "https://api.example.com/openapi.json",
+        "--auth-header", "Authorization: Bearer TU_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+## Limitaciones honestas
+
+- **Sólo transporte stdio.** Cubre Claude Desktop, Cursor y Claude Code. Servir
+  por HTTP/SSE nativo aún no está implementado.
+- **Sólo `$ref` locales.** Las referencias internas (`#/components/...`) se
+  resuelven; las externas (a otros ficheros o URLs) dan un error claro.
+- **Cuerpos `application/json`.** `multipart/form-data` y formularios aún no.
+- **Es un mapeador, no una pasarela.** No añade reintentos, caché ni límites de
+  tasa. Emparéjalo con un proxy si los necesitas.
+
+## Pruebas
+
+```bash
+npm test          # 32 tests
+npm run typecheck # TypeScript estricto
+```
+
+Cubre el parseo JSON **y** YAML, la conversión endpoint→herramienta con esquemas
+Zod, y un `tools/call` completo por JSON-RPC contra un backend HTTP simulado.
+
+## Licencia
+
+MIT

package/README.md

@@ -0,0 +1,222 @@
+<div align="center">
+
+# 🔌 openapi-to-mcp
+
+**Turn any OpenAPI 3.x spec into a live MCP server.**
+Point it at a spec (file or URL) and every endpoint becomes a validated tool your
+AI agent can call — no glue code, no per-API server to write.
+
+[![CI](https://github.com/Karlangas12/openapi-to-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Karlangas12/openapi-to-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@karlangas12/openapi-to-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/@karlangas12/openapi-to-mcp)
+[![tests](https://img.shields.io/badge/tests-32%20passing-brightgreen)](#testing)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[Quick start](#quick-start) · [How it maps](#how-it-maps) · [Config](#configuration) · [Secure it](#pairing-with-mcp-shield-proxy) · [Limits](#honest-limitations) · [Español](README.es.md)
+
+</div>
+
+```
+  OpenAPI 3.x spec                         your AI client
+ (JSON / YAML, file or URL)               (Claude, Cursor)
+          │                                      │
+          ▼                                      │  MCP / JSON-RPC (stdio)
+ [ openapi-to-mcp ]  ◀───────────────────────────┘
+          │  GET /pets/{id} → tool "get_pet_by_id"
+          ▼  HTTP + your auth header
+   the underlying REST API
+```
+
+---
+
+## Why
+
+MCP lets an agent call tools, but someone has to write those tools. If the
+capability you want already exists as a REST API with an OpenAPI spec, writing a
+bespoke MCP server for it is busywork.
+
+`openapi-to-mcp` reads the spec and does the mapping for you: each `METHOD /path`
+becomes a tool, each parameter and request body becomes a **Zod-validated** input,
+and every call is turned into an HTTP request with your auth header attached. The
+response comes back trimmed for an LLM context window.
+
+## Quick start
+
+No install needed — run it straight from npm:
+
+```bash
+npx @karlangas12/openapi-to-mcp --spec https://api.example.com/openapi.json \
+  --auth-header "Authorization: Bearer YOUR_TOKEN"
+```
+
+See what tools a spec produces without starting a server:
+
+```bash
+npx @karlangas12/openapi-to-mcp --spec ./openapi.yaml --list
+```
+
+### Claude Desktop — `claude_desktop_config.json`
+
+```jsonc
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "npx",
+      "args": [
+        "-y", "@karlangas12/openapi-to-mcp",
+        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json",
+        "--auth-header", "Authorization: Bearer YOUR_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+### Cursor — `.cursor/mcp.json`
+
+```jsonc
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": [
+        "-y", "@karlangas12/openapi-to-mcp",
+        "--spec", "./openapi.yaml",
+        "--base-url", "https://api.internal.company.com"
+      ]
+    }
+  }
+}
+```
+
+That's the whole integration. Restart the client and the API's endpoints show up
+as tools.
+
+## How it maps
+
+| OpenAPI | Becomes |
+| --- | --- |
+| `operationId`, or `METHOD /path` if absent | Tool name (`get_pets_by_pet_id`) |
+| `summary` / `description` | Tool description |
+| Path, query and header parameters | Tool input properties (path params are required) |
+| `requestBody` (`application/json`) | A `body` input property |
+| Every input schema | A **Zod** validator + a JSON Schema for `tools/list` |
+| Local `$ref` (`#/components/...`) | Resolved inline |
+| `enum`, `minimum`/`maximum`, `required`, `nullable`, `oneOf`/`anyOf`/`allOf` | Enforced on input |
+
+When the agent calls a tool, arguments are validated **before** any HTTP request
+goes out. Path params are substituted into the URL, query params are appended,
+header params and your static `--auth-header` values are sent, and a JSON body is
+serialized. A `4xx`/`5xx` response comes back as an error result the model can
+read and react to — not a silent failure.
+
+## Configuration
+
+```
+openapi-to-mcp --spec <path|url> [options]
+
+  -s, --spec <path|url>    OpenAPI 3.x spec (JSON or YAML, local or remote)
+      --base-url <url>     API base URL (when the spec declares no "servers")
+  -H, --auth-header <h>    Header to forward, "Name: value" (repeatable)
+      --format <mode>      Response format: markdown (default) or json
+  -n, --name <name>        MCP server name
+      --list               Print the generated tools and exit
+  -h, --help / -v, --version
+```
+
+Multiple headers:
+
+```bash
+npx @karlangas12/openapi-to-mcp --spec ./api.yaml \
+  --auth-header "Authorization: Bearer XYZ" \
+  --auth-header "X-Api-Version: 2024-01"
+```
+
+### Export a standalone server (codegen)
+
+```bash
+npx @karlangas12/openapi-to-mcp codegen --spec ./api.yaml -o server.ts
+```
+
+Writes a single self-contained TypeScript file that embeds the spec and boots the
+server via this package — handy for committing a pinned server to a repo.
+
+## Pairing with mcp-shield-proxy
+
+`openapi-to-mcp` talks to a **third-party API** on your behalf, with your
+credentials. If you want a policy, credential masking and an audit trail around
+that, wrap it with [mcp-shield-proxy](https://www.npmjs.com/package/mcp-shield-proxy)
+— they compose with one extra line:
+
+```jsonc
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-shield-proxy", "--",          // ← inspect, mask, audit
+        "npx", "-y", "@karlangas12/openapi-to-mcp",
+        "--spec", "https://api.example.com/openapi.json",
+        "--auth-header", "Authorization: Bearer YOUR_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+Now every generated tool call is policy-checked, credentials in the traffic are
+masked, and the whole session lands in a verifiable audit log.
+
+## Use as a library
+
+```ts
+import { loadSpec, buildTools, createMcpServer, startStdioServer } from '@karlangas12/openapi-to-mcp';
+
+const doc = await loadSpec('./openapi.yaml');
+const { tools, baseUrl } = buildTools(doc);
+
+const server = createMcpServer({
+  tools,
+  baseUrl: baseUrl ?? 'https://api.example.com',
+  headers: { Authorization: 'Bearer YOUR_TOKEN' },
+  fetchFn: (url, init) => fetch(url, init as RequestInit),
+});
+
+startStdioServer(server);
+```
+
+The parser, the schema→Zod converter and the tool builder are all exported
+independently.
+
+## Honest limitations
+
+- **stdio transport only.** The MCP server speaks stdio, which covers Claude
+  Desktop, Cursor and Claude Code. Native HTTP/SSE serving isn't implemented yet.
+- **Local `$ref` only.** References inside the document (`#/components/...`) are
+  resolved. External refs (other files or URLs) are not — they raise a clear
+  error rather than failing quietly.
+- **`application/json` bodies.** Request bodies are mapped for JSON content.
+  `multipart/form-data` and `application/x-www-form-urlencoded` aren't mapped yet.
+- **It's a mapper, not a gateway.** It doesn't add retries, caching or rate
+  limiting. Pair it with a proxy if you need those.
+
+## Performance
+
+The spec is parsed once at startup; after that, each tool call is a schema
+validation plus one HTTP request. Parsing and tool generation for a typical spec
+is sub-millisecond — the latency you feel is the underlying API's, not this.
+
+## Testing
+
+```bash
+npm test          # 32 tests
+npm run typecheck # strict TypeScript
+```
+
+Coverage includes JSON **and** YAML parsing, endpoint→tool conversion with Zod
+schemas, and a full `tools/call` round trip over JSON-RPC against a mocked HTTP
+backend (asserting the URL, method, headers and body that reach it).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { writeFile } from 'node:fs/promises';
+import { createLogger } from './core/telemetry/index.js';
+import { toAppError } from './utils/errors.js';
+import { loadSpec } from './openapi/load.js';
+import { buildTools } from './generator/operations.js';
+import { generateServerCode } from './generator/codegen.js';
+import { createMcpServer } from './mcp/server.js';
+import { startStdioServer } from './mcp/stdio.js';
+const VERSION = '0.1.0';
+/** Transporte que manda TODO a stderr: stdout queda limpio para el protocolo MCP. */
+const stderrTransport = {
+    emit(record) {
+        process.stderr.write(`${JSON.stringify(record)}\n`);
+    },
+};
+/** Envoltorio del `fetch` global con la forma desacoplada `FetchLike`. */
+const nodeFetch = (url, init) => fetch(url, init);
+async function runCli(argv) {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        printHelp();
+        return;
+    }
+    if (argv.includes('--version') || argv.includes('-v')) {
+        process.stdout.write(`openapi-to-mcp v${VERSION}\n`);
+        return;
+    }
+    const isCodegen = argv[0] === 'codegen';
+    const options = parseArgs(isCodegen ? argv.slice(1) : argv);
+    if (options.spec === undefined) {
+        throw toAppError(new Error('Falta --spec <ruta|url> con la especificación OpenAPI.'));
+    }
+    const doc = await loadSpec(options.spec, { fetchFn: nodeFetch });
+    if (isCodegen) {
+        await runCodegen(doc, options);
+        return;
+    }
+    const { tools, baseUrl } = buildTools(doc, options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl });
+    if (options.list) {
+        process.stdout.write(`${tools.length} herramienta(s) generada(s):\n`);
+        for (const tool of tools)
+            process.stdout.write(`  ${tool.name}  —  ${tool.description}\n`);
+        return;
+    }
+    const resolvedBaseUrl = options.baseUrl ?? baseUrl;
+    if (resolvedBaseUrl === undefined || resolvedBaseUrl === '') {
+        throw toAppError(new Error('No hay URL base para la API. Declara "servers" en la especificación o pásala con --base-url.'));
+    }
+    const logger = createLogger({ service: 'openapi-to-mcp', transport: stderrTransport });
+    const server = createMcpServer({
+        tools,
+        baseUrl: resolvedBaseUrl,
+        headers: options.headers,
+        fetchFn: nodeFetch,
+        formatMode: options.format,
+        logger,
+        ...(options.name === undefined ? {} : { serverInfo: { name: options.name, version: VERSION } }),
+    });
+    logger.info('servidor MCP listo', { tools: tools.length, baseUrl: resolvedBaseUrl });
+    startStdioServer(server);
+}
+async function runCodegen(doc, options) {
+    const code = generateServerCode(doc, {
+        ...(options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
+        ...(options.name === undefined ? {} : { serverName: options.name }),
+    });
+    if (options.codegenOut === undefined) {
+        process.stdout.write(code);
+        return;
+    }
+    await writeFile(options.codegenOut, code, 'utf8');
+    process.stdout.write(`✓ Servidor MCP generado en ${options.codegenOut}\n`);
+}
+function parseArgs(argv) {
+    const options = { headers: {}, format: 'markdown', list: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--spec':
+            case '-s':
+                options.spec = requireValue(argv, (i += 1), arg);
+                break;
+            case '--url':
+                // Alias práctico: si te pasan la URL de la especificación como --url.
+                options.spec = requireValue(argv, (i += 1), arg);
+                break;
+            case '--base-url':
+                options.baseUrl = requireValue(argv, (i += 1), arg);
+                break;
+            case '--auth-header':
+            case '--header':
+            case '-H': {
+                const [name, value] = splitHeader(requireValue(argv, (i += 1), arg));
+                options.headers[name] = value;
+                break;
+            }
+            case '--format':
+                options.format = parseFormat(requireValue(argv, (i += 1), arg));
+                break;
+            case '--name':
+            case '-n':
+                options.name = requireValue(argv, (i += 1), arg);
+                break;
+            case '--out':
+            case '-o':
+                options.codegenOut = requireValue(argv, (i += 1), arg);
+                break;
+            case '--list':
+                options.list = true;
+                break;
+            default:
+                // Primer argumento posicional sin bandera: se toma como --spec.
+                if (arg !== undefined && !arg.startsWith('-') && options.spec === undefined) {
+                    options.spec = arg;
+                }
+                break;
+        }
+    }
+    return options;
+}
+function requireValue(argv, index, flag) {
+    const value = argv[index];
+    if (value === undefined) {
+        throw toAppError(new Error(`La opción ${flag} necesita un valor.`));
+    }
+    return value;
+}
+function splitHeader(raw) {
+    const separator = raw.indexOf(':');
+    if (separator === -1) {
+        throw toAppError(new Error(`Cabecera mal formada: "${raw}". Usa el formato "Nombre: valor".`));
+    }
+    return [raw.slice(0, separator).trim(), raw.slice(separator + 1).trim()];
+}
+function parseFormat(raw) {
+    if (raw === 'json' || raw === 'markdown')
+        return raw;
+    throw toAppError(new Error(`Formato no válido: "${raw}". Usa "markdown" o "json".`));
+}
+function printHelp() {
+    process.stdout.write(`openapi-to-mcp v${VERSION} — sirve cualquier OpenAPI 3.x como servidor MCP
+
+USO
+  openapi-to-mcp --spec <ruta|url> [opciones]   Levanta un servidor MCP por stdio
+  openapi-to-mcp --spec <ruta|url> --list       Lista las herramientas y sale
+  openapi-to-mcp codegen --spec <ruta|url> -o server.ts   Exporta un servidor autocontenido
+
+OPCIONES
+  -s, --spec <ruta|url>    Especificación OpenAPI (JSON o YAML, local o remota)
+      --base-url <url>     URL base de la API (si la spec no declara "servers")
+  -H, --auth-header <h>    Cabecera a propagar, "Nombre: valor" (repetible)
+      --format <modo>      Formato de respuesta: markdown (por defecto) o json
+  -n, --name <nombre>      Nombre del servidor MCP
+      --list               Muestra las herramientas generadas y termina
+  -o, --out <fichero>      (codegen) Fichero de salida
+  -h, --help               Esta ayuda
+  -v, --version            Versión
+
+EJEMPLO
+  openapi-to-mcp --spec https://api.example.com/openapi.json \\
+    --auth-header "Authorization: Bearer XYZ"
+`);
+}
+void runCli(process.argv.slice(2)).catch((error) => {
+    const appError = toAppError(error);
+    process.stderr.write(`✗ ${appError.message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/telemetry/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Telemetría unificada: logging estructurado y métricas.
+ *
+ * Diseño pensado para el edge:
+ * - Sin dependencias externas: el transporte por defecto es la consola.
+ * - Estructurado en JSON, para que Better Stack / Axiom lo indexen tal cual.
+ * - Redacción automática de secretos: nunca queremos una API key en los logs.
+ *
+ * Uso típico en un Worker:
+ *
+ *   const log = createLogger({ level: config.LOG_LEVEL, service: 'mi-activo' });
+ *   log.info('petición recibida', { path: '/v1/generar' });
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Campos arbitrarios que acompañan a un registro. */
+export type LogContext = Readonly<Record<string, unknown>>;
+/** Un registro ya estructurado, listo para enviarse al transporte. */
+export interface LogRecord {
+    readonly timestamp: string;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly service: string;
+    readonly context: Record<string, unknown>;
+}
+/** Destino de los registros. Implementa uno propio para Axiom, Better Stack, etc. */
+export interface Transport {
+    emit(record: LogRecord): void;
+}
+/**
+ * Recorre un valor y redacta los campos sensibles.
+ *
+ * Limita la profundidad para no atascarse con estructuras enormes o cíclicas
+ * (un log nunca debe ser el cuello de botella de una petición).
+ */
+export declare function redact(value: unknown, depth?: number): unknown;
+/** Transporte por defecto: una línea JSON por registro en la consola. */
+export declare const consoleTransport: Transport;
+/**
+ * Transporte HTTP genérico para Better Stack, Axiom o cualquier colector que
+ * acepte JSON por POST.
+ *
+ * Los envíos son "fire and forget": si el colector falla no queremos tumbar la
+ * petición del usuario. Pasa el `Promise` a `ctx.waitUntil()` en un Worker si
+ * necesitas garantizar la entrega antes de que muera el aislado.
+ */
+export declare function createHttpTransport(options: {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly onFlush?: (promise: Promise<unknown>) => void;
+}): Transport;
+/** Emite cada registro a varios destinos a la vez. */
+export declare function combineTransports(...transports: readonly Transport[]): Transport;
+export interface Logger {
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    /** Deriva un logger hijo que arrastra contexto fijo (petición, usuario...). */
+    child(context: LogContext): Logger;
+    /** Registra una métrica puntual (contador, duración, etc.). */
+    metric(name: string, value: number, context?: LogContext): void;
+}
+export interface LoggerOptions {
+    /** Umbral mínimo: los registros por debajo se descartan. */
+    readonly level?: LogLevel;
+    /** Nombre del activo, para distinguir orígenes en el colector. */
+    readonly service?: string;
+    /** Destino de los registros. Por defecto, la consola. */
+    readonly transport?: Transport;
+    /** Contexto fijo que acompaña a todos los registros. */
+    readonly context?: LogContext;
+    /** Fuente de la marca de tiempo. Inyectable para los tests. */
+    readonly now?: () => number;
+}
+/** Crea un logger estructurado. */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/** Logger silencioso, útil en tests que no deben ensuciar la salida. */
+export declare const silentLogger: Logger;