Ampersand MCP

安培和MCP

多运行时AI代理架构，具有干净的模块组织和ES模块支持。

特性

• 多运行时支持 -在AI SDK、Mastra或MCP上运行代理
• ES模块 -现代JavaScript，完全支持ES模块
• 类型安全 -具有全面类型定义的严格TypeScript
• 整洁架构 -使用路径别名分离关注点
• 运行时验证 -用于类型安全验证的Zod模式
• 可扩展 -易于添加新代理和运行时

安装

npm install

环境设置

创建一个 .env 根目录中的文件：

AMPERSAND_API_KEY=your_api_key
AMPERSAND_PROJECT_ID=your_project_id
AMPERSAND_INTEGRATION_NAME=your_integration_name
AMPERSAND_GROUP_REF=your_group_ref
OPENAI_API_KEY=your_openai_key  # Optional
NODE_ENV=development
LOG_LEVEL=info

用法

发展

# Run with watch mode
npm run dev

# Run specific runtime
npm run start:ai-sdk
npm run start:mastra-aisdk
npm run start:mastra
npm run start:mcp

父亲代理人

# Run Fathom AI SDK agent
npm run start:fathom-aisdk "Show me meetings from last week"

# Run Fathom Mastra agent (default: Mastra tools)
npm run start:fathom-mastra "Show me meetings from last week"

# Run Fathom Mastra agent with AI SDK tools
npm run start:fathom-mastra -- --agent=aisdk "What meetings do I have?"

# Run Fathom Mastra agent with MCP tools
npm run start:fathom-mastra -- --agent=mcp "Show me recent meetings"

生产

# Build
npm run build

# Run built code
npm start

命令行选项

# Run with specific runtime
npm start -- --runtime=ai-sdk
npm start -- --runtime=mcp

项目结构

src/
├── agents/                      # Agent definitions
│   ├── fathom/                 # Fathom meeting agent
│   │   ├── config.ts          # Agent configuration
│   │   ├── prompt.ts          # System prompts
│   │   ├── schema.ts          # Zod validation schemas
│   │   └── workflow.ts        # Workflow builder
│   ├── index.ts               # Agent exports
│   └── registry.ts            # Agent registry
│
├── orchestrator/              # Core orchestration
│   ├── router.ts             # Request routing
│   ├── pipeline.ts           # Execution pipeline
│   └── index.ts              # Orchestrator exports
│
├── runtimes/                  # Runtime implementations
│   ├── ai-sdk/               # Vercel AI SDK runtime
│   ├── mastra/               # Mastra runtime
│   ├── mcp/                  # Model Context Protocol
│   ├── registry.ts           # Runtime registry
│   └── utils.ts              # Runtime utilities
│
├── services/                  # External services
│   ├── llm/                  # LLM provider (OpenAI)
│   └── mcp/                  # MCP client manager
│
├── shared/                   # Shared utilities
│   ├── constants.ts         # App constants & enums
│   ├── errors.ts            # Error handling
│   ├── helpers.ts           # Utility functions
│   ├── logger.ts            # Logging utility
│   └── types/               # Type definitions
│
├── config/                   # Configuration
│   ├── app.ts               # App configuration
│   ├── env.ts               # Environment validation
│   └── mcp.ts               # MCP server config
│
└── index.ts                  # Main entry point

路径别名

该项目使用TypeScript路径别名进行干净导入：

• @agents/* -代理定义
• @orchestrator/* -编排逻辑
• @runtimes/* -运行时实现
• @services/* -对外服务
• @shared/* -共享公用设施
• @config/* -配置

例子：

import { logger } from '@shared/logger';
import { agentRegistry } from '@agents';
import { agentRouter } from '@orchestrator/router';

添加新代理

1. 创建代理目录： src/agents/[agent-name]/
2. 添加所需文件：

- config.ts -代理配置 - prompt.ts -系统提示 - schema.ts -Zod验证模式 - workflow.ts -工作流生成器

1. 出口自 src/agents/[agent-name]/index.ts
2. 注册 src/agents/index.ts

例子：

// src/agents/my-agent/index.ts
import { AgentDefinition } from '@shared/types/agent';
import { myAgentConfig } from './config';
import { MY_PROMPT } from './prompt';
import { mySchema } from './schema';
import { buildMyWorkflow } from './workflow';

export const myAgentDefinition: AgentDefinition = {
  config: myAgentConfig,
  getName: (runtime) => `My Agent (${runtime})`,
  prompt: MY_PROMPT,
  workflow: buildMyWorkflow,
  schema: mySchema,
};

添加新运行时

1. 创建运行时工厂： src/runtimes/[runtime-name]/factory.ts
2. 实施 AgentRuntimeAdapter 接口
3. 出口自 src/runtimes/index.ts
4. 注册 src/orchestrator/router.ts

例子：

// src/runtimes/my-runtime/factory.ts
import { AgentConfig, AgentRuntimeAdapter, RuntimeType } from '@shared/types/agent';
import { createRuntimeAdapter } from '@runtimes/utils';

export function createMyRuntimeAgent(
  config: Omit
): AgentRuntimeAdapter {
  return createRuntimeAdapter({
    runtime: RuntimeType.MY_RUNTIME,
    config,
    label: 'my-runtime',
    generate: async (query: string) => {
      // Your runtime implementation
      return 'response';
    },
  });
}

脚本

• npm run dev -手表开发模式
• npm run build -为生产而建
• npm start -运行构建代码
• npm run start:ai-sdk -运行AI SDK运行时
• npm run start:mastra-aisdk -使用AI SDK工具运行Mastra
• npm run start:mastra -运行Mastra运行时
• npm run start:mcp -运行MCP运行时
• npm run start:fathom-aisdk -运行Fathom AI SDK代理
• npm run start:fathom-mastra -运行Fathom Mastra代理
• npm run type-check -不发射的类型检查
• npm run lint -Lint代码
• npm run lint:fix -修复掉毛问题
• npm run format -使用Prettier格式化代码
• npm run format:check -检查代码格式
• npm run clean -清理dist目录

技术栈

• TypeScript -类型安全的JavaScript
• 萨德 -运行时验证
• Vercel AI SDK -AI/LLM抽象
• 马斯特拉 -代理框架
• 主控程序 -模型上下文协议
• 开放人工智能 -LLM提供者

需求

• Node.js>=18.0.0
• npm或纱线

许可证

麻省理工学院