{"_id":"@anvosio/agentify-components","name":"@anvosio/agentify-components","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@anvosio/agentify-components","version":"0.1.0","description":"A framework for agentifying UI components with semantic metadata for AI agents","main":"src/index.ts","repository":{"type":"git","url":"git+https://github.com/anvosio/agentify-components.git"},"scripts":{"start":"node examples/simple-app/index.js","test":"echo 'Tests coming soon!'","build":"echo 'Build script coming soon!'","generate-mcp":"node examples/TestExample/generate.ts"},"dependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0","reflect-metadata":"^0.2.2","uuid":"^11.1.0","zod":"^3.24.2"},"peerDependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0","react-dom":"^16.8.0 || ^17.0.0 || ^18.0.0"},"keywords":["react","components","agents","ai","hoc","metadata","typescript","mcp","server"],"author":{"name":"Anvos"},"license":"MIT","devDependencies":{"@types/react":"^19.0.10","ts-node":"^10.9.2","typescript":"^5.8.2"},"publishConfig":{"access":"public"},"bugs":{"url":"https://github.com/anvosio/agentify-components/issues"},"homepage":"https://github.com/anvosio/agentify-components#readme","_id":"@anvosio/agentify-components@0.1.0","gitHead":"c3e37a2a15bc6bd9008ea07bff9990665e08ee3c","_nodeVersion":"22.11.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-DmtswQEMswtb1vILE/KWwMR5Rdz+mKZ51XOC4YWNyc5N9OwZyEkjnEmbE1GCfpjEjEbK7b5ttgyCePEO5vRIWw==","shasum":"cf977faae15303caf710c253a5ad4d33e3972c8e","tarball":"https://registry.npmjs.org/@anvosio/agentify-components/-/agentify-components-0.1.0.tgz","fileCount":28,"unpackedSize":49809,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDnwN9O3TWusWF1T6NrMdDbp1v3Y3YXFVDjdy4We7fnRQIgRZwH3FSd++jkTq0BssvxYyWIKz8/57jL8w5q7f2l2xE="}]},"_npmUser":{"name":"kanlanc","email":"saivicky2015@gmail.com"},"directories":{},"maintainers":[{"name":"kanlanc","email":"saivicky2015@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentify-components_0.1.0_1742026408566_0.8297868881398278"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-15T08:13:28.503Z","0.1.0":"2025-03-15T08:13:28.761Z","modified":"2025-03-15T08:13:28.998Z"},"maintainers":[{"name":"kanlanc","email":"saivicky2015@gmail.com"}],"description":"A framework for agentifying UI components with semantic metadata for AI agents","homepage":"https://github.com/anvosio/agentify-components#readme","keywords":["react","components","agents","ai","hoc","metadata","typescript","mcp","server"],"repository":{"type":"git","url":"git+https://github.com/anvosio/agentify-components.git"},"author":{"name":"Anvos"},"bugs":{"url":"https://github.com/anvosio/agentify-components/issues"},"license":"MIT","readme":"# Agentify Components\n\n[![npm version](https://img.shields.io/badge/npm-v0.1.0-blue.svg)](https://www.npmjs.com/package/@anvos/agentify-components)\n[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nA framework for adding semantic metadata to React components, making them \"agent-aware\" for AI systems and automation tools.\n\n# NOT FINISHED! Last updated 14th march, 2025\n\n## Overview\n\nAgentify Components solves the problem of making UI components understandable to AI agents. When AI assistants interact with web applications, they typically lack context about what components do, how to interact with them, and what data they handle.\n\nThis framework adds a semantic layer to your components through decorators that:\n\n1. **Register component metadata** - Define what a component does and how it behaves\n2. **Provide a standardized schema** - Create consistent metadata structures for different component types\n3. **Generate configuration files** - Create an MCP server at build time\n\n> 🚀 **Note:** This framework focuses on *component metadata* rather than behavior modification. It makes your components \"self-describing\" to AI systems without changing their functionality.\n\n## Installation\n\n```bash\nnpm install @anvos/agentify-components\n```\n\n## Core Concepts\n\n### Component Types\n\nAgentify currently supports three main component types:\n\n- **Search Bars** - For search inputs with navigation or API behavior\n- **Forms** - For data collection with field-level metadata\n- **Buttons** - For actions with navigation, API, or UI interaction behaviors\n\n### Model Context Protocol (MCP)\n\nThe Model Context Protocol (MCP) is an open standard developed by Anthropic to connect AI models with external data sources and tools. It uses a client-server architecture, allowing AI assistants to access live data from various systems like Google Drive, Slack, or databases, enhancing their responses with up-to-date context134. MCP simplifies integrations by providing a universal protocol for secure and standardized connections, replacing custom API connectors with reusable MCP servers\n\n### Framework Architecture\n\nThe framework consists of four main parts:\n\n1. **Decorator (@AgentConfig)** - Attaches metadata to components, including common fields and protocol-specific configurations\n2. **Transformers** - Adapt the generic metadata into protocol-specific formats (e.g., for protocols like MCP for now but will be extended to other protocols in the future)\n3. **Generators** - Produce server file content based on the transformed configurations, tailored to each protocol\n4. **CLI Tool** - Processes components, applies the appropriate transformer and generator based on the target protocol, and outputs the server file\n\nThis architecture ensures flexibility—developers can define components once and support multiple protocols by adding new transformers and generators as needed.\n\n## Usage\n\n### Specific type Component Agentification Examples (NEEDS TO BE UPDATED)\n\n\n#### Agentifying a Search Bar\n\n```jsx\nimport React from 'react';\nimport { AgentConfig } from '@anvos/agentify-components';\n\n// Add semantic metadata using decorator\n@AgentConfig({\n  type: 'search',\n  behavior: {\n    type: 'api',\n    endpoint: '/api/products/search',\n    method: 'GET',\n    queryParam: 'term'\n  },\n  description: 'Search for products in the catalog',\n \n})\nexport class ProductSearch extends React.Component {\n  render() {\n    return (\n      <input \n        type=\"search\" \n        onChange={(e) => this.props.onSearch?.(e.target.value)}\n        placeholder=\"Search...\" \n      />\n    );\n  }\n}\n```\n\n#### Agentifying a Form\n\n```jsx\nimport React from 'react';\nimport { AgentConfig } from '@anvos/agentify-components';\n\n// Add semantic metadata using decorator\n@AgentConfig({\n  type: 'form',\n  behavior: {\n    type: 'api',\n    endpoint: '/api/auth/login',\n    method: 'POST'\n  },\n  fields: [\n    { name: 'username', type: 'text', required: true },\n    { name: 'password', type: 'password', required: true }\n  ],\n  purpose: 'user-authentication',\n  description: 'User login form for account access'\n})\nexport class LoginForm extends React.Component {\n  render() {\n    return (\n      <form onSubmit={this.props.onSubmit}>\n        {/* Form fields */}\n        <input type=\"text\" name=\"username\" />\n        <input type=\"password\" name=\"password\" />\n        <button type=\"submit\">Login</button>\n      </form>\n    );\n  }\n}\n```\n\n#### Agentifying a Button\n\n```jsx\nimport React from 'react';\nimport { AgentConfig } from '@anvos/agentify-components';\n\n// Add semantic metadata using decorator\n@AgentConfig({\n  type: 'button',\n  behavior: {\n    type: 'navigation',\n    href: '/checkout'\n  },\n  label: 'Proceed to Checkout',\n  description: 'Navigate to checkout page to complete purchase'\n})\nexport class CheckoutButton extends React.Component {\n  render() {\n    return (\n      <button onClick={this.props.onClick}>\n        {this.props.children}\n      </button>\n    );\n  }\n}\n```\n\n\n### Generic Component Agentification Examples\n\nThe `@anvos/agentify-components` package provides several ways to add agent configuration to your React components:\n\n#### Example 1: Functional Component with HOC\n\nFor functional components, you can use the `withAgentConfig` higher-order component to wrap your component with agent configuration:\n\n```tsx\nimport { withAgentConfig } from '@anvos/agentify-components';\n\nexport const LoginButton = withAgentConfig({\n  type: 'button',\n  behavior: { type: 'api', endpoint: '/api/login', method: 'POST' },\n  label: 'Login Button',\n  selector: '#login-btn',\n  description: 'Submits login form via API'\n})(() => {\n  return <button id=\"login-btn\">Login</button>;\n});\n```\n\n#### Example 2: Functional Component with Direct Property Assignment\n\nAlternatively, you can create a functional component and directly assign the `agentConfig` property:\n\n```tsx\nimport { AgentComponent } from '@anvos/agentify-components';\n\nexport const LoginButton2: AgentComponent = () => {\n  return <button id=\"login-btn\">Login</button>;\n};\n\nLoginButton2.agentConfig = {\n  type: 'button',\n  behavior: { type: 'api', endpoint: '/api/login', method: 'POST' },\n  label: 'Login Button',\n  description: 'Submits login form via API'\n};\n```\n\n#### Example 3: Class Component with Decorator\n\nFor class components, you can use the `@AgentConfig` decorator directly:\n\n```tsx\nimport { AgentConfig } from '@anvos/agentify-components';\n\n@AgentConfig({\n  type: 'button',\n  behavior: { type: 'navigation', href: '/home' },\n  label: 'Home Button',\n  description: 'Navigates to the home page'\n})\nclass HomeButton extends React.Component {\n  render() {\n    return <button id=\"home-btn\">Home</button>;\n  }\n}\n\nexport { HomeButton };\n```\n\n### When to Use Each Approach\n\n- **HOC Pattern (Example 1)**: Best for when you need to apply agent configuration to existing functional components or when you want to maintain separation between the component and its configuration.\n- **Direct Property Assignment (Example 2)**: Simplest approach for functional components, useful when the component is defined and configured in the same file.\n- **Decorator Pattern (Example 3)**: Most elegant option for class components, providing a clean syntax with TypeScript decorators.\n\n### MCP Tool Schema Type Mappings\n\nWhen generating the MCP server, the following JSON Schema to Zod type mappings are used:\n\n| JSON Schema Type | Zod Schema Type |\n|-----------------|----------------|\n| `string`        | `z.string()`   |\n| `number`        | `z.number()`   |\n| `boolean`       | `z.boolean()`  |\n| `array`         | `z.array(z.string())` |\n| `object`        | `z.object({})` |\n| `integer`       | `z.number()`   |\n| `float`         | `z.number()`   |\n| `date`          | `z.date()`     |\n| `datetime`      | `z.date()`     |\n| `time`          | `z.date()`     |\n\nThese mappings are used when converting the component metadata to the appropriate format for the MCP server tools.\n\n\n## Generating MCP Server\n\nAdd generate.ts file to the root of the project and add the following code:\n\n```javascript\nimport { generateMCPServer } from '@anvos/agentify-components';\nimport * as components from './components/ButtonExample';\n\nconst componentList = Object.values(components);\n\nconsole.log(componentList);\ngenerateMCPServer(componentList, './mcpServer');\n\n```\n\nNow, add the following scripts to your package.json:\n\n```javascript\n\"scripts\": {\n  \"build:mcp\": \"ts-node ./generate.ts\",\n  \"deploy:mcp\": \"echo 'STILL WORKING ON IT'\"\n}\n```\n\nThis will scan your codebase for agentified components and generate an MCP server in the `/mcpServer` directory.\n\nTo deploy your MCP server:\n\n```bash\nnpm run deploy:mcp\n```\n\nThis will deploy your MCP server to the Anvos community MCP servers on GitHub where users can easily access it. Your configuration will be available via a unique URL that you can share with AI systems and tools that support the MCP protocol.\n\nI also intend to take it a step further and make it so that only the needed tools for the client will be retuned back instead of the entire MCP server because this would lead to overfill of the MCP client with unnecessary tools.\n\n\n## Component Configuration Options\n\nSee the [setup guide](docs/setup.md) for detailed configuration options for each component type.\n\n## Documentation\n\n- [Setup Guide](docs/setup.md) - Detailed instructions and configuration options\n- [Product Requirements Document](docs/product-requirements.md) - Full project specification and roadmap\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \n\n","readmeFilename":"README.md","_rev":"1-d9b5f61cbe0e6185ac2ca2cfb7baa8db"}