MCP-Use

MCP-Use 是一个面向 TypeScript 的 MCP（Model Context Protocol）应用框架，用于构建 AI Agent、MCP Server、调试工具和项目脚手架。它把模型调用、工具接入、服务端能力和开发调试流程放在同一套工程体系里，适合用来快速搭建可执行的 Agent 应用。

项目采用 monorepo 组织，既可以作为 MCP Client 连接外部工具，也可以作为 MCP Server 框架构建自己的工具服务，还提供 Inspector 和 CLI，方便本地开发、调试和发布。

项目目标

这个项目主要解决以下问题：

1. 让 AI Agent 能稳定接入 MCP 工具，而不只是停留在文本问答层。
2. 让 MCP Server 的开发、调试、预览和发布形成完整链路。
3. 让开发者在 TypeScript 环境下统一构建 Agent、工具服务、UI 组件和工程脚手架。

核心能力

• 支持构建 MCP Client，并连接多个 MCP Server。
• 支持构建可运行的 AI Agent，让模型通过工具完成任务。
• 支持构建 MCP Server，并声明工具、资源和交互能力。
• 支持 Inspector 调试界面，便于测试工具调用和服务状态。
• 支持 CLI 开发流程，包括本地开发、构建和启动。
• 支持 TypeScript 类型推导，降低工具定义和调用成本。
• 支持将 UI Widget 与 MCP Server 一起组织和交付。

包结构

当前仓库主要包含以下包：

• mcp-use：核心框架，负责 MCP Client、MCP Agent 和 MCP Server 能力。
• @mcp-use/cli：开发与构建工具，支持本地开发、热更新和生产构建。
• @mcp-use/inspector：MCP Server 调试工具，用于测试工具调用和查看运行状态。
• create-mcp-use-app：项目初始化脚手架，用于快速创建 MCP 应用。

技术栈

• TypeScript
• Node.js
• MCP（Model Context Protocol）
• React（用于部分 UI Widget 场景）
• pnpm workspace
• tsup
• ESLint

快速开始

创建一个新的 MCP 应用：

npx create-mcp-use-app my-mcp-app
cd my-mcp-app
npm run dev

如果直接在当前仓库中开发：

pnpm install
pnpm build
pnpm dev

作为 MCP Client 使用

下面示例展示了如何连接 MCP Server，并创建一个可调用工具的 Agent：

import { MCPAgent, MCPClient } from "mcp-use";
import { ChatOpenAI } from "@langchain/openai";

const client = MCPClient.fromDict({
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["@modelcontextprotocol/server-filesystem"],
    },
  },
});

const agent = new MCPAgent({
  llm: new ChatOpenAI({ model: "gpt-4o-mini" }),
  client,
  maxSteps: 10,
});

const result = await agent.run(
  "扫描当前项目中的 TypeScript 文件，并生成一份结构摘要"
);

console.log(result);

作为 MCP Server 使用

下面示例展示了如何创建一个简单的 MCP Server，并声明工具：

import { createMCPServer } from "mcp-use/server";
import { z } from "zod";

const server = createMCPServer("weather-server", {
  version: "1.0.0",
  description: "Weather information MCP server",
});

server.tool("get_weather", {
  description: "获取指定城市的天气信息",
  parameters: z.object({
    city: z.string().describe("城市名称"),
  }),
  execute: async ({ city }) => {
    return {
      city,
      condition: "sunny",
      temperature: 28,
    };
  },
});

server.listen(3000);

Inspector 调试

项目支持通过 Inspector 对 MCP Server 进行调试和测试。启动服务后，可以在浏览器中查看工具列表、调用参数和执行结果，适合在开发阶段快速验证工具行为。

常见开发流程：

pnpm dev

启动后可以使用 Inspector 对本地服务进行检查和联调。

典型应用场景

• 构建具备工具调用能力的 AI Agent。
• 为本地文件、数据库、搜索服务等能力封装 MCP Server。
• 为 Agent 系统提供调试面板和联调入口。
• 为团队内部构建统一的 MCP 工程模板。
• 快速验证多工具协作和任务执行流程。

工程结构

仓库采用 monorepo 结构，核心目录如下：

mcp-use-ts/
├── packages/
│   ├── mcp-use/
│   ├── cli/
│   ├── inspector/
│   └── create-mcp-use-app/
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.json

开发命令

安装依赖：

pnpm install

构建全部包：

pnpm build

运行测试：

pnpm test

运行 lint：

pnpm lint

启动开发模式：

pnpm dev

扩展方向

项目可以继续扩展以下能力：

• 增加面向 OpenAI-compatible / MiMo-compatible 的模型接入示例。
• 增加多 Agent 协作示例，包括任务拆解、工具路由和结果汇总。
• 增加更完整的 UI Widget 示例，展示工具调用结果可视化。
• 增加面向业务场景的模板，例如知识库问答、文件处理和自动化检索。
• 增加更完整的生产部署示例。

许可证

MIT License