MCP Apps Kit

Features at a Glance

Quick Start

npx @mcp-apps-kit/create-app@latest my-app
cd my-app && npm run dev

Or manually set up a file-based project:

npm install @mcp-apps-kit/core @mcp-apps-kit/codegen zod

How It Works

MCP AppsKit uses file-based conventions to eliminate boilerplate. Drop files in the right directories and everything wires up automatically.

Project Structure

my-app/
├── mcp.config.ts              # App configuration (single source of truth)
├── tools/
│   ├── get-weather.ts         # → getWeather tool
│   └── search-location.ts     # → searchLocation tool
├── workflows/
│   └── daily-briefing.ts      # → dailyBriefing workflow
├── ui/widgets/
│   ├── get-weather.tsx        # → Auto-bound to getWeather tool
│   └── daily-briefing.tsx     # → Auto-bound to dailyBriefing
├── middleware/
│   └── logging.ts             # Runs on every tool call
├── handlers/
│   └── app-lifecycle.ts       # Server events (start, shutdown)
└── __generated__/             # Auto-generated (gitignored)
    └── app-manifest.ts

Configuration

// mcp.config.ts
import { defineConfig } from "@mcp-apps-kit/codegen";

export default defineConfig({
  name: "weather-app",
  version: "1.0.0",
  directories: {
    tools: "tools",
    workflows: "workflows",
    uiWidgets: "ui/widgets",
    middleware: "middleware",
    handlers: "handlers",
  },
  config: {
    protocol: "mcp", // or "openai" for ChatGPT
    cors: { origin: true },
  },
});

Define a Tool

// tools/get-weather.ts
import { tool } from "@mcp-apps-kit/core";
import { z } from "zod";

export default tool
  .describe("Get current weather for a location")
  .input({
    location: z.string().describe("City name"),
  })
  .output(
    z.object({
      temperature: z.number(),
      conditions: z.string(),
      humidity: z.number(),
    })
  )
  .handle(async ({ location }) => {
    const data = await fetchWeather(location);
    return {
      temperature: data.temp,
      conditions: data.weather,
      humidity: data.humidity,
    };
  });

Create a Widget

Widgets in ui/widgets/ automatically bind to tools with matching filenames:

// ui/widgets/get-weather.tsx
import { useToolResult, useHostContext } from "@mcp-apps-kit/ui-react";
import type { WidgetMetadata } from "@mcp-apps-kit/core";

export default function WeatherWidget() {
  const result = useToolResult<{ temperature: number; conditions: string }>();
  const { theme } = useHostContext();

  if (!result) return <div>Loading...</div>;

  return (
    <div className={theme === "dark" ? "dark" : ""}>
      <h2>{result.temperature}°C</h2>
      <p>{result.conditions}</p>
    </div>
  );
}

// Widget metadata (optional)
export const ui: WidgetMetadata = {
  name: "Weather Display",
  prefersBorder: true,
};

Run Your App

npm run dev

The codegen watches for changes and regenerates the manifest. Your tools and widgets are instantly available. Widget changes are picked up by Vite's HMR with React Fast Refresh — no full reload needed.

Naming Conventions

Files are automatically converted to camelCase identifiers:

Packages

Advanced Features

Middleware

Add cross-cutting concerns like logging, auth, or metrics:

// middleware/logging.ts
import { defineMiddleware } from "@mcp-apps-kit/codegen";

export default defineMiddleware({
  before: async (ctx) => {
    ctx.state.set("startTime", Date.now());
    console.log(`Tool called: ${ctx.toolName}`);
  },
  after: async (ctx) => {
    const duration = Date.now() - ctx.state.get("startTime");
    console.log(`Completed in ${duration}ms`);
  },
});

Event Handlers

React to server lifecycle events:

// handlers/app-lifecycle.ts
import { defineHandler, Events } from "@mcp-apps-kit/codegen";

export default defineHandler({
  event: Events.APP_START,
  handler: async ({ port }) => {
    console.log(`Server started on port ${port}`);
  },
});

Multi-Version APIs

Support multiple API versions from a single codebase:

// mcp.config.ts
export default defineConfig({
  name: "my-api",
  versions: {
    v1: {
      version: "1.0.0",
      // Uses versions/v1/tools, versions/v1/workflows, etc.
    },
    v2: {
      version: "2.0.0",
      config: { debug: { level: "debug" } },
    },
  },
});

Workflow Engine

Compose multi-step operations:

// workflows/order-process.ts
import { workflow, toolStep } from "@mcp-apps-kit/core";
import { z } from "zod";

export default workflow("process_order")
  .input({ orderId: z.string() })
  .output({ success: z.boolean() })
  .step("validate", toolStep("validate_order"))
  .step("payment", toolStep("process_payment"), {
    retry: { maxAttempts: 3, backoff: "exponential" },
  })
  .parallel("notify", [toolStep("send_email"), toolStep("send_sms")])
  .build();

Platform Support

Examples

Weather App

Full-featured example with tools, widgets, middleware, and workflows:

git clone https://github.com/AndurilCode/mcp-apps-kit.git
cd mcp-apps-kit/examples/weather-app
pnpm install && pnpm dev

Kanban Demo

Production-ready example with tool calling, React widgets, plugins, middleware, and events:

git clone https://github.com/AndurilCode/kanban-mcp-example.git
cd kanban-mcp-example
npm install && npm run dev

Deployment

Express (default)

// Handled automatically by codegen
npm run start

Stdio Mode

// mcp.config.ts
export default defineConfig({
  // ...
  config: {
    transport: "stdio",
  },
});

Serverless

import { createFileBasedApp } from "@mcp-apps-kit/codegen";

const app = await createFileBasedApp();

export default {
  async fetch(request: Request) {
    return app.handleRequest(request);
  },
};

Compatibility

• Node.js: >= 18 (runtime), >= 20 (development/CLI)
• React: 18.x or 19.x
• Zod: ^4.0.0
• Vite: 5.x, 6.x, or 7.x

API Reference

Full Documentation — TypeDoc-generated API reference

Package documentation:

• Core API
• UI SDK
• React Hooks
• Widget Builder
• Testing

Contributing

See CONTRIBUTING.md for development setup. Issues and pull requests welcome.

License

MIT