Agentify Components

一个框架，用于向React组件添加语义元数据，使其对AI系统和自动化工具“感知”。

概述

Agentify Components 解决了使UI组件对AI代理可理解的问题。当AI助手与Web应用程序交互时，它们通常缺乏关于组件的功能、如何与其交互以及处理什么数据的上下文信息。

该框架通过装饰器为您的组件添加了一层语义：

1. 注册组件元数据 - 定义组件的功能及其行为。
2. 提供标准化模式 - 为不同类型的组件创建一致的元数据结构。
3. 生成配置文件 - 在构建时创建MCP服务器。

🚀 注意： 该框架专注于组件元数据而不是行为修改。它使您的组件对AI系统“自我描述”，而不改变其功能。

安装

npm install @anvosio/agentify-components

发展路线图

目前，这仅生成一个MCP服务器。接下来最重要的里程碑之一是能够构建本地工具，这些工具可以与您已经构建的一系列其他工具一起传递给大模型。

这使得您可以同时拥有前端工具和后端工具。

未完成！最后更新于2025年3月14日

核心概念

组件类型

Agentify 目前支持三种主要的组件类型：（以下已被移除，现在仅限于API和导航行为）

• 搜索栏 - 用于具有导航或API行为的搜索输入
• 表单 - 用于具有字段级元数据的数据收集
• 按钮 - 用于具有导航、API或UI交互行为的操作

模型上下文协议 (MCP)

模型上下文协议 (MCP) 是由Anthropic开发的一个开放标准，用于连接AI模型与外部数据源和工具。它采用客户端-服务器架构，允许AI助手从各种系统（如Google Drive、Slack或数据库）访问实时数据，增强其响应的时效性。MCP通过提供一种通用协议简化集成，实现安全且标准化的连接，取代自定义API连接器，使用可重用的MCP服务器。

框架架构

该框架由四个主要部分组成：

1. 装饰器 (@AgentConfig) - 将元数据附加到组件上，包括通用字段和特定于协议的配置。
2. 转换器 - 将通用元数据适应成特定于协议的格式（例如，当前为MCP协议，但未来将扩展到其他协议）。
3. 生成器 - 基于转换后的配置生成服务器文件内容，针对每个协议进行定制。
4. CLI 工具 - 处理组件，根据目标协议应用适当的转换器和生成器，并输出服务器文件。

这种架构确保了灵活性——开发者可以一次定义组件，并通过添加新的转换器和生成器来支持多种协议。

使用方法

具体类型组件的Agentification示例（需要更新）

对搜索栏进行Agentification

import React from 'react';
import { AgentConfig } from '@anvos/agentify-components';

// 使用装饰器添加语义元数据
@AgentConfig({
  type: 'search',
  behavior: {
    type: 'api',
    endpoint: '/api/products/search',
    method: 'GET',
    queryParam: 'term'
  },
  description: '在目录中搜索产品',
 
})
export class ProductSearch extends React.Component {
  render() {
    return (
      <input 
        type="search" 
        onChange={(e) => this.props.onSearch?.(e.target.value)}
        placeholder="搜索..." 
      />
    );
  }
}

对表单进行Agentification

import React from 'react';
import { AgentConfig } from '@anvos/agentify-components';

// 使用装饰器添加语义元数据
@AgentConfig({
  type: 'form',
  behavior: {
    type: 'api',
    endpoint: '/api/auth/login',
    method:  'POST'
  },
  fields: [
    { name: 'username', type: 'text', required: true },
    { name: 'password', type: 'password', required: true }
  ],
  purpose: 'user-authentication',
  description: '用户登录表单以访问账户'
})
export class LoginForm extends React.Component {
  render() {
    return (
      <form onSubmit={this.props.onSubmit}>
        {/* 表单字段 */}
        <input type="text" name="username" />
        <input type="password" name="password" />
        <button type="submit">登录</button>
      </form>
    );
  }
}

对按钮进行Agentification

import React from 'react';
import { AgentConfig } from '@anvos/agentify-components';

