@pulumi/mcp-server

Instructions

Implementation Reference

• src/pulumi/registry.ts:357-408 (handler)

  Handler function for the 'list-resources' command that fetches the provider schema using 'pulumi package get-schema', filters resources by optional module, formats them with type, name, module, and short description, and returns as JSON or error message if none found.

  handler: async (args: ListResourcesArgs) => {
    const schema = await getSchema(args.provider, args.version);
  
    // Filter and format resources
    const resources = Object.entries(schema.resources)
      .filter(([key]) => {
        if (args.module) {
          const [, modulePath] = key.split(':');
          const mainModule = modulePath.split('/')[0];
          return mainModule === args.module;
        }
        return true;
      })
      .map(([key, resource]) => {
        const resourceName = key.split(':').pop() || '';
        const modulePath = key.split(':')[1];
        const mainModule = modulePath.split('/')[0];
        // Trim description at first '#' character
        const shortDescription =
          resource.description?.split('\n')[0].trim() ?? '<no description>';
        return {
          type: key,
          name: resourceName,
          module: mainModule,
          description: shortDescription
        };
      });
  
    if (resources.length === 0) {
      return {
        description: 'No resources found',
        content: [
          {
            type: 'text' as const,
            text: args.module
              ? `No resources found for provider '${args.provider}' in module '${args.module}'`
              : `No resources found for provider '${args.provider}'`
          }
        ]
      };
    }
  
    return {
      description: 'Lists available Pulumi Registry resources',
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(resources)
        }
      ]
    };
  }

• src/pulumi/registry.ts:338-356 (schema)

  Definition of the 'list-resources' command including description and Zod input schema for provider (required string), module (optional string), version (optional string).

  'list-resources': {
    description: 'List all resource types for a given provider and module',
    schema: {
      provider: z
        .string()
        .describe(
          "The cloud provider (e.g., 'aws', 'azure', 'gcp', 'random') or github.com/org/repo for Git-hosted components"
        ),
      module: z
        .string()
        .optional()
        .describe("Optional module to filter by (e.g., 's3', 'ec2', 'lambda')"),
      version: z
        .string()
        .optional()
        .describe(
          "The provider version to use (e.g., '6.0.0'). If not specified, uses the latest available version."
        )
    },

• src/server/server.ts:55-66 (registration)

  Code that registers all registry commands (including 'list-resources') as MCP tools with prefixed names like 'pulumi-registry-list-resources', using the command's description, schema, and handler wrapped in try-catch error handling.

  // Register registry commands
  Object.entries(registryCommands(CACHE_DIR)).forEach(([commandName, command]) => {
    const toolName = `pulumi-registry-${commandName}`;
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    this.tool(toolName, command.description, command.schema, async (args: any) => {
      try {
        return await command.handler(args);
      } catch (error) {
        return handleError(error, toolName);
      }
    });
  });

• src/pulumi/registry.ts:98-112 (helper)

  Helper function to retrieve and cache the Pulumi provider schema by executing 'pulumi package get-schema' CLI command if not cached.

  async function getSchema(provider: string, version?: string): Promise<Schema> {
    const providerWithVersion = version ? `${provider}@${version}` : provider;
    const cacheFile = path.join(
      cacheDir,
      `${providerWithVersion.replace(/[^a-zA-Z0-9]/g, '_')}_schema.json`
    );
  
    if (!fs.existsSync(cacheFile)) {
      const output = execFileSync('pulumi', ['package', 'get-schema', providerWithVersion], {
        maxBuffer: 50 * 1024 * 1024 // 50MB buffer instead of default 1MB (AWS provider schema is ~37MB)
      });
      fs.writeFileSync(cacheFile, output);
    }
    return JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
  }