mcp-after-effects

Instructions

Implementation Reference

• src/index.ts:219-278 (handler)

  The handler function for the 'run-script' MCP tool. It validates the script against a whitelist of allowed scripts, clears any stale results file, writes the script name and parameters to a temporary command file (ae_command.json) in the system temp directory for the After Effects MCP Bridge panel to detect and execute, and returns a text response instructing the user to check results with the 'get-results' tool.

  async ({ script, parameters = {} }) => {
    // Validate that script is safe (only allow predefined scripts)
    const allowedScripts = [
      "listCompositions", 
      "getProjectInfo", 
      "getLayerInfo", 
      "createComposition",
      "createTextLayer",
      "createShapeLayer",
      "createSolidLayer",
      "setLayerProperties",
      "setLayerKeyframe",
      "setLayerExpression",
      "applyEffect",
      "applyEffectTemplate",
      "test-animation",
      "bridgeTestEffects"
    ];
    
    if (!allowedScripts.includes(script)) {
      return {
        content: [
          {
            type: "text",
            text: `Error: Script "${script}" is not allowed. Allowed scripts are: ${allowedScripts.join(", ")}`
          }
        ],
        isError: true
      };
    }
  
    try {
      // Clear any stale result data
      clearResultsFile();
      
      // Write command to file for After Effects to pick up
      writeCommandFile(script, parameters);
      
      return {
        content: [
          {
            type: "text",
            text: `Command to run "${script}" has been queued.\n` +
                  `Please ensure the "MCP Bridge Auto" panel is open in After Effects.\n` +
                  `Use the "get-results" tool after a few seconds to check for results.`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error queuing command: ${String(error)}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:216-218 (schema)

  The input schema for the 'run-script' tool using Zod: requires 'script' string (predefined script name), optional 'parameters' as any record.

    script: z.string().describe("Name of the predefined script to run"),
    parameters: z.record(z.any()).optional().describe("Optional parameters for the script")
  },

• src/index.ts:212-279 (registration)

  The MCP server registration of the 'run-script' tool using server.tool(), specifying name, description, input schema, and handler function.

  server.tool(
    "run-script",
    "Run a read-only script in After Effects",
    {
      script: z.string().describe("Name of the predefined script to run"),
      parameters: z.record(z.any()).optional().describe("Optional parameters for the script")
    },
    async ({ script, parameters = {} }) => {
      // Validate that script is safe (only allow predefined scripts)
      const allowedScripts = [
        "listCompositions", 
        "getProjectInfo", 
        "getLayerInfo", 
        "createComposition",
        "createTextLayer",
        "createShapeLayer",
        "createSolidLayer",
        "setLayerProperties",
        "setLayerKeyframe",
        "setLayerExpression",
        "applyEffect",
        "applyEffectTemplate",
        "test-animation",
        "bridgeTestEffects"
      ];
      
      if (!allowedScripts.includes(script)) {
        return {
          content: [
            {
              type: "text",
              text: `Error: Script "${script}" is not allowed. Allowed scripts are: ${allowedScripts.join(", ")}`
            }
          ],
          isError: true
        };
      }
  
      try {
        // Clear any stale result data
        clearResultsFile();
        
        // Write command to file for After Effects to pick up
        writeCommandFile(script, parameters);
        
        return {
          content: [
            {
              type: "text",
              text: `Command to run "${script}" has been queued.\n` +
                    `Please ensure the "MCP Bridge Auto" panel is open in After Effects.\n` +
                    `Use the "get-results" tool after a few seconds to check for results.`
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error queuing command: ${String(error)}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:156-170 (helper)

  Helper function called by the handler to serialize the script command and parameters to ae_command.json in system temp directory, which is polled by the After Effects bridge script.

  function writeCommandFile(command: string, args: Record<string, any> = {}): void {
    try {
      const commandFile = path.join(process.env.TEMP || process.env.TMP || '', 'ae_command.json');
      const commandData = {
        command,
        args,
        timestamp: new Date().toISOString(),
        status: "pending"  // pending, running, completed, error
      };
      fs.writeFileSync(commandFile, JSON.stringify(commandData, null, 2));
      console.error(`Command "${command}" written to ${commandFile}`);
    } catch (error) {
      console.error("Error writing command file:", error);
    }
  }

• src/index.ts:173-189 (helper)

  Helper function called by the handler to reset the results file ae_mcp_result.json to a 'waiting' state before queuing a new command, preventing stale data.

  function clearResultsFile(): void {
    try {
      const resultFile = path.join(process.env.TEMP || process.env.TMP || '', 'ae_mcp_result.json');
      
      // Write a placeholder message to indicate the file is being reset
      const resetData = {
        status: "waiting",
        message: "Waiting for new result from After Effects...",
        timestamp: new Date().toISOString()
      };
      
      fs.writeFileSync(resultFile, JSON.stringify(resetData, null, 2));
      console.error(`Results file cleared at ${resultFile}`);
    } catch (error) {
      console.error("Error clearing results file:", error);
    }
  }