// 使用装饰器添加语义元数据
@AgentConfig({
  type: 'button',
  behavior: {
    type: 'navigation',
    href: '/checkout'
  },
  label: '前往结算',
  description: '导航至结算页面以完成购买'
})
export class CheckoutButton extends React.Component {
  render() {
    return (
      <button onClick={this.props.onClick}>
        {this.props.children}
      </button>
    );
  }
}

通用组件的Agentification示例

@anvos/agentify-components 包提供了几种方式为您的React组件添加代理配置：

示例1：使用HOC的函数组件

对于函数组件，您可以使用withAgentConfig高阶组件来包装带有代理配置的组件：

import { withAgentConfig } from '@anvos/agentify-components';

export const LoginButton = withAgentConfig({
  type: 'button',
  behavior: { type: 'api', endpoint: '/api/login', method: 'POST' },
  label: '登录按钮',
  selector: '#login-btn',
  description: '通过API提交登录表单'
})(() => {
  return <button id="login-btn">登录</button>;
});

示例2：直接属性赋值的函数组件

或者，您可以创建一个函数组件并直接分配agentConfig属性：

import { AgentComponent } from '@anvos/agentify-components';

export const LoginButton2: AgentComponent = () => {
  return <button id="login-btn">登录</button>;
};

LoginButton2.agentConfig = {
  type: 'button',
  behavior: { type: 'api', endpoint: '/api/login', method: 'POST' },
  label: '登录按钮',
  description: '通过API提交登录表单'
};

示例3：使用装饰器的类组件

对于类组件，您可以直接使用@AgentConfig装饰器：

import { AgentConfig } from '@anvos/agentify-components';

@AgentConfig({
  type: 'button',
  behavior: { type: 'navigation', href: '/home' },
  label: '主页按钮',
  description: '导航至主页'
})
class HomeButton extends React.Component {
  render() {
    return <button id="home-btn">主页</button>;
  }
}

export { HomeButton };

各种方法何时使用

• HOC模式（示例1）：最适合需要为现有函数组件应用代理配置或希望在组件和其配置之间保持分离的情况。
• 直接属性赋值（示例2）：对于函数组件来说是最简单的做法，适用于组件定义和配置在同一文件中的情况。
• 装饰器模式（示例3）：对于类组件来说是最优雅的选择，提供了干净的语法和TypeScript装饰器。

MCP工具模式类型映射

在生成MCP服务器时，使用以下JSON Schema到Zod类型的映射：

JSON Schema 类型	Zod Schema 类型
string	z.string()
number	z.number()
boolean	z.boolean()
array	z.array(z.string())
object	z.object({})
integer	z.number()
float	z.number()
date	z.date()
datetime	z.date()
time	z.date()

这些映射在将组件元数据转换为MCP服务器工具的适当格式时使用。

生成MCP服务器

在项目根目录下添加generate.ts文件，并添加以下代码：

import { generateMCPServer } from '@anvos/agentify-components';
import * as components from './components/ButtonExample';

const componentList = Object.values(components);

console.log(componentList);
generateMCPServer(componentList, './mcpServer');

现在，在您的package.json中添加以下脚本：

"scripts": {
  "build:mcp": "ts-node ./generate.ts",
  "deploy:mcp": "echo '仍在开发中'"
}

这将扫描您的代码库以查找已代理化的组件，并在/mcpServer目录下生成一个MCP服务器。

要部署您的MCP服务器：

npm run deploy:mcp

这将把您的MCP服务器部署到Anvos社区的MCP服务器上GitHub，用户可以轻松访问。您的配置可以通过一个唯一的URL共享给支持MCP协议的AI系统和工具。

我还打算更进一步，只返回客户端所需的工具，而不是整个MCP服务器，因为这会导致MCP客户端被不必要的工具填充过多。

组件配置选项

参见设置指南了解每种组件类型的详细配置选项。

文档

• 设置指南 - 详细的安装说明和配置选项
• 产品需求文档 - 完整的项目规范和路线图

贡献

欢迎贡献！请随时提交Pull Request。

许可证

该项目采用MIT许可证 - 详情请参阅LICENSE文件。