@kernlang/mcp-server

MCP server for KERN -- the backend structure and portable route-logic language. Give any AI agent the ability to write, compile, review, and self-correct .kern code.

npx @kernlang/mcp-server

What is this?

KERN is a declarative DSL for backend structure, portable route logic, and AI-assisted code generation. This MCP server exposes KERN's compiler, reviewer, and schema to any MCP-compatible client (Claude Desktop, Cursor, Windsurf, VS Code, etc.).

An AI agent using this server can:

1. Ask what it can write -- schema tool returns the full language spec as JSON
2. Compile .kern to maintained targets -- especially Express, FastAPI, MCP servers, and UI/runtime adapters where they fit
3. Self-correct from errors -- compile-json returns structured diagnostics with line numbers and suggestions
4. Review code -- 76+ static analysis rules with taint tracking and OWASP coverage

Quick start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kern": {
      "command": "npx",
      "args": ["@kernlang/mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "kern": {
      "command": "npx",
      "args": ["@kernlang/mcp-server"]
    }
  }
}

Claude Code

claude mcp add kern -- npx @kernlang/mcp-server

Windsurf / VS Code

Add to your MCP settings:

{
  "kern": {
    "command": "npx",
    "args": ["@kernlang/mcp-server"]
  }
}

Tools

compile

Compile .kern source to an available target framework. Returns generated code.

source: ".kern source code"
target: "nextjs" | "tailwind" | "web" | "vue" | "express" | "fastapi" | "mcp" | ...
structure: "flat" | "bulletproof" | "atomic" | "kern"  // React targets

compile-json

Compile with structured JSON diagnostics for programmatic self-correction. Returns { success, code, diagnostics, stats }.

Each diagnostic includes code, severity, line, col, endCol, and suggestion -- everything an LLM needs to fix its own mistakes.

schema

Returns the full KERN language schema as JSON: all node types, their props (with required/optional and types), allowed children, style shorthands, and multiline block types.

Use this before writing .kern code to know exactly what's valid.

review

Run static analysis (76+ rules, taint tracking, OWASP) on TypeScript/JavaScript source code.

review-kern

Lint .kern source for structural issues, missing props, and pattern violations.

review-mcp-server

Scan MCP server code for security vulnerabilities. 13 rules mapped to OWASP MCP Top 10.

parse

Parse .kern source and return the intermediate representation (IR). Useful for debugging.

decompile

Convert parsed IR back to human-readable .kern text.

validate

Validate .kern syntax without compiling. Returns parse errors or success.

list-targets

List available compile targets plus React output structures.

list-nodes

Browse KERN node types by category (layout, backend, state, types, mcp, etc.) with their props and allowed children.

Resources

| Resource | URI | Description | |----------|-----|-------------| | kern-spec | kern://spec | Full language specification | | kern-examples | kern://examples/{category} | Example code by category (modules, ui, api, state-machine, mcp, terminal) | | kern-targets | kern://targets | Available compile targets as JSON |

Prompts

write-kern

Comprehensive system prompt that teaches an LLM how to write .kern code -- grammar rules, node types, style shorthands, and annotated examples for UI, API, state machines, MCP servers, hooks, and type systems.

LLM self-correction loop

The schema and compile-json tools enable a closed-loop workflow:

1. schema          --> "what can I write?"
2. write .kern     --> generate code using schema
3. compile-json    --> "did I get it right?"
4. if errors:
     read diagnostics (line, col, suggestion)
     fix and goto 3
5. done

No human intervention needed. The LLM can iterate to correct code autonomously.

KERN syntax at a glance

// Comments work with // or #
import { UserRepo } from "./users.kern"
import type { User } from "./types.kern"

@http.get("/users/:id")
export fn getUser(id: string): User
  let user = UserRepo.get(id)?
  return user

// Legacy node form remains valid.

doc text="User management API"
server name=UserAPI port=3001
  middleware name=cors
  middleware name=json

  route GET /api/users
    auth required
    handler <<<
      const users = await db.query('SELECT * FROM users');
      res.json(users);
    >>>

