STARWARCLOUD STARWAR.AI
返回市场
智能模板mcp代理

智能模板mcp代理

作者：Sri017295 星标更新：2025-08-13
安装使用来源：spider==github.com

项目介绍

智能MCP代理模板

用于创建能够动态发现、安装并使用MCP（模型上下文协议）服务器的智能AI代理的Mastra模板。此模板为构建能够自动查找并通过MCP生态系统集成外部服务的代理提供了基础。

🚀 特性

  • 动态MCP服务器发现：在Smithery注册表中搜索可用的MCP服务器
  • 自动服务器安装：动态地将服务器添加到代理配置中
  • 持久配置：服务器永久添加到代码库中
  • 文件系统访问：内置文件系统MCP服务器，用于项目文件操作
  • 内存管理：基于LibSQL的内存存储，用于代理状态
  • 类型安全：完全支持TypeScript，并带有Zod模式验证

🏗️ 项目结构

src/
├── mastra/
│   ├── agents/
│   │   └── smart-mcp-agent.ts      # 具有MCP功能的主要AI代理
│   ├── tools/
│   │   ├── add-mcp-server.ts       # 动态向配置添加MCP服务器
│   │   ├── discover-servers.ts     # 在Smithery注册表中搜索服务器
│   │   └── list-servers.ts         # 列出当前配置的服务器
│   ├── index.ts                    # Mastra配置
│   ├── mcp.ts                      # MCP客户端配置
│   └── types.ts                    # TypeScript类型定义

🛠️ 安装

  1. 克隆模板：

    npx create-mastra@latest template-smart-mcp-agent
cd template-smart-mcp-agent

  2. 安装依赖项：

    npm install

  3. 设置环境变量：

    cp .env.example .env
# 编辑.env文件以包含您的API密钥

  4. 启动开发服务器：

    npm run dev

🔧 配置

环境变量

变量描述必需
OPENAI_API_KEY用于代理模型的OpenAI API密钥是
SMITHERY_API_KEYSmithery注册表API密钥是

代理配置

import { smartMcpAgent } from './src/mastra/agents/smart-mcp-agent';

// 代理配置包括：
// - OpenAI GPT-4o-mini模型
// - 基于LibSQL的内存存储
// - 动态MCP服务器管理

🔄 工作流程

智能MCP代理遵循以下工作流程：

  1. 发现：使用discover-servers在Smithery上搜索MCP服务器
  2. 安装：使用add-mcp-server动态添加服务器到配置中
  3. 验证：使用list-servers确认安装
  4. 使用：通过代理访问服务器工具

示例用法

// 搜索网络搜索服务器
await discoverServersTool.execute({
  context: { query: "web search", limit: 5 }
});

// 添加一个网络搜索服务器
await addMcpServerTool.execute({
  context: {
    name: "websearch",
    serverId: "@Aas-ee/open-websearch",
    description: "网络搜索能力"
  }
});

// 列出已配置的服务器
await listServersTool.execute({ context: {} });

🛠️ 工具

添加MCP服务器工具

动态地将MCP服务器添加到mcp.ts配置文件中。

输入模式：

{
  name: z.string().min(1),           // 服务器名称（例如："websearch"）
  serverId: z.string().min(1),       // 完整的服务器ID（例如："@Aas-ee/open-websearch"）
  description: z.string().optional() // 可选描述
}

特性：

  • 自动将服务器名称转换为有效的JavaScript标识符
  • 更新mcp.ts文件以进行正确的配置
  • 触发自动服务器重启以加载新服务器
  • 提供清晰的反馈和下一步操作

发现服务器工具

在Smithery注册表中搜索可用的MCP服务器。

输入模式：

{
  query: z.string(),                 // 搜索查询
  limit: z.number().int().min(1).max(20).optional() // 结果限制
}

特性：

  • 使用可选API密钥搜索Smithery注册表
  • 返回服务器详情，包括名称、描述和使用统计信息
  • 如果API不可用时优雅回退

列出服务器工具

列出所有当前配置的MCP服务器。

特性：

  • 读取当前的mcp.ts配置
  • 识别服务器类型（Smithery、文件系统等）
  • 显示服务器ID和配置详情
  • 提供清晰的状态信息

🔄 服务器管理

添加服务器

当您使用add-mcp-server添加服务器时：

  1. 配置更新：服务器被添加到src/mastra/mcp.ts
  2. 自动重启：Mastra服务器重启以加载新服务器
  3. 持久性：服务器配置在重启后仍然存在
  4. 验证：使用list-servers确认成功添加

服务器类型

  • Smithery服务器：托管在Smithery上的远程MCP服务器
  • 文件系统服务器：本地文件系统访问，用于项目文件
  • 自定义服务器：任何兼容MCP的服务器

当前配置

模板预配置了这些服务器：

  • textEditor：项目文件的文件系统访问
  • geeknews：科技新闻和更新
  • aidaily：AI每日新闻和见解

🛡️ 错误处理

模板包括全面的错误处理：

  • MCP连接失败：优雅地处理服务器连接问题
  • 文件系统错误：具有适当错误消息的安全文件操作
  • API速率限制：对外部API调用的内置重试逻辑
  • 验证错误：带有清晰错误消息的Zod模式验证

🚀 开发

可用脚本

  • npm run dev - 启动具有热重载的开发服务器
  • npm run build - 构建生产版本
  • npm run start - 启动生产服务器

开发工作流程

  1. 启动开发服务器：npm run dev
  2. 访问游乐场：http://localhost:4111
  3. 测试代理交互：使用游乐场与代理互动
  4. 添加新服务器：使用代理发现并添加MCP服务器
  5. 监控日志：检查终端输出以获取服务器状态和错误

📝 API参考

代理

smartMcpAgent提供：

  • 模型：OpenAI GPT-4o-mini
  • 内存：基于LibSQL的持久存储
  • 工具：动态MCP服务器管理工具
  • 指令：全面的工作流程指导

MCP客户端

MCP客户端（buildMcp）管理：

  • 服务器连接：自动连接到配置的服务器
  • 工具发现：从MCP服务器动态加载工具
  • 错误恢复：优雅地处理连接问题
  • 心跳管理：自动连接维护

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 如适用，添加测试
  5. 提交拉取请求

📄 许可证

ISC许可证 - 详情见LICENSE文件。

🔗 资源