@elementor/angie-sdk
Advanced tools
Based on MCP version: 1.20.1
An SDK for extending Angie AI Assistant capabilities.
This SDK enables you to create custom MCP servers that Angie can discover and use to run your plugin features.
Angie is a WordPress AI Assistant that can perform almost any task on a WordPress website.
Angie is fully extensible, so plugin developers can easily integrate their own features, allowing Angie to use and control them.
Angie is built on an MCP-based architecture, enabling you to create custom MCP servers that expose your plugin's capabilities for Angie to access.
To learn about MCP:
The SDK was designed specifically to address these issues:
Run MCP in the Browser The SDK allows you to run an MCP server as a JavaScript module in the browser, so there is no need for creating a PHP-based MCP server or creating an external SSE or HTTPStreamable-based MCP Server.
All logic runs client-side while you can use WP REST or even adminAjax to communicate with your plugin backend.
Register MCP with Angie Without an External Server You can register your MCP directly with Angie using the SDK, even if you don't have an external MCP Gateway. Angie discovers your server through the SDK.
Communicate with MCP on the Current Screen The SDK enables Angie to communicate with your plugin's MCP directly on the current page, so Angie will be able to see and act on the current user's screen.
Angie SDK allows you to use the official TypeScript MCP SDK to write your MCP Server. Then with Angie SDK you can register it and let Angie run your MCP server like other MCP Hosts.
The SDK covers three main abilities:
┌──────────────────────────────┐
│ Angie SDK Flow │
├──────────────────────────────┤
│ │
│ Your WordPress Plugin │
│ │ │
│ │ enqueue script │
│ ▼ │
│ Your MCP Server (JS) │
│ │ │
│ │ register server │
│ ▼ │
│ Angie SDK │
│ │ │
│ ◄─► Browser │
│ │ Transport │
│ ▼ │
│ Angie (iframe) │
│ │
└──────────────────────────────┘
Supported:
Not Supported Yet:
Not Available:
📖 For detailed feature documentation and best practices, see MCP SDK Supported Features
npm install @elementor/angie-sdk
Create a TypeScript or a Javascript file (e.g., demo-mcp-server.ts):
import {
AngieMcpSdk,
CallToolRequest,
CallToolRequestSchema,
ListToolsRequestSchema,
McpServer,
} from '@elementor/angie-sdk';
// Define the MCP server
function createSeoMcpServer() {
const server = new McpServer(
{ name: 'my-seo-server', title: 'SEO', version: '1.0.0' },
{
capabilities: { tools: {} },
instructions: `Guidelines for when to use this server and its capabilities.`
}
);
// Add your tools, resources, etc.
server.tool( ... );
return server;
}
// Register the server with Angie
const server = createSeoMcpServer();
const sdk = new AngieMcpSdk();
await sdk.waitForReady();
sdk.registerServer({
name: 'my-seo-server',
version: '1.0.0',
description: 'SEO tools for Angie',
server,
});
The registerServer() method is asynchronous and returns a Promise.
In most cases, you don't need to await it since registration happens in the background.
Use await sdk.registerServer(...) when:
The SDK can also trigger Angie with custom prompts - useful for help buttons or deep linking.
import { AngieMcpSdk } from '@elementor/angie-sdk';
// Register your MCP server and trigger Angie
const server = createSeoMcpServer();
const sdk = new AngieMcpSdk();
await sdk.waitForReady();
sdk.registerServer({
name: 'my-seo-server',
version: '1.0.0',
description: 'SEO tools for Angie',
server,
});
// Trigger Angie with a prompt
await sdk.triggerAngie({
prompt: 'Help me optimize this page for SEO',
context: { pageType: 'product', source: 'my-plugin' },
options: {
timeout: 30000, // Optional: 30 seconds timeout (default: 30000)
}
});
// Or simplified version
await sdk.triggerAngie({
prompt: 'Help me create a contact page'
});
Options:
timeout: How long to wait for Angie response (milliseconds)priority: Request priority levelcontext: Additional data to help Angie understand the request// Trigger via URL hash - perfect for deep linking
window.location.hash = 'angie-prompt=' + encodeURIComponent('Help me create a contact page');
// Or visit URLs like: https://yoursite.com/wp-admin/edit.php#angie-prompt=Help%20me%20optimize%20SEO
Note: Always call await sdk.waitForReady() before triggering Angie.
A typical project structure:
your-plugin/
├── plugin.php # Main WordPress plugin file
├── dist/
│ └── demo-mcp-server.js # Bundled MCP server JS
├── src/
│ └── demo-mcp-server.ts # MCP server source
└── ...
Instructions are guidelines that describe when to use your MCP server and what its capabilities are. They help Angie understand what your server can and cannot do, ensuring appropriate tool selection and proper user expectations.
Provide instructions in the second parameter during server initialization:
const server = new McpServer(
{ name: 'content-writer', title: 'Content Writer', version: '1.0.0' },
{
instructions: `Guidelines for using the Text Content Management server.
### Capabilities:
- **Generate new content**: Creates blog posts, page content, headlines, product descriptions
- **Edit existing content**: Refines or adjusts text based on specific instructions
- **Content variations**: Creates multiple versions for A/B testing or different audiences
### Limitations:
- **SEO optimization**: Cannot analyze or optimize for specific keywords or search rankings
- **Fact checking**: Cannot verify accuracy against real-world data
- **Plagiarism checking**: Cannot verify content originality`
}
);
Each tool must be registered with:
Example:
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'analyze-page-seo',
description: 'Analyzes the SEO of a page.',
inputSchema: {
type: 'object',
properties: { url: { type: 'string', description: 'Page URL' } },
required: ['url'],
},
},
],
}));
Implement a handler for CallToolRequestSchema:
server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => {
const { name, arguments: args } = request.params;
switch (name) {
case 'analyze-page-seo':
// Call your backend or perform logic
const { root, nonce } = window.wpApiSettings;
const response = await fetch(`${root}my-plugin/v1/analyze-seo`, {
method: 'POST',
headers: {
'X-WP-Nonce': nonce,
'Content-Type': 'application/json',
},
credentials: 'same-origin',
body: JSON.stringify(args),
});
if (!response.ok) {
throw new Error(`API request failed: ${response.statusText}`);
}
const result = await response.json();
return {
content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
};
// Add more cases as needed
default:
throw new Error(`Unknown tool: ${name}`);
}
});
⚠️ Security Responsibility: When you create MCP tools that interact with your WordPress backend, you become responsible for the security of those operations. Angie acts as a channel for user actions, so it's your responsibility to implement proper security measures.
add_action('rest_api_init', function () {
register_rest_route('my-plugin/v1', '/analyze-seo', [
'methods' => 'POST',
'callback' => 'my_analyze_seo_callback',
'permission_callback' => function () {
return current_user_can('edit_posts');
},
'args' => array(
'url' => array(
'validate_callback' => function($param, $request, $key) {
return filter_var($param, FILTER_VALIDATE_URL);
},
'required' => true,
),
),
]);
});
For remote servers, let your Angie users add them via Angie MCP Gateway settings.
Remote MCP servers can be configured through Angie's settings interface, allowing users to connect to external MCP services without requiring code changes.
Example:
server.setRequestHandler(CallToolRequestSchema, async (req) => {
try {
// Your tool implementation
const result = await performToolAction(req.params);
return {
content: [{ type: 'text', text: result }],
};
} catch (err) {
console.error('Tool error:', err);
throw new Error('User-friendly error message');
}
});
For more examples, see the demo plugin and MCP server in the example folder
If you have questions or need help, open an issue or contact the Elementor team!
Angie includes a Dev Mode feature that displays tool execution progress and details directly in the chat interface, making it easier to debug your MCP server integrations and understand how Angie interacts with your tools.
To enable Dev Mode:
What Dev Mode shows: When enabled, Angie will display in the chat:
MIT
FAQs
TypeScript SDK for Angie AI assistant
We found that @elementor/angie-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub postponed a new billing model for self-hosted Actions after developer pushback, but moved forward with hosted runner price cuts on January 1.
Research
Destructive malware is rising across open source registries, using delays and kill switches to wipe code, break builds, and disrupt CI/CD.
Security News
Socket CTO Ahmad Nassri shares practical AI coding techniques, tools, and team workflows, plus what still feels noisy and why shipping remains human-led.