---
name: mindlogic_plugin
description: Instructions and guidelines for developing plugins (.mlplugin) for the MindLogic application.
---

# MindLogic Plugin Development Guide

MindLogic supports dynamically loadable plugins (`.mlplugin`) that allow users to add custom nodes, HTTP requests, LLM API calls, or custom logic to their workflow graphs.

When asked to create or modify a MindLogic plugin, follow these guidelines.

## Plugin Structure
A MindLogic plugin (`.mlplugin`) is simply a ZIP archive containing:
1. `plugin.json` (Required): The JSON serialization of the `PluginDefinition` schema.
2. `icon.png` (Optional): A square PNG icon for the plugin.

## PluginDefinition Schema (plugin.json)

```json
{
  "id": "com.yourname.plugin.identifier",
  "name": "Display Name of Plugin",
  "description": "Short description of what it does",
  "version": "1.0.0",
  "author": "Your Name",
  "inputs": [
    {
      "key": "prompt",
      "label": "Prompt text",
      "type": "textarea",
      "defaultValue": "Analyze this data."
    }
  ],
  "globalInputs": [
    {
      "key": "apiKey",
      "label": "API Key",
      "type": "secure_text"
    }
  ],
  "scriptTemplate": "// Your JavaScript code here\\nlet apiKey = '{{apiKey}}';\\nlet prompt = '{{prompt}}';\\nconsole.log(prompt);"
}
```

### PluginInputSchema
Defines the UI fields the user must fill out.
- `key`: String identifier for the input.
- `label`: Display name in the inspector.
- `type`: String. Supported types: `"text"`, `"textarea"`, `"secure_text"`, `"dropdown"`.
- `defaultValue`: Optional default string.
- `options`: Optional array of strings for the `"dropdown"` type.
- `placeholder`: Optional placeholder string.

- `inputs`: Node-specific configurations (configured when the user selects a node on the canvas).
- `globalInputs`: Global configurations (configured in the Plugin Center, ideal for API keys and endpoint URLs).

## JavaScript Runtime & APIs

The `scriptTemplate` contains JavaScript code executed by the MindLogic JS Engine (JavaScriptCore).

### Template Injection
MindLogic injects user configurations into `scriptTemplate` before execution by replacing `{{key}}` with the actual value (from either node `inputs` or `globalInputs`). 
**Always surround placeholders with quotes if they are meant to be strings:**
```javascript
let myVar = "{{myInputKey}}"; 
```

### System APIs
The JS environment provides access to native operations through the `system` object:
- `system.request(url, options)`: Asynchronous HTTP request. Use `await system.request(url, { method: "POST", headers: {...}, body: "..." })`. Returns a string.
- `system.fetch(url)`: Simple GET request. Returns a string.
- `system.readFile(path)`: Reads a file from the file system.
- `system.openFileDialog()`: Prompts the user to select a file and returns the path.
- `system.extractPDF(url)`: Asynchronously extracts text from a PDF file located at the specified URL/path. Returns a string.
- `system.sleep(ms)`: Returns a Promise that resolves after `ms` milliseconds. Use `await system.sleep(1000)`.

### Node APIs
When a plugin runs, it evaluates specifically for the currently executing node. The current node is exposed as the `node` object.
**There is NO global `doc` object available in node scripts.**

The `node` object provides access to the current node's properties:
- `node.title`
- `node.confidence`
- `node.statusIcon` (String): Bottom right icon. Built-in shortcuts: `check`, `complete`, `error`, `warning`, `loading`, `uncheck`, `none`. You can also use any SF Symbols name.
- `node.classID`
- `node.classDisplayName`
- `node.customClassName`
- `node.tags` (Dictionary)
- `node.outputs` (Dictionary)

Methods on `node`:
- `node.setTag(key, value)`: Sets a tag on the node.
- `node.getTag(key)`: Gets a tag value.
- `node.removeTag(key)`: Removes a tag.

## Best Practices
1. **Error Handling & Status**: Use `try...catch` blocks around JSON parsing and network requests. If your script encounters an error, write it to `node.outputs['__scriptError']` and set `node.statusIcon = 'error'` to visually alert the user. On success, you might set `node.statusIcon = 'check'`.
2. **Output Storage & Display**: 
   - **Outputs**: Save the final output by directly assigning to `node.outputs`.
   - **Quick View**: Assign the result to `node.annotation` so the user can see the result directly on the canvas below the node.
   - **Rich Content**: You can dynamically set `node.contentType = 'markdown'` and put the markdown string into `node.title`. For charts, set `node.contentType = 'chart'` and assign the chart dictionary object to `node.contentPayload`. If asked to display a chart, ALWAYS generate the code to format `node.contentPayload` according to the chart specification.
   ```javascript
   node.outputs['response'] = data.result;
   node.annotation = data.result;
   node.statusIcon = 'check';
   ```
3. **Escaping**: Be mindful that MindLogic replaces `{{...}}` as literal strings. If the user input contains quotes or newlines, it might break the JS syntax. Use template strings `` `{{key}}` `` or carefully escape inputs where necessary.

## Advanced References (Important for AI Agents)
If you are asked to generate complex data visualizations (Charts) or need more advanced examples of Entity Scripts, **DO NOT guess the formats**. Instead, use your `view_file` tool to read the latest official documentation directly from the workspace before writing the code:
- **For Chart Data Formats**: Read `web/src/content/manual/en/11-charts-and-data.md`
- **For more Node Script Examples**: Read `web/src/content/manual/en/08-entity-scripts.md`