Build a TypingMind Plugin

• JavaScript: run a JavaScript code in a secure sandbox environment, then return the result to the AI model or render the result to the user chat conversation.

• HTTP Actions: send an HTTP request and get the response.

• MCP: use a Model Context Protocol server as a plugin.

• Plugin Name: to be shown to the user.

• Overview: introduction about the plugin and how to use it. Markdown is supported.

json
[
  {
    "name": "searchEngineID",
    "label": "Search Engine ID"
  },
  {
    "name": "searchEngineAPIKey",
    "label": "Search Engine API Key",
    "type": "password"
  },
	{
	  "name": "quality",
	  "label": "Quality",
	  "description": "Optional, default: \"standard\"",
	  "type": "enum",
	  "values": [
	    "standard",
	    "hd"
	  ]
	}
]

• name: This is the identifier the plugin will use to retrieve the user's input.

• label: This is the label displayed to the user to help identify what information should be entered. Try to make this intuitive and relevant to the data you're asking for.

• required (optional): Must be a boolean value of true or false, indicating whether the field is required or not. Default is false.

• description (optional): Displayed as a small text under the label. Use this to clarify other information related to the field.

• type (optional): This is used to specify the type of data expected from the users. For instance, input type could be password, email, number, or enum. By default, if not specified, the type is assumed to be text.

• placeholder (optional): The placeholder text to be shown in the input field.

• values (optional): Only takes effect when type is enum. This must be an array of strings of allowed values for the field.

• defaultValue (optional): The default value if not provided by the user. To use these settings within your plugin, you can access them from the user's input and either store them for later use or use them immediately as needed.

• Static text prompt: a fixed text prompt (with variables from user settings).

• Read context from an HTTP endpoint: allows you to inject live data to the context of the plugin.

• No authentication: the user doesn't need to authenticate to use the plugin.

• API Key: requires the user to add an API key to use the plugin.

• OAuth 2.0: requires the user to log in to an OAuth provider to use the plugin.

json
[
  {
    "name": "firecrawl_api_key",
    "label": "Firecrawl API Key",
    "description": "This plugin require an API key from www.firecrawl.dev, go to your Firecrawl admin panel to get an API key.",
    "required": true
  }
]

• A Google Calendar plugin that allows the AI to read events from the user's Google calendar.

• A Slack message plugin that allows the AI to send a message to the user's Slack channel.

• Creating a plugin with OAuth requires the plugin developer to set up Authorization URL, Token URL, Scopes, Prompt, and Access Type. These parameters are different depending on which OAuth provider is used.

• When installing a plugin with OAuth, the plugin will require setting up OAuth Client ID and OAuth Client Secret. The admin user who installs the plugin will need to set this up with their own OAuth app.

• When the plugin is being used by the end users, they will need to authorize first. The authorization process is handled by TypingMind automatically.

• Plugin developers can use the {OAUTH_PLUGIN_ACCESS_TOKEN} variable in their plugin source code as a placeholder for the user's access token. If the user has not authorized or the access token has expired, the variable will hold an empty value.

• Access Type: Setting access_type=offline to explicitly request a refresh token.

• Prompt: Many providers (like Google) only issue a refresh token the first time a user grants consent. Using prompt=consent ensures a refresh token is issued even if the user has previously authorized the app.

json
"oauthConfig": {
	  "scopes": "https://www.googleapis.com/auth/calendar.readonly",
	  "tokenURL": "https://oauth2.googleapis.com/token",
	  "contentType": "json",
	  "authorizationURL": "https://accounts.google.com/o/oauth2/v2/auth",
	  "prompt": "consent",
	  "accessType": "offline"
}

• Centralized OAuth Setup: Admins configure OAuth credentials just once for multiple plugins.

• Simplified User Experience: Users authenticate once and gain seamless access across all plugins sharing the OAuth connection.

1. Create a Shared Connection:
• Navigate to the Plugins Manager
• Select the "Shared OAuth Connections" tab
• Click "Add New Connection" to create a new OAuth connection

