import_collection

Instructions

Implementation Reference

• src/tools/utilities.ts:451-540 (handler)

  The handler function for the import_collection tool. Reads a collection.json file, validates its format, iterates over SavedRequest entries, optionally skips existing ones or overwrites, adds an extra tag if provided, and saves each request via storage.saveCollection().

  async (params) => {
    try {
      // Auto-detect file
      const filePath = await findFile(params.file, 'collection.json')
      if (!filePath) {
        return {
          content: [
            {
              type: 'text' as const,
              text: 'No se encontró collection.json. Busqué en .atm/ y en el directorio actual.\nEspecifica la ruta con el parámetro "file".',
            },
          ],
          isError: true,
        }
      }
  
      const raw = await readFile(filePath, 'utf-8')
      const bundle = JSON.parse(raw)
  
      if (bundle._format !== 'api-testing-mcp' || !Array.isArray(bundle.requests)) {
        return {
          content: [
            {
              type: 'text' as const,
              text: 'Error: El archivo no es un export nativo válido. Verifica que fue generado con export_collection.',
            },
          ],
          isError: true,
        }
      }
  
      const overwrite = params.overwrite ?? false
      const extraTag = params.tag
      let imported = 0
      let skipped = 0
      const errors: string[] = []
  
      for (const req of bundle.requests as SavedRequest[]) {
        try {
          if (!req.name || !req.request) {
            errors.push(`Request sin nombre o configuración — omitido`)
            continue
          }
  
          if (!overwrite) {
            const existing = await storage.getCollection(req.name)
            if (existing) {
              skipped++
              continue
            }
          }
  
          // Add extra tag if provided
          if (extraTag) {
            const tags = req.tags ?? []
            if (!tags.includes(extraTag)) tags.push(extraTag)
            req.tags = tags
          }
  
          // Update timestamp
          req.updatedAt = new Date().toISOString()
  
          await storage.saveCollection(req)
          imported++
        } catch (err) {
          const msg = err instanceof Error ? err.message : String(err)
          errors.push(`${req.name ?? 'unknown'}: ${msg}`)
        }
      }
  
      const lines: string[] = [
        `Colección importada: ${imported} requests guardados (desde ${filePath}).`,
      ]
      if (skipped > 0) lines.push(`${skipped} requests omitidos (ya existían, usa overwrite: true para sobreescribir).`)
      if (errors.length > 0) {
        lines.push(`${errors.length} errores:`)
        for (const e of errors) lines.push(`  - ${e}`)
      }
  
      return {
        content: [{ type: 'text' as const, text: lines.join('\n') }],
      }
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error)
      return {
        content: [{ type: 'text' as const, text: `Error: ${message}` }],
        isError: true,
      }
    }
  },

• src/tools/utilities.ts:438-450 (schema)

  Zod schema for tool inputs: file (optional string), tag (optional string), overwrite (optional boolean).

    file: z
      .string()
      .optional()
      .describe('Ruta al archivo (default: busca en .atm/collection.json)'),
    tag: z
      .string()
      .optional()
      .describe('Tag adicional para aplicar a todos los requests importados'),
    overwrite: z
      .boolean()
      .optional()
      .describe('Sobreescribir requests existentes con el mismo nombre (default: false)'),
  },

• src/tools/utilities.ts:434-541 (registration)

  Registration of the 'import_collection' tool on the MCP server with name, description, input schema, and handler callback.

  server.tool(
    'import_collection',
    'Importa requests desde .atm/collection.json o un archivo específico. Auto-detecta .atm/ en el proyecto.',
    {
      file: z
        .string()
        .optional()
        .describe('Ruta al archivo (default: busca en .atm/collection.json)'),
      tag: z
        .string()
        .optional()
        .describe('Tag adicional para aplicar a todos los requests importados'),
      overwrite: z
        .boolean()
        .optional()
        .describe('Sobreescribir requests existentes con el mismo nombre (default: false)'),
    },
    async (params) => {
      try {
        // Auto-detect file
        const filePath = await findFile(params.file, 'collection.json')
        if (!filePath) {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'No se encontró collection.json. Busqué en .atm/ y en el directorio actual.\nEspecifica la ruta con el parámetro "file".',
              },
            ],
            isError: true,
          }
        }
  
        const raw = await readFile(filePath, 'utf-8')
        const bundle = JSON.parse(raw)
  
        if (bundle._format !== 'api-testing-mcp' || !Array.isArray(bundle.requests)) {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'Error: El archivo no es un export nativo válido. Verifica que fue generado con export_collection.',
              },
            ],
            isError: true,
          }
        }
  
        const overwrite = params.overwrite ?? false
        const extraTag = params.tag
        let imported = 0
        let skipped = 0
        const errors: string[] = []
  
        for (const req of bundle.requests as SavedRequest[]) {
          try {
            if (!req.name || !req.request) {
              errors.push(`Request sin nombre o configuración — omitido`)
              continue
            }
  
            if (!overwrite) {
              const existing = await storage.getCollection(req.name)
              if (existing) {
                skipped++
                continue
              }
            }
  
            // Add extra tag if provided
            if (extraTag) {
              const tags = req.tags ?? []
              if (!tags.includes(extraTag)) tags.push(extraTag)
              req.tags = tags
            }
  
            // Update timestamp
            req.updatedAt = new Date().toISOString()
  
            await storage.saveCollection(req)
            imported++
          } catch (err) {
            const msg = err instanceof Error ? err.message : String(err)
            errors.push(`${req.name ?? 'unknown'}: ${msg}`)
          }
        }
  
        const lines: string[] = [
          `Colección importada: ${imported} requests guardados (desde ${filePath}).`,
        ]
        if (skipped > 0) lines.push(`${skipped} requests omitidos (ya existían, usa overwrite: true para sobreescribir).`)
        if (errors.length > 0) {
          lines.push(`${errors.length} errores:`)
          for (const e of errors) lines.push(`  - ${e}`)
        }
  
        return {
          content: [{ type: 'text' as const, text: lines.join('\n') }],
        }
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error)
        return {
          content: [{ type: 'text' as const, text: `Error: ${message}` }],
          isError: true,
        }
      }
    },
  )

• src/tools/utilities.ts:1121-1139 (helper)

  Helper function findFile used by import_collection to auto-detect the collection.json file path (checks .atm/ subdirectory and current working directory).

  async function findFile(explicit: string | undefined, fileName: string): Promise<string | null> {
    if (explicit) return explicit
  
    const candidates = [
      join(process.cwd(), '.atm', fileName),
      join(process.cwd(), fileName),
    ]
  
    for (const candidate of candidates) {
      try {
        await access(candidate)
        return candidate
      } catch {
        // Not found, try next
      }
    }
  
    return null
  }