npm package: @kya-os/create-mcp-i-app
Description: Bootstrap MCP applications with identity features (temporary - use @kya-os/create-mcpi-app after Oct 7)
Author: MCP-I Team
Latest version: 1.2.4

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