@lementor/angie-sdk (英语)

依据 MCP 磁共振 版本: 1.20.1

一个SDK,用于扩展安吉AI助理能力.

这个SDK使您能够创建自定义的MCP服务器,安吉可以发现并使用它来运行您的插件特性.

目录

• 背景情况
• 如何运作
• 支持的 MCP 特性
• 安装
• 快速启动
• 同步注册
• 触发 Angie 有提示
• MCP 服务器示例
• 添加指令到 MCP 服务器
• 注册工具
• 工具说明
• 处理工具呼叫
• 最佳做法
• 远程 SSE 和 HTTP 可流 MCP 服务器
• 处理错误
• 更改日志
• 演示插件
• 在任何网页上嵌入安吉
• 调试( T)
• 财务问题

背景情况

安琪是一个WordPress AI助手,可以在WordPress网站上执行几乎任何任务.

安吉完全可扩展,因此插件开发者可以轻松地整合自己的功能,使安吉能够使用和控制.

安琪基于基于MCP的架构而构建,使您能够创建自定义的MCP服务器,暴露出您插件让安琪访问的能力.

要了解MCP:

• MCP 规格
• MCP 类型脚本 SDK
• MCP 文档

SDK专为解决这些问题而设计的:

1. 在浏览器中运行 MCP SDK允许您在浏览器中作为JavaScript模块运行一个MCP服务器,因此不需要创建基于PHP的MCP服务器或创建外部SSE或基于HTTPStreamable的MCP服务器.

   所有逻辑运行客户端,同时您可以使用WP REST甚至adminAjax与您的插件后端通信.

2. 在没有外部服务器的安吉注册 MCP 您可以使用 SDK 直接与 Angie 注册您的 MCP, 即使您没有外部的 MCP 网关 。 安琪通过SDK发现了你的服务器.

3. 在当前屏幕上与 MCP 通信 SDK使Angie能够与您插件的MCP直接在当前页面上通信,因此Angie将能够 见 财务报告和审定财务报表 动作 当前用户屏幕上.

如何运作

Angie SDK允许您使用正式的TypeScript MCP SDK来写入您的MCP服务器. 然后用Angie SDK可以注册,让Angie像其他MCP主机一样运行你的MCP服务器.

SDK包括三个主要能力:

• 导入和使用当前支持的官方 MCP SDK
• 注册您的 MCP 服务器
• 在浏览器中运行您的 MCP 服务器

┌──────────────────────────────┐
│       Angie SDK Flow         │
├──────────────────────────────┤
│                              │
│  Your WordPress Plugin       │
│            │                 │
│            │ enqueue script  │
│            ▼                 │
│  Your MCP Server (JS)        │
│            │                 │
│            │ register server │
│            ▼                 │
│  Angie SDK                   │
│            │                 │
│            ◄─► Browser       │
│            │   Transport     │
│            ▼                 │
│  Angie (iframe)              │
│                              │
└──────────────────────────────┘

支持的 MCP 特性

获得支持:

• 工具、资源、通知、抽样(通过后端)

尚未支持 :

• 提示( 仅以检查器显示)、 OAuth 2. 0 外部认证、 以语录

不可用 :

• 根,STIO运输(浏览器环境限制)

📖 联合国

• MCP SDK 支持的特性
• 工具说明 - 以资源依赖性、模式偏好和更多工具作注释

安装

npm install @elementor/angie-sdk

快速启动

1. 创建您的 MCP 服务器

创建 TypeScript 或 Javascript 文件( 如 , 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( { appId: 'my-app' } );

await sdk.waitForReady();

sdk.registerServer({
  name: 'my-seo-server',
  version: '1.0.0',
  description: 'SEO tools for Angie',
  server,
});

通过一个 appId 用你的应用程序的设置. 它识别聊天属于哪个应用程序. SDK将其添加到Angie iframe URL中,Angie随每个聊天请求一起发送. 没有 appId安琪会用它 默认设置 (一般助理,没有特定应用的提示或代理).

同步注册

这个 registerServer() 方法是一个同步并返回一个承诺. 在大多数情况下,你不需要 await 因为登记发生在背景.

使用 await sdk.registerServer(...) 当:

• 您需要确保注册完成前
• 要明确抓好并处理注册错误

触发 Angie 有提示

SDK可以以快取,上下文附件来触发Angie,或者两者兼而有之.

interface ContextAttachment {
  label: string;
  content: string;
}

interface PromptSuggestion {
  label: string;
  value: string;
  autoSend?: boolean;
  color?: string;
  isNew?: boolean;
  requiresPrompt?: string;
}

interface AngieTriggerRequest {
  prompt?: string;
  context?: { source?: string } & Record<string, unknown>;
  contextAttachment?: ContextAttachment;
  suggestions?: { items: PromptSuggestion[] };
  options?: {
    timeout?: number;
    newChat?: boolean;
    autoSend?: boolean;
  };
}

import { AngieMcpSdk, type ContextAttachment } from '@elementor/angie-sdk';

// Register your MCP server and trigger Angie
const server = createSeoMcpServer();
const sdk = new AngieMcpSdk( { appId: 'my-app' } );

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' },
  contextAttachment: {
    label: 'Current SEO report',
    content: 'The page is missing a meta description.',
  },
  suggestions: {
    items: [
      { label: 'Add meta description', value: 'Add a meta description to this page', autoSend: true },
      { label: 'Improve title', value: 'Suggest a better SEO title', isNew: true },
    ],
  },
  options: {
    timeout: 30000, // Optional: 30 seconds timeout (default: 30000)
    newChat: true,
  },
  metadata: { plan: 'pro', area: 'seo' },
});

