npm package: @kya-os/create-xmcpi-app
Description: Bootstrap XMCP applications with identity features
Author: XMCP-I Team
Latest version: 0.1.0-alpha.147

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