# mcp-agent

**Build Effective Agents with Model Context Protocol in TypeScript**

**mcp-agent** is a TypeScript framework inspired by the Python [lastmile-ai/mcp-agent](https://github.com/lastmile-ai/mcp-agent) project. It provides a simple, composable, and type-safe way to build AI agents leveraging the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) in JavaScript and TypeScript environments.

This library aims to bring the powerful patterns and architecture of `mcp-agent` to the JavaScript ecosystem, enabling developers to create robust and controllable AI agents that can interact with MCP-aware services and tools.

## Installation
```bash
npm install @joshuacalpuerto/mcp-agent
```

## Key Capabilities

**mcp-agent** empowers you to build sophisticated AI agents with the following core capabilities:

*   **Agent Abstraction:** Define intelligent agents with clear instructions, access to tools (both local functions and MCP servers), and integrated LLM capabilities.
*   **Model Context Protocol (MCP) Integration:** Seamlessly connect and interact with services and tools exposed through MCP servers.
*   **Local Function Tools:** Extend agent capabilities with custom, in-process JavaScript/TypeScript functions that act as tools, alongside MCP server-based tools.
*   **LLM Flexibility:** Integrate with various Large Language Models (LLMs). The library includes an example implementation for Fireworks AI, demonstrating extensibility for different LLM providers.
*   **Memory Management:** Basic in-memory message history to enable conversational agents.
*   **Workflows:** Implement complex agent workflows like the `Orchestrator` pattern to break down tasks into steps and coordinate multiple agents. Support for additional patterns from Anthropic's [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) and OpenAI's [Swarm](https://github.com/openai/swarm) coming soon.
*   **TypeScript & Type Safety:** Built with TypeScript, providing strong typing, improved code maintainability, and enhanced developer experience.

## Quick Start

### Standalone Usage

Get started quickly with a basic example (Using as standalone):

```js
import { fileURLToPath } from 'url';
import path from 'path';
import { Agent, LLMFireworks, Orchestrator } from 'mcp-agent'; // Import from your library name!
import { writeLocalSystem } from './tools/writeLocalSystem'; // Assuming you have example tools

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

async function runOrchestrator() {
  const llm = new LLMFireworks("accounts/fireworks/models/deepseek-v3", { // Example LLM from Fireworks
    maxTokens: 2048,
    temperature: 0.1
  });

  const researcher = await Agent.initialize({
    llm,
    name: "researcher",
    description: `Your expertise is to find information.`,
    serverConfigs: [ // Example MCP Server Configurations
      {
        name: "read_file_from_local_file_system",
        type: "stdio",
        command: "node",
        args: ['--loader', 'ts-node/esm', path.resolve(__dirname, 'servers', 'readLocalFileSystem.ts'),]
      },
      {
        name: "search_web",
        type: "ws",
        url: createSmitheryUrl( // Example using community mcp server via @smithery/sdk
          "https://server.smithery.ai/exa/ws",
          {
            exaApiKey: process.env.EXA_API_KEY
          }
        )
      },
    ],
  });

  const writer = await Agent.initialize({
    llm
    name: "writer",
    description: `Your expertise is to write information to a file.`,
    functions: [writeLocalSystem], // Example local function tool
    llm,
  });

  const orchestrator = new Orchestrator({
    llm,
    agents: [researcher, writer],
  });

  const result = await orchestrator.generate('Search new latest developemnt about AI and write about it to `theory_on_ai.md` on my local machine. no need to verify the result.');
  console.log(JSON.stringify(result));

  await researcher.close();
  await writer.close();
}

runOrchestrator().catch(console.error);
```

https://github.com/user-attachments/assets/122a388b-0dc8-4984-b189-22408a308d7f

**To run this example:**

1.  **Install Dependencies:**
    ```bash
    pnpm install
    ```
2.  **Set Environment Variables:** Create a `.env` file (or set environment variables directly) and add your API keys (e.g., `EXA_API_KEY`, Fireworks AI API key if needed).
3.  **Run the Demo:**
    ```bash
    node --loader ts-node/esm ./demo/standalone/index.ts
    ```

### Rest server Integration
For a complete Express.js integration example with multi-agent orchestration, check out the [demo/express/README.md](./demo/express/README.md).

## Core Concepts

*   **Agent:** The fundamental building block. An `Agent` is an autonomous entity with a specific role, instructions, and access to tools. Agents can invoke tools to perform actions and interact with external services.
*   **MCP Server Aggregator (`MCPServerAggregator`):** Manages the tools available to each individual agent. Each agent has its own aggregator that provides access to the specific tools that agent needs. The aggregator acts as a tool provider for its assigned agent.
*   **MCP Connection Manager (`MCPConnectionManager`):** Central repository that manages the lifecycle and reuse of ALL MCP server connections across the entire application. This is a global collection of all available tools that any agent can potentially use.
    * **Supported Transport**: `stdio`, `sse`, `streamable-http` & `websockets`
*   **LLM Integration (`LLMInterface`, `LLMFireworks`):**  Abstracts interaction with Large Language Models.  `LLMFireworks` is an example implementation for Fireworks AI models.
*   **Tools:**  Functions or MCP server capabilities that Agents can use to perform actions. Tools can be:
    *   **MCP Server Tools:** Capabilities exposed by external MCP servers (e.g., file system access, web search).
    *   **Local Function Tools:**  JavaScript/TypeScript functions defined directly within your application.
*   **Workflows:**  Composable patterns for building complex agent behaviors (see anthropic blog [here](https://www.anthropic.com/research/building-effective-agents)).
    *   **Orchestrator** - workflow demonstrates how to coordinate multiple agents to achieve a larger objective.
    *   **Prompt chaining** - coming soon.
    *   **Routing** - coming soon.
    *   **Parallelization** - coming soon.
    *   **Evaluator-optimizer** - coming soon.
*   **Memory (`SimpleMemory`):**  Provides basic in-memory message history for conversational agents.

## Architecture: Why Connection Manager + Aggregator?

The framework uses a two-layer architecture to efficiently manage MCP server connections:

**Connection Manager (Global):** 
- Maintains a single instance of each MCP server connection across the entire application
- Prevents duplicate server connections when multiple agents need the same tool
- Example: If Agent1 and Agent2 both need a file system tool, only one file system server is spawned

**Aggregator (Per-Agent):**
- Each agent has its own aggregator that provides access to its specific set of tools
- The aggregator references tools from the global connection manager
- Acts as a tool provider interface for its assigned agent

**Benefits:**
- **Resource Efficiency:** Avoid spinning multiple instances of the same MCP server
- **Connection Reuse:** Share server connections across agents when possible
- **Isolation:** Each agent only sees the tools it's configured to use
- **Scalability:** Add new agents without duplicating existing server connections

## Evaluation

The project uses [RunLedger](https://pypi.org/project/runledger/) for deterministic agent evaluation through cassette replay. The evaluation suite lives in [`evals/runledger/`](./evals/runledger/) and runs automatically on every PR and push to `main` via GitHub Actions.

```bash
# Run evaluations locally
python -m pip install "runledger==0.1.0"
runledger run evals/runledger --mode replay --baseline baselines/runledger-demo.json
```

See the [evaluation README](./evals/runledger/README.md) for full details on how the suite works, the message protocol, and how to add new test cases.

## Acknowledgements

This project is heavily inspired by and builds upon the concepts and architecture of the excellent [lastmile-ai/mcp-agent](https://github.com/lastmile-ai/mcp-agent) Python framework

We encourage you to explore their repository for a deeper understanding of the underlying principles and patterns that have informed this TypeScript implementation.

## Contributing

Contributions are welcome!