使用说明

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

Quick Start • Documentation • Examples • Issues

功能一览

特性	描述
基于文件的开发	从文件系统中自动发现的工具、小部件和工作流
约定优于配置	`tools/get-weather.ts` → `getWeather` 工具，自动
托管小部件	React用户界面 `ui/widgets/` 自动绑定到匹配工具
类型安全端到端	从输入到UI道具的完整TypeScript推理
双平台	单个代码库部署到MCP应用程序和ChatGPT
热模块重新加载	Vite驱动的HMR，支持小部件的React快速刷新
零沸点板	没有要维护的清单文件——codegen会处理它

快速开始

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<{ 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,
};

运行您的应用程序

npm run dev

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

命名规范

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

文件	工具名称
`get-current-weather.ts`	`getCurrentWeather`
`search_locations.ts`	`searchLocations`
`DailyBriefing.ts`	`dailyBriefing`
`_shared.ts`	（忽略--下划线前缀）

包裹

包装	描述
`@mcp-apps-kit/core`	带有工具/工作流构建器的服务器框架
`@mcp-apps-kit/codegen`	基于文件的发现和清单生成
`@mcp-apps-kit/ui`	客户端SDK（vanilla JS）
`@mcp-apps-kit/ui-react`	React绑定和钩子
`@mcp-apps-kit/ui-react-builder`	用于小部件捆绑和HMR的Vite插件
`@mcp-apps-kit/create-app`	CLI脚手架工具
`@mcp-apps-kit/testing`	测试工具和模拟

高级功能

中间件

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

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

平台支持

功能	MCP应用程序	ChatGPT应用程序
工具调用	是	是
结构化输出	是	是
React小部件	是	是
OAuth 2.1	是	是
主题支持	是	是
持续状态	否	是
工具取消	是	否

例子

天气应用程序

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

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引用

包装文件：

贡献

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

许可证

麻省理工学院