mcp-ai-agent

# MCP AI Agent

A TypeScript library that enables AI agents to leverage MCP (Model Context Protocol) servers for enhanced capabilities. This library integrates with the AI SDK v5 to provide a seamless way to connect to MCP servers and use their tools in AI-powered applications.

## Features

- Connect to multiple MCP servers using different transport methods (STDIO, SSE)
- Automatically discover and use tools from MCP servers
- Integrate with AI SDK for text generation with tool usage
- Filter and combine MCP tools with custom tools
- Preconfigured servers for easy initialization
- Auto-configuration support for simplified setup
- Agents can call other agents for specific tasks
- Agent composition - create specialized agents and combine them
- Named agents with descriptions for improved identification
- Auto-initialization of agents (no need to call initialize explicitly)
- Custom tool definitions directly within agent configuration
- Default model support to simplify multi-agent systems
- System prompt integration for specialized behaviors
- Verbose mode for debugging

## Roadmap

- [x] Basic agent with MCP tools integration
- [x] Auto handled MCP servers
- [x] Multi-agent workflows
- [x] Function based tool handlers
- [ ] Automatic Swagger/OpenAPI to tools conversion (stateless servers simple integration)
- [ ] API Server implementation (call your agent on a server)
- [ ] Observabilty system

## Installation

```bash
npm install mcp-ai-agent
```

For a comprehensive example implementation, check out the [mcp-ai-agent-example](https://github.com/fkesheh/mcp-ai-agent-example) repository.

## Minimal Example

Here's the most basic way to use AI Agent with preconfigured servers:

```typescript
import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

// Use a preconfigured server
const agent = new AIAgent({
  name: "Sequential Thinking Agent",
  description: "This agent can be used to solve complex tasks",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.sequentialThinking],
});

// Use the agent
const response = await agent.generateResponse({
  prompt: "What is 25 * 25?",
});
console.log(response.text);
```

### Multi-Agent Workflows (Agent Composition)

You can create specialized agents and compose them into a master agent that can delegate tasks:

```typescript
import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

// Create specialized agents for different tasks
const sequentialThinkingAgent = new AIAgent({
  name: "Sequential Thinker",
  description:
    "Use this agent to think sequentially and resolve complex problems",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.sequentialThinking],
});

const braveSearchAgent = new AIAgent({
  name: "Brave Search",
  description: "Use this agent to search the web for the latest information",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.braveSearch],
});

const memoryAgent = new AIAgent({
  name: "Memory Agent",
  description: "Use this agent to store and retrieve memories",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [
    {
      mcpServers: {
        memory: {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-memory"],
        },
      },
    },
  ],
});

// Create a master agent that can use all specialized agents
const masterAgent = new AIAgent({
  name: "Master Agent",
  description: "An agent that can manage and delegate to specialized agents",
  model: openai("gpt-4o"),
  toolsConfigs: [
    {
      type: "agent",
      agent: sequentialThinkingAgent,
    },
    {
      type: "agent",
      agent: memoryAgent,
    },
    {
      type: "agent",
      agent: braveSearchAgent,
    },
  ],
});

// Use the master agent
const response = await masterAgent.generateResponse({
  prompt: "What is the latest Bitcoin price? Store the answer in memory.",
});

console.log(response.text);

// You can ask the memory agent about information stored by the master agent
const memoryResponse = await masterAgent.generateResponse({
  prompt: "What information have we stored about Bitcoin price?",
});

console.log(memoryResponse.text);
```

## Crew AI style workflow

The MCP AI Agent can be used to create a crew of specialized agents that work together to accomplish complex tasks, similar to the Crew AI pattern. Here's an example of setting up a project management workflow with multiple specialized agents:

```typescript
import { AIAgent, CrewStyleHelpers, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import * as dotenv from "dotenv";

// Load environment variables
dotenv.config();

// Project details
const projectDetails = {
  project: "Website",
  industry: "Technology",
  team_members: [
    "John Doe (Project Manager)",
    "Jane Doe (Software Engineer)",
    "Bob Smith (Designer)",
    "Alice Johnson (QA Engineer)",
    "Tom Brown (QA Engineer)",
  ],
  project_requirements: [
    "Responsive design for desktop and mobile",
    "Modern user interface",
    "Intuitive navigation system",
    "About Us page",
    "Services page",
    "Contact page with form",
    "Blog section",
    "SEO optimization",
    "Social media integration",
    "Testimonials section",
  ],
};

// Define tasks
const tasks = {
  task_breakdown: (details) => ({
    description: `Break down the ${details.project} project requirements into individual tasks.`,
    expected_output: `A comprehensive list of tasks with descriptions, timelines, and dependencies.`,
  }),
  time_estimation: (details) => ({
    description: `Estimate time and resources for each task in the ${details.project} project.`,
    expected_output: `A detailed estimation report for each task.`,
  }),
  resource_allocation: (details) => ({
    description: `Allocate tasks to team members based on skills and availability.`,
    expected_output: `A resource allocation chart with assignments and timeline.`,
  }),
};

// Create agent
const agent = new AIAgent({
  name: "Sequential Thinking Agent",
  description: "A sequential thinking agent",
  toolsConfigs: [Servers.sequentialThinking],
});

// Define crew members
const crew = {
  planner: {
    name: "Project Planner",
    goal: "Break down the project into actionable tasks",
    backstory: "Experienced project manager with attention to detail",
    agent: agent,
    model: openai("gpt-4o-mini"),
  },
  estimator: {
    name: "Estimation Analyst",
    goal: "Provide accurate time and resource estimations",
    backstory: "Expert in project estimation with data-driven approach",
    agent: agent,
    model: openai("gpt-4o-mini"),
  },
  allocator: {
    name: "Resource Allocator",
    goal: "Optimize task allocation among team members",
    backstory: "Specialist in team dynamics and resource management",
    agent: agent,
    model: openai("gpt-4o-mini"),
  },
};

// Define schema
const planSchema = z.object({
  rationale: z.string(),
  tasks: z.array(
    z.object({
      task_name: z.string(),
      estimated_time_hours: z.number(),
      required_resources: z.array(z.string()),
      assigned_to: z.string(),
      start_date: z.string(),
      end_date: z.string(),
    })
  ),
  milestones: z.array(
    z.object({
      milestone_name: z.string(),
      tasks: z.array(z.string()),
      deadline: z.string(),
    })
  ),
  workload_distribution: z
    .record(z.string(), z.number())
    .describe("Total hours allocated to each team member"),
});

async function runWorkflow() {
  // Execute planning task
  const projectPlan = await CrewStyleHelpers.executeTask({
    agent: crew.planner,
    task: tasks.task_breakdown(projectDetails),
  });
  console.log("Project Plan:", projectPlan.text);

  // Execute estimation task
  const timeEstimation = await CrewStyleHelpers.executeTask({
    agent: crew.estimator,
    task: tasks.time_estimation(projectDetails),
    previousTasks: { projectPlan: projectPlan.text },
  });
  console.log("Time Estimation:", timeEsti

[truncated…]