import_postman_environment

Instructions

Implementation Reference

• src/server.ts:68-68 (registration)

  Registration of registerUtilityTools which includes import_postman_environment tool.

  registerUtilityTools(server, storage)

• src/server.ts:10-10 (registration)

  Import of registerUtilityTools from utilities module.

  import { registerUtilityTools } from './tools/utilities.js'

• src/tools/utilities.ts:942-1029 (handler)

  Full handler implementation of the import_postman_environment tool: reads a Postman environment JSON file, validates it, parses variables (preferring currentValue over value), creates the environment via storage, optionally activates it, and returns a success/error response.

  server.tool(
    'import_postman_environment',
    'Importa un Postman Environment (JSON) como entorno local. Soporta variables con valores initial/current.',
    {
      file: z.string().describe('Ruta al archivo .postman_environment.json exportado de Postman'),
      name: z
        .string()
        .optional()
        .describe('Nombre para el entorno (default: usa el nombre del archivo Postman)'),
      overwrite: z
        .boolean()
        .optional()
        .describe('Sobreescribir si ya existe un entorno con el mismo nombre (default: false)'),
      activate: z
        .boolean()
        .optional()
        .describe('Activar el entorno importado como entorno activo (default: false)'),
    },
    async (params) => {
      try {
        const raw = await readFile(params.file, 'utf-8')
        const postmanEnv = JSON.parse(raw)
  
        if (!postmanEnv.values || !Array.isArray(postmanEnv.values)) {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'Error: El archivo no parece ser un Postman Environment válido. Falta la propiedad "values".',
              },
            ],
            isError: true,
          }
        }
  
        const envName = params.name ?? postmanEnv.name ?? 'postman-import'
        const overwrite = params.overwrite ?? false
  
        const existing = await storage.getEnvironment(envName)
        if (existing && !overwrite) {
          return {
            content: [
              {
                type: 'text' as const,
                text: `Error: Ya existe un entorno '${envName}'. Usa overwrite: true para sobreescribir.`,
              },
            ],
            isError: true,
          }
        }
  
        // Parse variables — prefer currentValue over value (Postman v2.1 uses both)
        const variables: Record<string, string> = {}
        for (const v of postmanEnv.values) {
          if (!v.key) continue
          if (v.enabled === false) continue
          variables[v.key] = String(v.currentValue ?? v.value ?? '')
        }
  
        const now = new Date().toISOString()
        await storage.createEnvironment({
          name: envName,
          variables,
          createdAt: now,
          updatedAt: now,
        })
  
        if (params.activate) {
          await storage.setActiveEnvironment(envName)
        }
  
        const lines: string[] = [
          `Postman Environment "${envName}" importado (${Object.keys(variables).length} variables).`,
        ]
        if (params.activate) lines.push('Entorno activado como activo.')
  
        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:945-959 (schema)

  Input schema for import_postman_environment: file (string, required), name (string, optional), overwrite (boolean, optional, default false), activate (boolean, optional, default false).

  {
    file: z.string().describe('Ruta al archivo .postman_environment.json exportado de Postman'),
    name: z
      .string()
      .optional()
      .describe('Nombre para el entorno (default: usa el nombre del archivo Postman)'),
    overwrite: z
      .boolean()
      .optional()
      .describe('Sobreescribir si ya existe un entorno con el mismo nombre (default: false)'),
    activate: z
      .boolean()
      .optional()
      .describe('Activar el entorno importado como entorno activo (default: false)'),
  },

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

  Function signature registerUtilityTools that groups all utility tool registrations including import_postman_environment.

  export function registerUtilityTools(server: McpServer, storage: Storage): void {