create-mcp-i-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-mcpi-app</h1> <a href="https://github.com/modelcontextprotocol-identity/xmcp-i"><img alt="MCP-I" src="https://img.shields.io/badge/MCP--I-000000.svg?style=for-the-badge&labelColor=000"></a> <a href="https://www.npmjs.com/package/@kya-os/create-mcpi-app"><img alt="NPM version" src="https://img.shields.io/npm/v/@kya-os/create-mcpi-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/@kya-os/create-mcpi-app.svg?style=for-the-badge&labelColor=000000"></a> </div> ## Create AI Agents You Actually Own Bootstrap MCP applications with cryptographic identity built-in. Get complete control over your agent's capabilities and permissions. ## Quick Start ```bash npx create-mcpi-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-mcpi-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-mcpi-app my-personal-agent # Quick creation without prompts npx create-mcpi-app my-quick-agent --yes ``` ## Generated Project Structure ``` my-agent/ ├── src/ │ ├── server.ts # Main agent server with identity │ └── tools/ │ ├── index.ts # Tool exports │ └── hello.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**: Identity management is now handled by the `mcpi` CLI. Development identities are stored in `.mcpi/identity.json` (gitignored) and production identities use environment variables. ## 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 MCP-I CLI: ```bash npm install -g @kya-os/cli mcpi init ``` This automatically detects your framework (Next.js, Express, or standalone) and adds identity features without disrupting your existing codebase. ## Getting Started with MCP-I ### Step 1: Install MCP-I ```bash cd my-existing-agent npm install @kya-os/mcp-i ``` ### Step 2: Generate Identity ```bash # Install CLI globally npm install -g @kya-os/cli # Initialize identity (development) mcpi init # Check identity status mcpi check ``` ### Step 3: Integrate Identity ```javascript import { enableMCPIdentity } from "@kya-os/mcp-i"; const server = await enableMCPIdentity({ name: "my-agent", description: "My AI agent with identity" }); ``` ## Troubleshooting ### Common Issues #### Identity Generation Fails ```bash # Regenerate identity manually mcpi rotate --force mcpi init ``` #### Platform Detection Issues ```bash # Force platform selection with verbose output npx create-mcpi-app my-agent --platform vercel --verbose ``` #### Dependencies Issues ```bash # Skip install and run manually npx create-mcpi-app my-agent --no-install cd my-agent && npm install ``` #### Identity File Missing ```bash # Ensure identity exists before starting npm run init npm run dev ``` ### Debug Mode ```bash # Enable verbose logging for troubleshooting npx create-mcpi-app my-agent --verbose # Check generated files without installation npx create-mcpi-app my-agent --no-install --verbose ``` ## Next Steps After creating your agent: 1. **Start Development**: `npm run dev` to start your agent locally 2. **View Your Identity**: Run `mcpi check` to see your agent's DID 3. **Learn More**: Read the full [MCP-I documentation](https://github.com/modelcontextprotocol-identity/xmcp-i) for advanced features 4. **Deploy**: Use platform-specific deployment guides in the MCP-I repo ## Learn More - [MCP-I Documentation](https://github.com/modelcontextprotocol-identity/xmcp-i) - Core framework and advanced features - [Model Context Protocol](https://modelcontextprotocol.io) - Core protocol specification - [KYA-OS](https://kya-os.com) - Learn more about the KYA-OS ecosystem ## 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.