// A prompt without context
await sdk.triggerAngie({
  prompt: 'Help me create a contact page'
});

// Attach context without pre-filling a prompt
const contextAttachment: ContextAttachment = {
  label: 'Selected error',
  content: 'Checkout failed with error code PAYMENT_DECLINED.',
};

await sdk.triggerAngie({ contextAttachment });

请求字段 :

• prompt: 可选的即时文本.
• contextAttachment: 附加在下个提交的用户信息上的可选标签内容. 它可以使用没有 prompt 而不作为电文的一部分提供.
• suggestions: 向用户显示的可选快速建议列表. 每个项目有一个 label (已删除的文本)和 value (选中时立即发送); 可选 autoSend 立即提出, color 设置芯片颜色, isNew 显示一个"新"徽章,和 requiresPrompt 打开给定提示背后的建议.
• context: 可选集成元数据. SDK 添加电流 pageUrl 财务报告和审定财务报表 pageTitle· ;
• options.timeout: 在毫秒内等待 Angie 回复需要多久( 默认 : 30000) (中文(简体) ).
• options.newChat: 当 true中,清除当前对话并打开新的聊天.
• options.autoSend: 当 true,提交 prompt 而不是仅仅预装作曲家.
• metadata: 可选的平面元数据存储在新聊天上. {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}我还是要继续, {} 来清理.

metadata 规则 (服务器执行这些限制并删除无效条目):

元数据未经核实:不使用它进行许可或计费,也不将个人数据(电子邮件,姓名)或秘密放入其中.

宽参数法

// Trigger via URL hash - perfect for deep linking
window.location.hash = 'angie-prompt=' + encodeURIComponent('Help me create a contact page');

// Open a new chat via hash parameter
window.location.hash = 'angie-prompt=' + encodeURIComponent('Fix this error') + '&angie-new-chat=true';

// Example URL: https://yoursite.com/wp-admin/edit.php#angie-prompt=Help%20me%20optimize%20SEO&angie-new-chat=true

散列参数:

• angie-prompt: 输入字段中要插入的提示文本
• angie-new-chat: 当设定为 true,清除当前对话,并打开与输入中预填入的提示的新聊天

两者 loadSidebar() 财务报告和审定财务报表 loadSidebarV2() 注意散列,在页面载荷和以后的散列变化。 你不需要自己的散列密码.

说明: 总是打电话 await sdk.waitForReady() 在触发安琪之前.

MCP 服务器示例

典型的项目结构:

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
└── ...

• 前一頁: 需要时为您的工具执行 REST API 端点.
• 联合来文/TS: 使用 SDK 注册工具和处理请求.

添加指令到 MCP 服务器

指令是描述何时使用您 MCP 服务器及其能力的准则 。 它们帮助安琪理解你的服务器能做什么和不能做什么,确保适当的工具选择和适当的用户期望.

为什么要添加指令 ?

• 引导 Angie 当您的服务器是合适的任务选择时
• 澄清现有哪些能力
• 在无法完成的事情上设置明确的界限
• 提高工具选择的准确性

如何添加指令

