Carla Next.js


> Automatically turn your Next.js API routes into AI-powered tools for the Interworky assistant.

Features

- 🔍 Auto-discovery - Scans API routes and generates tool definitions
- 🤖 AI-Ready - Works with OpenAI Realtime API (text & voice)
- 📦 Zero Config - One command to install widget
- 🔄 Smart Sync - Push tools to Interworky dashboard
- 🛠️ Auto-Fix - Detects and fixes common issues
- 🎯 Type-Safe - Full TypeScript support

Quick Start

$3

``bash


Add your API key to .env.local

NEXT_PUBLIC_CARLA_API_KEY="your-api-key-here"

Install the Interworky widget

npx @interworky/carla-nextjs install
`

This adds the Carla assistant widget to your Next.js app.

$3

`bash


Scan your API routes

npx @interworky/carla-nextjs scan

Review generated tools

npx @interworky/carla-nextjs status

Sync to Interworky

npx @interworky/carla-nextjs sync
`

That's it! Your assistant now has access to your API routes.

Installation Options

`bash


Interactive setup (recommended)

npx @interworky/carla-nextjs interactive

Install widget on specific pages

npx @interworky/carla-nextjs install --pages "/,/products,/pricing"

Install with custom delay

npx @interworky/carla-nextjs install --delay 2000

Install with landing page mode

npx @interworky/carla-nextjs install --landing
`

Commands

| Command | Description |
|--------------|--------------------------------------|
| install | Install Carla widget in your app |
| scan | Scan API routes and generate tools |
| generate-mcp | Generate HTTP MCP routes at /api/mcp |
| sync | Sync enabled tools to Interworky |
| status | Show current sync status |
| fix | Auto-fix tool issues |
| interactive| Interactive setup wizard |
| mcp | Start MCP server for AI editors |

Environment Variables

Add to your .env.local, .env.development, or .env:

`bash
NEXT_PUBLIC_CARLA_API_KEY="your-api-key-here"
`

Get your API key from the Interworky Dashboard.

How It Works

`
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Next.js │───▶│ carla-nextjs │───▶│ Interworky │
│ API Routes │ │ CLI Tool │ │ Dashboard │
└─────────────┘ └──────────────┘ └─────────────┘
│ │
│ ┌──────────────┐ │
└───────────▶│ Carla Widget │◀───────────┘
│ (Frontend) │
└──────────────┘
`

1. Scan - CLI analyzes your API routes using TypeScript AST
2. Generate - Creates tool definitions with types and descriptions
3. Sync - Pushes enabled tools to Interworky
4. Execute - Carla assistant can call your APIs in real-time

JavaScript & TypeScript Support

Carla Next.js automatically detects your project type and generates the appropriate files:

- TypeScript projects → .tsx components
- JavaScript projects → .jsx components

Widget Features

The installed widget component:

- ✅ Loads asynchronously (non-blocking)
- ✅ 1.5s delay for optimal performance
- ✅ Proper cleanup on unmount
- ✅ Route-based conditional loading
- ✅ Error handling and fallbacks

Examples

$3

`bash
npx @interworky/carla-nextjs scan --path ./src/app/api
`

$3

`bash
npx @interworky/carla-nextjs scan --force
npx @interworky/carla-nextjs sync
`

$3

`bash
npx @interworky/carla-nextjs status --verbose
`

$3

`bash


Generate HTTP MCP routes for AI integration

npx @interworky/carla-nextjs generate-mcp

Force regenerate if routes already exist

npx @interworky/carla-nextjs generate-mcp --force
`

MCP HTTP Routes

The generate-mcp command creates HTTP endpoints that expose your API tools via the Model Context Protocol:

$3

- GET /api/mcp/tools - Returns the catalog of available tools
- POST /api/mcp/call - Executes a tool with provided arguments

$3

`javascript
// Get available tools
fetch('http://localhost:3000/api/mcp/tools')
.then(res => res.json())
.then(tools => console.log(tools));

// Execute a tool
fetch('http://localhost:3000/api/mcp/call', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
tool: 'get_users',
args: { limit: 10 }
})
})
.then(res => res.json())
.then(result => console.log(result));
`

MCP Server Integration

Use with AI editors like Cursor or Claude Desktop:

`json
{
"mcpServers": {
"carla-nextjs": {
"command": "npx",
"args": ["carla-nextjs", "mcp"],
"cwd": "/path/to/your/nextjs/project"
}
}
}
``

Now your AI editor can scan, fix, and sync tools automatically.

Requirements

- Node.js 18+
- Next.js 14+
- React 18+

Support

- 📧 Email: hello@interworky.com
- 📚 Docs: interworky.com/docs
- 🐛 Issues: GitHub Issues
- 💬 Discord: Join Community

License

MIT © Interworky

---

Made with ❤️ by the Interworky team