@kya-os/mcp-i-vercel/README.md

Vercel deployment utilities for MCP-I - lightweight wrapper providing build output generation

# @kya-os/mcp-i-vercel

Vercel deployment utilities for MCP-I (Model Context Protocol with Identity). This lightweight package provides Vercel Build Output API generation while re-exporting all functionality from the main `@kya-os/mcp-i` package.

## Overview

This package enables deploying MCP-I agents to Vercel's serverless platform with proper build output structure. Since Vercel runs standard Node.js (unlike Cloudflare Workers), this package is intentionally minimal - it adds build tooling without requiring a specialized runtime.

## Quick Start

### 1. Create a new project

```bash
npx @kya-os/create-mcpi-app my-agent --platform vercel
cd my-agent
```

### 2. Build for Vercel

```bash
mcpi build --platform vercel
```

This creates the `.vercel/output` directory structure that Vercel expects.

### 3. Deploy to Vercel

```bash
vercel deploy
```

## What This Package Provides

### Build Output Generation

The package generates Vercel Build Output API v3 structure:

```
.vercel/output/
├── config.json          # Routing configuration
└── functions/
    └── api/
        └── index.func/
            ├── index.js         # Your compiled MCP-I server
            ├── .vc-config.json  # Function runtime config
            └── package.json     # Dependencies
```

### Re-exports from @kya-os/mcp-i

All types, utilities, and APIs from the main package:

```typescript
import {
  XmcpConfig,
  Middleware,
  ToolSchema,
  compile
} from '@kya-os/mcp-i-vercel';
```

### Vercel-Specific Utilities

```typescript
import { buildVercelOutput } from '@kya-os/mcp-i-vercel/build';

// Manually generate Vercel output (usually called by CLI)
await buildVercelOutput();
```

## Configuration

### vercel.json

Configure your project for Vercel deployment:

```json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "buildCommand": "mcpi build --platform vercel"
}
```

### xmcp.config.ts

Use the same configuration as standard MCP-I projects:

```typescript
import { XmcpConfig } from "@kya-os/mcp-i-vercel";

const config: XmcpConfig = {
  http: {
    port: 3000,
  },
};

export default config;
```

## Environment Variables

Set these in Vercel dashboard or via CLI:

```bash
# Required for identity features
vercel env add MCP_IDENTITY_AGENT_DID production
vercel env add MCP_IDENTITY_PRIVATE_KEY production

# Optional: AgentShield integration
vercel env add AGENTSHIELD_PROJECT_ID production
vercel env add AGENTSHIELD_API_KEY production
```

## Architecture

Unlike `@kya-os/mcp-i-cloudflare` which provides a complete runtime, this package is a thin wrapper because:

1. **Vercel runs Node.js** - No need for platform-specific runtime
2. **Standard APIs work** - File system, crypto, HTTP all work normally
3. **Build output only** - Only needs to generate proper deployment structure

The package:
- Re-exports all `@kya-os/mcp-i` functionality
- Adds `buildVercelOutput()` utility
- Configures Vercel Build Output API v3 structure
- That's it!

## Comparison with Cloudflare

| Feature | Cloudflare | Vercel |
|---------|-----------|--------|
| **Runtime** | Custom (Workers API) | Standard Node.js |
| **Package** | Full runtime (`@kya-os/mcp-i-cloudflare`) | Thin wrapper (this package) |
| **Build** | `wrangler deploy` | `mcpi build --platform vercel` |
| **Deploy** | `wrangler deploy` | `vercel deploy` |
| **Config** | `wrangler.toml` | `xmcp.config.ts` + `vercel.json` |

## API Reference

### buildVercelOutput()

```typescript
async function buildVercelOutput(): Promise<void>
```

Generates Vercel Build Output API v3 structure in `.vercel/output/`.

**Prerequisites:**
- Must have compiled output in `dist/` directory
- Must run after `mcpi build`

**Output:**
- `.vercel/output/config.json` - Routing configuration
- `.vercel/output/functions/api/index.func/` - Serverless function

**Usage:**
```typescript
import { buildVercelOutput } from '@kya-os/mcp-i-vercel/build';

// Usually called automatically by CLI with --platform vercel
await buildVercelOutput();
```

## Troubleshooting

### Build fails with "Dist directory not found"

Run standard build first:
```bash
mcpi build
mcpi build --platform vercel
```

Or use Vercel's `buildCommand` which handles both:
```json
{
  "buildCommand": "mcpi build --platform vercel"
}
```

### Function doesn't start on Vercel

Check:
1. `http.js` exists in dist/ after build
2. Environment variables are set correctly
3. Vercel logs for specific error messages

### Dependencies missing in deployment

Ensure your `package.json` has all dependencies (not just devDependencies). The build process copies `package.json` to the function directory.

## License

MIT