服务器初始化时在第二个参数中提供指令 :

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`
  }
);

最佳做法

1. 说明能力:解释每种能力的作用以及何时使用,而不仅仅是特征名称
2. 定义使用大小写: 帮助安琪理解当您的服务器是合适的任务选择时
3. 设置明确的边界: 明确说明您的服务器无法防止不适当的工具呼叫
4. 不断更新: 添加或删除工具时刷新指令
5. 使用面向动作的语言: 专注于用户可以用您的服务器完成什么

注册工具

每个工具必须登记在:

• 名称: 唯一字符串标识符
• 说明:工具做什么以及何时使用
• 输入计划: JSON 描述所需/可选参数的计划

示例

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'],
      },
    },
  ],
}));

工具说明

安吉用安吉特有的元数据扩展了MCP工具说明. 直接从 @elementor/angie-sdk数字 :

import {
  ANGIE_REQUIRED_RESOURCES,
  ANGIE_MODEL_PREFERENCES,
  ANGIE_EXTENDED_TIMEOUT,
  MCP_READONLY,
  ToolAnnotations,
} from '@elementor/angie-sdk';

server.tool(
  'analyze-page-layout',
  'Analyzes the current page layout and returns suggestions',
  { /* input schema */ },
  {
    [MCP_READONLY]: true,
    [ANGIE_EXTENDED_TIMEOUT]: { timeoutMs: 30000 },
    [ANGIE_REQUIRED_RESOURCES]: [
      { uri: 'elementor://page/layout', whenToUse: 'Always — needed to read the page structure' }
    ],
    [ANGIE_MODEL_PREFERENCES]: {
      hints: [{ name: 'claude-sonnet' }]
    }
  } as ToolAnnotations,
  async (args) => { /* handler */ }
);

见 工具说明 供充分参考.

处理工具呼叫

执行处理器 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}`);
  }
});

最佳做法

• 工具命名:使用清晰,注重结果的名称(如"analysis-page-seo").
• 说明:清晰地描述工具的用途,何时使用,以及返回的内容.
• 输入图:为每个工具定义精确的输入方案,偏好使用Zod.
• 处理错误: 返回自然语言中方便用户的错误和调试的日志细节.
• 警卫: 在您的后端使用非 CEST API 调用和权限检查 .
• 版本:Angie SDK导出当前所支持的MCP SDK,更倾向于使用集成的MCP SDK来确保所支持的MCP版本特性.

警卫

安全责任:当你创建了与你的WordPress后端交互的MCP工具时,你开始负责这些操作的安全. 安吉充当用户行动的渠道,所以你有责任执行适当的安全措施.

必要的安全措施

1. 权限检查: 总是在您的后端端验证用户权限
2. 输入验证: 对所有输入数据进行卫生和验证
3. 能力检查: 对特定操作使用 WordPress 能力检查

示例安全端点

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,
          ),
        ),
    ]);
});

远程 SSE 和 HTTP 可流 MCP 服务器

对于远程服务器,让你的Angie用户通过Angie MCP Gateway设置添加.

支持的远程服务器类型

• SSE( 仆人事件):用于实时流出响应
• HTTP 可流性:用于基于 HTTP 的流线通信

配置

远程MCP服务器可以通过安吉的设置接口来配置,允许用户与外部的MCP服务相接而无需更改代码.

处理错误

• 在处理器中丢出错误以返回对客户端的错误回复.
• 使用自定义错误信息处理用户显示错误 .
• 内部记录出错 .

示例

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');
  }
});

更改日志

• v1.0.0 (韩语)页:1

演示插件

更多实例请参见示例文件夹中的演示插件和MCP服务器

在任何网页上嵌入安吉

将 Angie 用户界面嵌入您自己的网站( 侧边栏或浮动聊天) , 使用 AngieMcpSdk.loadSidebarV2()。见专用指南: 装入SidebarV2。自定义嵌入式聊天UI(标题、建议、特性切换),参见 部件配置 编辑 部件配置演示。 。 。 .

如果有问题或需要帮助,请打开一个问题或联系元素团队!

调试( T)

• 使用浏览器控制台日志来验证服务器注册和工具呼叫.
• 在接通MCP服务器前直接测试REST端点(例如与Postman).
• 请检查Angie的UI 以发现和引用工具.

常见调试步骤

1. 检查浏览器显示注册错误
2. 验证注册和处理器之间的工具名称匹配
3. 独立测试 REST API 端点
4. 确保适当的非曲直和权限设置

增强调试的 Dev 模式

安吉包含一个Dev Mode功能,在聊天界面中直接显示工具执行进度和细节,从而更容易调试你的MCP服务器集成,并理解安吉如何与工具互动.

要启用 Dev 模式 :

1. 在 WordPress 中打开安吉
2. 点击用户配置图标
3. 导航到工具
4. 切换“ Dev 模式” 打开

Dev Mode 显示的内容 : 启用后, Angie 会显示在聊天中 :

• 每个用户请求的工具执行历史
• 工具调用状态( 待处理、 正在进行、 完成、 失败)
• 工具输入和输出

许可证

麻省理工学院