Nomi DevKit (@itfin/nomi-dev)

Local Development Server, Interactive UI Dashboard & MCP Tooling for Nomi Apps

Nomi DevKit is the official local development environment for building, testing, and debugging Nomi applications. It emulates the Nomi App Runner runtime locally, allowing you to test backend cloud functions, preview embedded UI panels inside <nomi-host-frame>, manage secrets/properties, and connect AI coding assistants via the Model Context Protocol (MCP).

Features

• ⚡ Zero-Config Local Runtime: Instant emulation of the Nomi App Runner environment without requiring a remote orchestrator.
• 📋 Manifest Inspection & Validation: Real-time parsing and live validation of your manifest.yaml (functions, triggers, panels, permissions, secrets, and feature flags).
• 🚀 Interactive Function Runner: Execute backend JavaScript functions directly from the browser with auto-generated schema forms or raw JSON payloads.
• 🎯 Trigger Simulation: Inspect and trigger all entry points:
  • Route / HTTP / Webhook API endpoints
  • Cron schedules and simulated ticks
  • Event listeners
  • AI action handlers
  • Sync synchronization routines
• 🖼️ Host Frame & Panel Preview: Test your iframe panels within an emulated <nomi-host-frame>, simulating host theme (light/dark), locale switching, routing, and Bridge SDK events.
• 🔐 Configuration & Secrets Manager: Inspect and mock Property Bags, scoped secrets (API keys, OAuth2), and Feature Flags.
• 🧠 Knowledge Base Sandbox: Test and manage vector knowledge base entries and metadata.
• 🤖 Integrated MCP Server: Built-in Model Context Protocol (MCP) server for AI assistants (Cursor, Windsurf, Claude Desktop, Antigravity, Copilot).
• 📊 Quality Checks & Logs: Live streaming execution logs and frontend/backend code quality validation.

Quick Start

1. Run with npx (No installation needed)

Navigate to your Nomi application folder (where manifest.yaml is located) and run:

npx @itfin/nomi-dev

Or specify the path to your application explicitly:

npx @itfin/nomi-dev --dir ./path-to-my-app --port 4200

2. Global Installation

npm install -g @itfin/nomi-dev

# Then run anywhere:
nomi-dev --dir ./my-app

Once started, the DevKit will be available at:

• 🌐 DevKit Dashboard: http://localhost:4200
• 🤖 MCP SSE Endpoint: http://localhost:4200/api/mcp/sse

CLI Options

nomi-dev [options]

Options:
  -v, --version        Output the current version
  -d, --dir <path>     Path to the application directory containing manifest.yaml (default: current working directory)
  -p, --port <number>  Port for the development server (default: 4200 or $PORT)
  -h, --help           Display help for command

Dashboard Overview

When you open http://localhost:4200, you will have access to the following sections:

1. Functions & Runner

• Displays all functions declared under functions in manifest.yaml.
• Provides an interactive Run Function modal that automatically creates a dynamic input form if inputSchema is defined, or accepts raw JSON payloads.
• Displays execution status (success, failed, queued), returned data, and execution errors.

2. Triggers

• Lists all entry points declared in triggers.
• Visually badges triggers according to their type:
  • Route / Webhook: API endpoint methods and paths
  • AI: Assistant action handlers
  • Sync: Synchronization targets
  • Event: Event listener subscriptions
  • Cron: Schedule patterns and timezones

3. UI Panels & Bridge Preview

• Previews custom frontend panels declared in panels.
• Embeds your static HTML or SPA frontend into a simulated <nomi-host-frame>.
• Allows testing bidirectional Nomi Bridge SDK actions:
  • Theme changes (light / dark)
  • Locales (uk_UA, en_US, etc.)
  • Modals & Side Panels (modal.open(), panel.open())
  • Property Bag and Secrets operations

4. Property Bags & Secrets

• Mock runtime configuration values (propertyBag.get(), propertyBag.set()).
• Configure mock integration secrets (api_key, oauth2) without exposing production credentials.

5. Feature Flags

• Test how your app behaves when feature flags are toggled on or off, or when different select options are set.

6. Executions & Logs

• Detailed execution history for all invoked functions.
• Full console output stream (console.log, console.error) with timestamps and search.

Model Context Protocol (MCP) Integration

Nomi DevKit comes with a built-in MCP server. This allows AI assistants like Claude Desktop, Cursor, Windsurf, or Antigravity to understand your app, edit the manifest, invoke functions, and inspect logs autonomously.

Configuring in Claude Desktop / Cursor / Windsurf

Add the following to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "nomi-dev": {
      "url": "http://localhost:4200/api/mcp/sse"
    }
  }
}

Available MCP Tools

| Tool | Description | | :--- | :--- | | nomi_dev_get_info | Retrieves application info, manifest data, and environment state. | | nomi_dev_validate_manifest | Validates the current manifest.yaml structure and schemas. | | nomi_dev_invoke_function | Runs a declared backend function with custom payload. | | nomi_dev_get_execution_logs | Fetches execution logs for a specific run ID. | | nomi_dev_add_function | Scaffolds and registers a new function in manifest.yaml. | | nomi_dev_add_trigger | Adds a new trigger entry to manifest.yaml. | | nomi_dev_add_panel | Declares a new UI panel in manifest.yaml. | | nomi_dev_get_properties / nomi_dev_set_property | Reads or updates Property Bag key-value items. | | nomi_dev_get_feature_flags / nomi_dev_set_feature_flag | Reads or updates application feature flag states. | | nomi_dev_get_secrets / nomi_dev_set_secret | Manages mock secrets configuration. |

Project Structure

your-nomi-app/
├── manifest.yaml          # Application manifest (triggers, functions, panels, etc.)
├── public/                # Static frontend files for panels & UI
│   └── index.html
├── src/                   # Serverless JavaScript functions
│   ├── handlers.js
│   └── sync.js
└── package.json

Related Packages

• @itfin/nomi-sdk — Official TypeScript SDK for Nomi Finance API, Bridge & Web Components.

License

MIT © ITFin / Nomi Team