2. Configure OAuth Credentials:
• Enter necessary details such as Authorization URL, Token URL, Client ID, Client Secret, Scopes, Prompt, and Access Type

3. Apply Shared OAuth to Plugins:
• Edit the desired plugin
• Under the "Authentication" section, select OAuth 2.0
• Choose your "OAuth Configuration Source" from the dropdown menu, selecting your newly created shared OAuth connection
• Plugin credentials will automatically apply from the shared connection—no further setup required

• Built-in plugins provided by the system come with predefined OAuth settings and cannot be directly modified.

• To apply a shared OAuth connection:
• Duplicate the built-in plugin
• Edit your duplicated plugin to select the shared OAuth connection

• JavaScript: run a JavaScript code in a secure sandbox environment, then return the result to the AI model or render the result to the user chat conversation.

• HTTP Actions: send an HTTP request and get the response.

• MCP: use a Model Context Protocol server as a plugin.

• Make sure it's in the correct JSON format: Follow the instructions in OpenAI document to understand how to write one. You can see the spec of existing plugins like Simple Calculator, JavaScript Interpreter, or the Generate Random Number example plugin below for reference.

• Unique Function Name: Note that the name field of the spec must be unique across all plugins you currently have. This is because OpenAI API will use this name to call the function, having multiple functions with the same name will confuse the AI.

• Use meaningful names & descriptions: It's important to provide a meaningful function name, function description, parameter name, parameter description, etc. The AI will use these names and descriptions to understand and decide when to use your function. Providing a meaningful and accurate name will help the AI use your function/plugin better.

json
{
  "name": "generate_random_number_in_range",
  "description": "Generate a random integer number between number 'a' and number 'b'.",
  "parameters": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number",
        "description": "The number a (the smaller number)"
      },
      "b": {
        "type": "number",
        "description": "The number b (the larger number)"
      }
    },
    "required": [
      "a",
      "b"
    ]
  }
}

json
[
  {
    "name": "searchEngineID",
    "label": "Search Engine ID"
  },
  {
    "name": "searchEngineAPIKey",
    "label": "Search Engine API Key",
    "type": "password"
  }
]

javascript
function search_images_via_google(params, userSettings) {
  const searchEngineID = userSettings.searchEngineID;
  const searchEngineAPIKey = userSettings.searchEngineAPIKey;

  // Now you can use these values in your code
}

javascript
function generate_random_number_in_range({a, b}) {
    var min = Math.ceil(a);
    var max = Math.floor(b);
    return Math.floor(Math.random() * (max - min + 1) + min);
}

• HTTP Method

• Endpoint URL

• Headers (optional)

• Body (optional)

• Post-Processing (optional)

• the variable {openaikey} is used in the request headers

• the variables {prompt}, {resolution}, {quality} is used the request body.

• JMESPath Transform (docs): Useful to filter a big JSON response to a smaller JSON.

• Handlebars.js Template (docs): Useful to rewrite the JSON response into a different format like Markdown or HTML.

• Give plugin output to the AI

• Render plugin output as markdown

• Render plugin output as interactive HTML

• Render plugin output as special cards format

• Render interactive chart

• Show preview of generated code (HTML/JS/CSS)

1. Image Card

json
[
  { type: "image", image: { url: "https://link-to-image.png" } }
]

• Export the plugin to a JSON file.

• Use the TypingMind’s default share feature to create a secret link.

• Upload your plugin source to a GitHub repository and share the GitHub link.

• When using JavaScript implementation, your plugins are run on a sandboxed browser environment. Some JavaScript features may not be available.

• In TypingMind personal version, your plugins can send HTTP requests to external services, however, the destination server must be configured to allow CORS requests from Typing Mind. If CORS requests are not allowed, you will need an intermediate server to process the requests. Some API servers allow CORS requests from everywhere – like Perplexity API, or Open AI – so the intermediate server is not needed in these cases.

• Bug report

• Ideas & feature suggestions

• Customer support: support@typingmind.com