@kya-os/create-xmcpi-app

<div align="center"> <a href="https://github.com/modelcontextprotocol-identity/xmcp-i"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-dark.png"> <img alt="MCP-I logo" src="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-light.png" height="128"> </picture> </a> <h1>create-xmcpi-app</h1> <a href="https://github.com/modelcontextprotocol-identity/xmcp-i"><img alt="XMCP-I" src="https://img.shields.io/badge/XMCP--I-000000.svg?style=for-the-badge&labelColor=000"></a> <a href="https://www.npmjs.com/package/create-xmcpi-app"><img alt="NPM version" src="https://img.shields.io/npm/v/create-xmcpi-app.svg?style=for-the-badge&labelColor=000000"></a> <a href="https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md"><img alt="License" src="https://img.shields.io/npm/l/create-xmcpi-app.svg?style=for-the-badge&labelColor=000000"></a> </div> ## Create AI Agents You Actually Own Bootstrap XMCP applications with cryptographic identity. Register them with knowthat.ai, and maintain complete control over your agent's capabilities and permissions. ## Quick Start ```bash npx create-xmcpi-app@latest my-agent cd my-agent npm run dev ``` Your agent now has its own cryptographic identity! - **Generated Identity**: Ed25519 keys and DID automatically created - **Claim Ownership**: Register at knowthat.ai to claim your agent - **Secure Operation**: All responses cryptographically signed by your agent - **Permission Control**: Delegate and revoke capabilities as needed ## Command Line Options ```bash npx create-xmcpi-app [agent-name] [options] ``` ## Platform Options Choose where to deploy your owned agent: - `-p, --platform <platform>` - Target deployment platform (default: "standalone") - `standalone` - Self-contained agent server - `vercel` - Vercel edge runtime with KV identity storage - `lambda` - AWS Lambda with DynamoDB identity persistence - `nextjs` - Next.js API routes with integrated identity - `express` - Express.js server with identity middleware ## General Options - `-t, --template <template>` - Agent template (default: "typescript") - `--no-install` - Skip dependency installation - `--no-git` - Skip git initialization - `--yes` - Skip interactive prompts and use defaults - `--verbose` - Detailed output during agent creation ## Examples ```bash # Create a standalone agent you can own npx create-xmcpi-app my-personal-agent # Quick creation without prompts npx create-xmcpi-app my-quick-agent --yes ``` ## Generated Project Structure ``` my-agent/ ├── src/ │ ├── index.ts # Main agent server with identity │ ├── generate-identity.ts # Cryptographic identity generation │ ├── identity-utils.ts # Signing, verification, and ownership utilities │ ├── ensure-identity.ts # Automatic identity initialization │ ├── generated-identity.json # Your agent's identity (keep secure!) │ └── tools/ │ ├── greet.ts # Example tool with identity integration │ ├── identity-info.ts # Display agent identity information │ ├── sign-message.ts # Sign messages with agent's key │ └── verify-signature.ts # Verify ownership and signatures ├── package.json # Dependencies including xmcp-i ├── tsconfig.json # TypeScript configuration ├── .env.example # Environment variables for identity ├── .gitignore # Includes identity security rules ├── .eslintrc.json # Code quality configuration └── README.md # Agent-specific documentation ``` **Security Note**: The `generated-identity.json` file contains your agent's private key. This file is automatically added to `.gitignore` and should never be shared or committed to version control. ## Platform-Specific Features ### Vercel - Edge Identity - **Edge Runtime**: Fast cold starts with cached identity context - **KV Storage**: Secure identity persistence with Vercel KV - **Environment**: Automatic identity configuration via environment variables - **Zero Config**: Deploy with `vercel --prod` and identity works immediately ### AWS Lambda - Serverless Identity - **Cold Start Optimized**: Minimal initialization time with identity caching - **DynamoDB**: Secure, scalable identity storage with DynamoDB - **IAM Policies**: Pre-configured identity permissions and access control - **Serverless**: Ready-to-deploy serverless framework configuration ### Next.js - Full-Stack Identity - **API Routes**: Identity-enabled API endpoints with automatic verification - **SSR Support**: Server-side identity rendering and ownership verification - **Middleware**: Request-level identity verification and permission checking - **Client Integration**: Full-stack identity features for complete applications ### Express - Identity Middleware - **Middleware Stack**: Identity verification middleware for existing apps - **Flexible Routing**: Identity-aware route handlers and permission checking - **Production Ready**: Battle-tested middleware for production workloads - **Custom Auth**: Extensible identity providers and authentication flows ### Standalone - **File-based Persistence**: Local identity storage - **Self-contained Deployment**: No external dependencies - **Docker Ready**: Containerized deployment support - **Process Management**: PM2 and systemd configurations ## Adding to Existing Projects For existing Node.js/TypeScript projects, use the init command: ```bash npx init-xmcp-i@latest ``` This automatically detects your framework (Next.js, Express, or standalone) and adds identity features without disrupting your existing codebase. ## Upgrading from create-xmcp-app Upgrade your existing XMCP agents to have ownership capabilities: ### Step 1: Install xmcp-i ```bash cd my-existing-agent npm install xmcp-i ``` ### Step 2: Generate Identity ```bash npx tsx generate-identity.ts ``` Or generate inline: ```javascript // generate-identity.ts import { generateIdentity } from 'xmcp-i/generate'; import fs from 'fs'; const identity = generateIdentity(); fs.writeFileSync('src/generated-identity.json', JSON.stringify(identity, null, 2)); console.log('Identity generated:', identity.did); ``` ### Step 3: Update Imports Update your existing code imports: ```javascript // Before import { createXMCPServer } from 'xmcp'; // After import { createXMCPServer } from 'xmcp-i'; ``` ## Troubleshooting ### Common Issues #### Identity Generation Fails ```bash # Regenerate identity manually cd my-agent/src npx tsx generate-identity.ts ``` #### Platform Detection Issues ```bash # Force platform selection with verbose output npx create-xmcpi-app my-agent --platform vercel --verbose ``` #### Dependencies Issues ```bash # Skip install and run manually npx create-xmcpi-app my-agent --no-install cd my-agent && npm install ``` #### Identity File Missing ```bash # Ensure identity exists before starting npm run ensure-identity npm run dev ``` ### Debug Mode ```bash # Enable verbose logging for troubleshooting npx create-xmcpi-app my-agent --verbose # Check generated files without installation npx create-xmcpi-app my-agent --no-install --verbose ``` ## Next Steps After creating your agent: 1. **Start Development**: `npm run dev` to start your agent locally 2. **Claim Ownership**: Visit [knowthat.ai](https://knowthat.ai) to register your agent's DID 3. **Learn More**: Read the full [xmcp-i documentation](https://github.com/modelcontextprotocol-identity/xmcp-i) for advanced features 4. **Deploy**: Use platform-specific deployment guides in the xmcp-i repo ## Learn More - [XMCP-I Documentation](https://github.com/modelcontextprotocol-identity/xmcp-i) - Core framework and advanced features - [Model Context Protocol](https://modelcontextprotocol.io) - Core protocol specification ## License This project is licensed under the MIT License - see the [LICENSE](https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md) file for details.