MCP Apps Kit

Build interactive AI apps for MCP Apps and ChatGPT. The Modern TypeScript Way.

=18">

Quick Start • Documentation • Examples • Issues

______________________________________________________________________

功能一览

______________________________________________________________________

快速开始

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

或者手动设置基于文件的项目：

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

______________________________________________________________________

运作原理

MCP AppsKit使用 基于文件的约定 以消除样板。将文件放到正确的目录中，所有内容都会自动连接起来。

项目结构

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

配置

// 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 },
  },
});

定义工具

// 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,
    };
  });

创建小部件

小工具在 ui/widgets/ 自动绑定到具有匹配文件名的工具：

// 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();
  const { theme } = useHostContext();

  if (!result) return 
Loading...
;

  return (
    

      
{result.temperature}°C

      
{result.conditions}

    

  );
}

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

运行您的应用程序

npm run dev

编码员观察变化并重新生成清单。您的工具和小部件可以立即使用。Vite的HMR通过React Fast Refresh接收小部件更改，无需完全重新加载。

______________________________________________________________________

命名规范

文件会自动转换为camelCase标识符：

______________________________________________________________________

包裹

______________________________________________________________________

高级功能

中间件

添加跨领域关注点，如日志记录、身份验证或指标：

// 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`);
  },
});

事件处理器

对服务器生命周期事件做出反应：

// 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}`);
  },
});

多版本API

从单个代码库支持多个API版本：

// 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" } },
    },
  },
});

工作流引擎

组合多步骤操作：

// 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();

______________________________________________________________________

平台支持

______________________________________________________________________

例子

天气应用程序

包含工具、小部件、中间件和工作流的全功能示例：

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

看板演示

具有工具调用、React小部件、插件、中间件和事件的生产就绪示例：

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

______________________________________________________________________

部署

Express（默认）

// Handled automatically by codegen
npm run start

标准模式

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

无服务器

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

const app = await createFileBasedApp();

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

______________________________________________________________________

兼容性

• Node.js：>=18（运行时），>=20（开发/CLI）
• 反应：18.x或19.x
• 黄道带: ^4.0.0
• 维特：5.x、6.x或7.x

______________________________________________________________________

api参考

全部文件 -TypeDoc生成的API引用

包装文件：

• 核心api
• UI SDK
• React挂钩
• 小部件生成器
• 测试

______________________________________________________________________

贡献

看 贡献.md 用于开发设置。欢迎问题和拉取请求。

______________________________________________________________________

许可证

麻省理工学院