// State machine -- 7 lines, 140+ lines TypeScript output
machine name=Order initial=pending
  transition from=pending to=confirmed event=confirm
  transition from=confirmed to=shipped event=ship
  transition from=shipped to=delivered event=deliver
  transition from=pending to=cancelled event=cancel

Project structure

A typical KERN project looks like this:

my-project/
  kern.config.ts          # KERN configuration
  src/
    features/
      auth.kern           # .kern source files
      dashboard.kern
  generated/              # compiled output (--outdir)
    auth.ts
    dashboard.tsx
  src/                    # facade re-exports (--facades)
    auth.ts               # export * from '../generated/auth.js'
    dashboard.ts
  index.ts                # barrel exports (auto-generated)

With kern compile src/features --outdir=generated --facades, you write .kern files and everything else is auto-generated.

Configuration

Create kern.config.ts in your project root:

import type { KernConfig } from 'kern-lang';

const config: KernConfig = {
  // Target framework
  target: 'nextjs',

  // Output directory for generated files
  output: {
    outDir: 'src/generated',
    sourceMaps: true,
  },

  // i18n support
  i18n: {
    enabled: true,
    hookName: 'useTranslation',
    importPath: 'react-i18next',
  },

  // Component import mappings
  components: {
    uiLibrary: '@components/ui',
    componentRoot: '@/components',
  },

  // Color palette (hex -> Tailwind class)
  colors: {
    '#09090b': 'zinc-950',
    '#f97316': 'orange-500',
  },

  // Code review settings
  review: {
    showConfidence: true,
    maxComplexity: 15,
  },
};

export default config;

The config is auto-loaded by the CLI. All fields are optional -- sensible defaults are applied.

Configuration options

| Key | Default | Description | |-----|---------|-------------| | target | nextjs | Compile target (auto-detected from package.json) | | structure | flat | Output structure: flat, bulletproof, atomic, kern | | output.outDir | . | Directory for generated files | | output.sourceMaps | false | Generate .map files | | i18n.enabled | true | Wrap strings in t() calls | | i18n.hookName | useTranslation | i18n hook name | | components.uiLibrary | @components/ui | UI component import path | | colors | Zinc scale | Hex-to-Tailwind color mappings | | review.maxComplexity | 15 | Max cognitive complexity | | review.disabledRules | [] | Rule IDs to disable | | express.security | strict | Express security level | | fastapi.cors | false | Enable CORS for FastAPI |

CLI commands

The KERN CLI (kern-lang npm package) provides these commands:

# Compile .kern files to TypeScript
kern compile src/ --outdir=generated --facades --barrel

# Compile with JSON diagnostics (for LLM self-correction)
kern compile src/ --outdir=generated --json

# Dump full language schema as JSON
kern schema

# Watch mode -- recompile on changes
kern dev src/

# Scan project and auto-detect target
kern scan

# LLM-powered code review
kern review src/

Compile flags

| Flag | Description | |------|-------------| | --outdir=DIR | Output directory (default: generated/) | | --target=TARGET | Override compile target | | --structure=flat\|bulletproof\|atomic\|kern | React output structure | | --facades | Auto-generate src/*.ts re-export facades | | --facades-dir=DIR | Custom facades directory | | --barrel | Generate barrel index.ts in output dir | | --strict-parse | Fail on parse errors | | --json | Output structured JSON diagnostics |

Compile targets

| Target | Output | |--------|--------| | nextjs | Next.js App Router (TypeScript/React) | | tailwind | React + Tailwind CSS | | web | Plain React components | | vue | Vue 3 SFC | | nuxt | Nuxt 3 | | express | Express TypeScript REST API | | fastapi | FastAPI Python async backend | | native | React Native (iOS/Android) | | cli | Node.js CLI | | terminal | Terminal UI (ANSI) | | ink | Ink (React for terminals) | | mcp | MCP server (Model Context Protocol) |

License

AGPL-3.0