Technical analysis of the Zen MCP (Model Context Protocol) Server architecture, implementation, and design patterns.

Zen MCP

Zen MCP breakdown


## Project summary

The Agent Framework is a AI agent system designed to create and manage autonomous digital personas that can engage with users through chat interfaces and perform automated actions like posting on social media platforms like Twitter. The system uses large language models via OpenRouter's AI SDK and includes capabilities for text generation, image creation, and intelligent scheduling of actions to maintain realistic persona behavior. An internal chat application was developed to showcase and test the agent's capabilities, providing a practical demonstration tool for stakeholders.

### Overview

| Project title | AI agent |
| --- | --- |
| Industry | Web3 |
| Project description | The Agent Framework enables the creation and management of autonomous digital personas that interact through chat and perform scheduled actions on social media. |
| Client Information | Dwarves Foundation partnered with a Web3 outsourcing firm to deliver a product for a prominent end client in the blockchain space. Due to NDA restrictions, client names cannot be disclosed. |
| Timeline | 6 - 9 months |
| Outcome | Fully built and delivered product; development paused pending a new business model |
| Type | Consulting, Time & Materials |

## Tech stack
| **Platform** | **Tech** |
| --- | --- |
| **Frontend** | Next.js (React framework), Streaming API responses |
| **Backend** | NestJS (Node.js framework), Twitter API (Social Media Integration), Cron job for task scheduling |
| **Database** | PostgreSQL with Prisma as the ORM library |
| **AI Integration** | OpenRouter AI SDK, Vercel AI SDK, Image generation capabilities |
| **Architecture** | Monorepo structure with Nx, Microservices pattern, Package-based modularization |

### System architecture

![](assets/system-architecture.png)

### Agent tweet workflow

![](assets/agent-tweet-workflow.png)

### Agent’s chat workflow

![](assets/agent-chat-workflow.png)

## The context

The project addresses the need for creating and managing AI personas that can:

1. Engage in natural conversations with users through a chat interface
2. Post content on social media platforms automatically with customizable frequencies
3. Generate appropriate images to accompany social media posts
4. Maintain consistent personality traits and behavioral patterns
5. Scale across multiple agent instances with different configurations

The framework solves the challenge of creating believable AI personas by combining configurable personality traits with automated scheduling of actions, making the agents appear more human-like in their behaviors and engagement patterns.

An internal chat application was developed to demonstrate the capabilities of these agents to stakeholders and to provide a testing ground for agent development. This application serves as both a proof-of-concept and a valuable internal tool for refining agent personalities and behaviors before deploying them to public-facing channels.

## Engagement model

The system employs several key engagement patterns:

1. **Agent configuration**:
    - Agents are defined with specific personality traits, abilities, moods, and execution parameters
    - Each agent has configurable responsiveness settings for different actions (posting, replying, retweeting)
2. **Conversational interface**:
    - Users can chat directly with agents through the internal web interface
    - Conversations are streamed in real-time and stored in a database for continuity
    - The internal chat app provides a controlled environment for testing and refining agent responses
3. **Automated actions**:
    - Agents can perform automated actions like posting tweets based on their configuration
    - A scheduler manages when agents perform actions based on configurable intervals (hourly or daily)
    - Random timing within intervals adds natural variability to agent behaviors
4. **Content generation**:
    - Text content is generated using AI models through OpenRouter
    - Image generation capabilities allow for visual content creation
    - Avatar customization enhances agent personas

## Outcome

![](assets/test-agent-share-tweets.png)

*Test Agent share tweets on our X Test Account*

![](assets/the-internal-chat-bot.png)

*The internal chat bot that has agent personalities and abilities*

The Agent Framework successfully delivers:

1. A flexible architecture that supports multiple agent personalities with configurable traits
2. A natural chat experience with real-time response streaming through an internal application
3. Automated social media engagement with Twitter integration
4. Intelligent scheduling of agent actions to maintain believable behavior patterns
5. Image generation capabilities to enhance agent-created content
6. Comprehensive logging of interactions and token usage for analysis

The internal chat application provides a controlled environment for testing and refining agent behaviors before deploying to public-facing channels. It serves as both a showcase of the technology's capabilities and a practical tool for iterative development.

## Impact

The Agent Framework represents a significant advancement in AI persona creation and management, with potential applications in:

1. Social media marketing and engagement
2. Customer service and support
3. Entertainment and interactive experiences
4. Personal assistant capabilities
5. Educational engagement and tutoring

By combining sophisticated AI language models with behavioral scheduling and multimedia content generation, the framework enables the creation of believable digital personas that can engage with users across multiple channels while maintaining consistent identities and behaviors.

The internal chat application has proven invaluable for:

- Demonstrating agent capabilities to stakeholders
- Testing and refining agent personalities before public deployment
- Training team members on agent interaction patterns
- Gathering feedback to improve the framework
- Documenting agent behaviors for quality assurance

The agent's ability to autonomously generate content and determine when visual assets are needed for social posts demonstrates a level of contextual awareness that goes beyond simple chatbots, creating more engaging and human-like digital experiences. The internal chat tool provides a safe environment to explore these capabilities and refine them before wider deployment.

### Our gains

- Vercel AI SDK: hands-on experience implementing streaming responses and AI agent integration patterns
- Agent system design: Developed knowledge in creating autonomous personas with configurable traits and behaviors

Explore the system design behind scalable AI agents, featuring modular architecture, streaming responses, and automated task scheduling for social platforms.

Building an AI-powered agent system with OpenRouter SDK and Web3 technologies


## Pricing models

### Freemium model

- **Description:** Attracts users with a free basic version, encouraging upgrades to paid plans for premium features.

- **Example:** Evernote offers a free Basic plan, with Premium and Business paid plans.

- **Use cases:** Gain market share, test in new markets, products with viral potential.

### Pay per quantity model

- **Description:** Charges based on the number of units (e.g., seats, emails).

- **Example:** Help Scout charges $20/user/month after the free plan for 2 users.

- **Use cases:** Predictable costs that scale with business, targeting large organizations.

### Pay per active user model

- **Description:** Charges only for users active during the billing period.

- **Example:** Slack charges based on active users, with a fair billing policy.

- **Use cases:** Persuade large enterprises, fair billing.

### Flat-fee model

- **Description:** Charges a flat recurring fee for a single plan or product.

- **Example:** Hubspot has different tiers with fixed monthly fees.

- **Use cases:** Generate consistent revenue, cater to risk-averse customers.

### Pay-as-you-go (usage-based) model

- **Description:** Charges based on usage with Tiered, Volume, and Stair-step variations.

- **Example:** Postmark charges $10 for up to 10,000 emails, up to $400 for 300,000-700,000 emails.

- **Use cases:** Value-based pricing, flexible according to demand.

### Tiered model

- **Description:** Different price points for different usage tiers.

- **Example:** ManageWiz charges based on the tier of units purchased.

- **Use cases:** Structured pricing for varying quantities.

### Volume model

- **Description:** Price per unit decreases with quantity.

- **Example:** Jira offer price per unit decrease base on size of your company

- **Use cases:** Economies of scale, incentivize larger purchases.

### Stair-step model

- **Description:** Fixed price points for usage ranges.

- **Example:** Trello categorizes pricing by usage ranges with fixed prices.

- **Use cases:** Certainty in pricing, easy to understand.

### 'Name Your Price' or Custom Pricing

- **Description:** Custom prices for each customer, often via sales negotiation.

- **Example:** Jira offers custom deals for enterprise plans.

- **Use cases:** High-touch sales processes, tailored pricing for large clients.

### Hybrid model

- **Description:** Combines multiple pricing models.

- **Example:** DocuSign uses both user number and document limits for pricing.

- **Use cases:** Multi-dimensional value extraction, upgrade opportunities.

### À la carte Model

- **Description:** Customers choose and pay for specific features/services.

- **Example:** Shopify allows merchants to choose and pay for specific features, like advanced reporting or additional staff accounts

- **Use cases:** Products with many use cases, flexible feature selection.

## References

https://www.chargebee.com/resources/guides/subscription-pricing-trial-strategy/find-the-right-pricing-model/


Subscription pricing models


![Command pattern](assets/command-pattern_command-en-2x.webp)

## What is the Command Design Pattern?

Command is a behavioral design pattern that encapsulates a request as an object. This allows you to parameterize methods with different requests, delay or queue a request’s execution, and support undoable operations. This pattern promotes the decoupling of the sender and receiver of a request, enhancing flexibility and maintainability.

## Key components of the Command pattern

![Structure of the Command design pattern](assets/command-pattern_structure-2x.webp)

### Command interface

**Purpose**

- Declares a method for executing a command.
- Ensures that all concrete commands implement this method, providing a consistent interface.

**Responsibilities**

- Defines an `execute()` method that `concrete commands` must implement.

### Concrete command

**Purpose**

- Implements the Command interface.
- Defines the binding between a `Receiver` object and an action.
- Calls the appropriate operations on the `Receiver`.

**Responsibilities**

- Implements the `execute()` method by invoking the corresponding operation(s) on the `Receiver`.
- Holds a reference to the Receiver.

### Receiver

**Purpose**

- Knows how to perform the operations needed to carry out the request.

**Responsibilities**

- Performs the actual work when its methods are called by the `Concrete command`.

### Invoker

**Purpose**

- Asks the command to carry out the request.
- Can store and queue commands, and even support undo operations by storing executed commands.

**Responsibilities**

- Maintains a reference to a Command object (or a list of Command objects).
- Calls the `execute()` method on the Command object.

## The real life example

![Restaurent](assets/command-pattern_command-comic-1-2x.webp)

> Imagine you own a small restaurant where you are both the chef and the person taking orders directly from your customers. As the chef, you prepare each meal yourself.
>
> As your restaurant gains popularity, you find it increasingly difficult to handle the growing number of orders. To manage this, you decide to hire a waiter. The waiter's responsibilities include taking orders from customers and writing them down on a piece of paper.
>
> The waiter then brings the written orders to the kitchen and sticks them on the wall. You, the chef, can pick up these order slips from the wall and prepare the meals accordingly. Once you finish cooking, you place the meal on a tray along with the corresponding order slip.
> The waiter retrieves the tray, double-checks the order, and serves the meal to the customer.

In this scenario, the paper order serves as a `Command`. It remains in a queue until the chef is ready to prepare it. The order contains all the relevant information required to cook the meal, allowing the chef to start cooking immediately instead of clarifying the order details directly from the customer.

## Pros and cons

### Pros

- Single Responsibility Principle: Decouples classes that invoke operations from classes that perform these operations.
- Open/Closed Principle: New commands can be introduced into the app without breaking existing client code.
- Undo/Redo: Supports implementing undo/redo functionality.
- Deferred Execution: Allows implementing deferred execution of operations.
- Complex Commands: Facilitates assembling a set of simple commands into a complex one.

### Cons

- Complexity: Introduces a whole new layer between senders and receivers, which can complicate the code.

## Applicability

- Transactional Systems: Financial/payment system, e-commerce platforms
- Task Scheduling: Job schedulers, cron jobs, and task queues, batch jobs, data processing pipelines
- User Interfaces: Optimistic UI

## References

- https://refactoring.guru/design-patterns/command


Command is a behavioral design pattern that encapsulates a request as an object. This allows you to parameterize methods with different requests, delay or queue a request’s execution, and support undoable operations. This pattern promotes the decoupling of the sender and receiver of a request, enhancing flexibility and maintainability.

Command pattern


![State pattern](assets/state-pattern_state-en-2x.webp)

> The State Design Pattern is a behavioral design pattern that allows an object to change its behavior when its internal state changes. This pattern is particularly useful for scenarios where an object can exist in multiple states and its behavior varies based on these states.

## Example scenario

Consider a Document class with three states: Draft, Moderation, and Published. The publish method behaves differently in each state:

- Draft: Moves the document to Moderation.
- Moderation: Publishes the document if the current user is an administrator.
- Published: Does nothing.

![Document state change](assets/state-pattern_problem2-en-2x.webp)

### Common implementation issues

```py
class Document is
    field state: string
    // ...
    method publish() is
        switch (state)
            "draft":
                state = "moderation"
                break
            "moderation":
                if (currentUser.role == "admin")
                    state = "published"
                break
            "published":
                // Do nothing.
                break
    // ...
```

- Monstrous Conditionals: As the number of states and transitions increases, the conditional logic becomes complex and difficult to manage.
- Maintenance Difficulty: Changes to the state transitions require updating conditionals in multiple places, increasing the risk of errors
- Scalability Issues: Predicting all possible states and transitions at the design stage is challenging, and the state machine can become bloated over time as new states and behaviors are added.

### Solution using State pattern

The State pattern addresses these issues by encapsulating state-specific behavior into separate state classes. This way, the context class delegates the behavior to the state objects, making the code cleaner and easier to manage.

![Solution](assets/state-pattern_solution-en-2x.webp)

## Concept of State pattern

![Finite-State Machine](assets/state-pattern_problem1-2x.webp)

In the State Design Pattern, the state of an object is represented by a set of state-specific classes. The object, known as the context, delegates state-specific behavior to the current state object. As the state of the context changes, it transitions between different state objects, each of which implements a particular set of behaviors.

### Structure

![Structure](assets/state-pattern_structure-en-2x.webp)

- **Context**: Maintains an instance of a `ConcreteState` subclass that defines the current state.
- **State**: Defines an interface for encapsulating the behavior associated with a particular state of the Context.
- **ConcreteState**: Implements the behavior associated with a state of the Context.

### Advantages

- **Simplifies state transitions**: Encapsulates state-specific behavior and state transitions, making it easier to add new states without modifying existing ones.
- **Enhances readability**: Improves code readability and maintainability by organizing state-specific behavior into separate classes.
- **Promotes open/closed principle**: Facilitates adherence to the Open/Closed Principle, allowing the system to be extended with new states without altering existing code.

### Use cases

The State Design Pattern is particularly beneficial in scenarios such as:

- **Finite state machines**: Implementing state machines where an object can be in one of a limited number of states.
- **User interfaces**: Managing different UI states like enabled, disabled, focused, etc.
- **Game development**: Handling various game states such as running, paused, stopped, etc.


The State Design Pattern is a behavioral design pattern that allows an object to change its behavior when its internal state changes. This pattern is particularly useful for scenarios where an object can exist in multiple states and its behavior varies based on these states.

State pattern


> Radix sort is a non-comparative sorting algorithm that sorts integers by processing individual digits. Unlike comparison-based algorithms (like Quick Sort or Merge Sort), Radix sort groups numbers by their individual digits.

## Key concepts

- **Digit positioning**: Radix sort processes digits from the `least significant digit (LSD)` to the `most significant digit (MSD)`.
- **Stable sorting**: It maintains the relative order of records with equal keys.
- **Counting sort as a subroutine**: Radix sort often uses Counting Sort for sorting digits, ensuring stable sorting at each digit level.

## Steps of Radix sort

- **Determine the maximum number of digits**: Find the maximum number in the array to understand the number of digits.
- **Sorting by each digit**: Use `Counting Sort` to sort based on each digit's place value
  - Initialize Buckets: create an array of buckets for each digit from 0 to the radix minus one (e.g., for decimal numbers, you need 10 buckets).
  - Distribute the Numbers: start with the LSD and move towards the MSD. distribute each number into the corresponding bucket based on the current digit
  - Collect Numbers: collect numbers from the buckets and update the list in the new order
- **Repeat for each digit position**: Continue the process for each digit until all positions are sorted.

![radix sort example](assets/radix-sort.gif)

## Big O notation

If we take

- `n` is the number of elements
- `k` is the number of digits in the largest number

the time complexity for Radix sort will be `O(n×k)` and the space complexity will be `O(n+k)`

## Advantages

- **Efficiency**: Linear time complexity O(n×k) when k is the number of digits.
- **Predictable performance**: Performs consistently regardless of the input data's initial order.

## Disadvantages

- **Limited scope**: Primarily useful for integers or fixed-length strings.
- **Memory usage**: Requires additional memory for the Counting Sort process.


Radix sort is a non-comparative sorting algorithm that sorts integers by processing individual digits. Unlike comparison-based algorithms (like Quick Sort or Merge Sort), Radix sort groups numbers by their individual digits.

Radix sort


### Go JSON parser: number <-> interface

**TLDR**; be careful when using map[string]interface{} to hold json number value, use custom decoder with newDecoder.UseNumber() to decode the json string.

The problem

```go
type payload struct { ID int64 `json:"id"` }
p := payload{ ID: 98470950831393239 }

raw, _ := json.Marshal(p)
fmt.Printf("version1 is %s\n", raw) // {"id":98470950831393239}

var obj map[string]interface{}
json.Unmarshal(raw, &obj) // id will be parsed as float64
interfaceRaw, _ := json.Marshal(obj)
fmt.Printf("version2 is %s\n", interfaceRaw) // {"id":98470950831393230 }
```

Why
The issue caused by default Go uses float64 for interface{} parsing
Ref: https://cs.opensource.google/go/go/+/refs/tags/go1.19.3:src/encoding/json/decode.go;l=844;drc=a11cd6f69aec5c783656601fbc7b493e0d63f605

Solution
To resolve we need custom decoder with UseNumber

```go
var obj map[string]interface{}
decoder := json.NewDecoder(strings.NewReader(string(raw)))
decoder.UseNumber()
decoder.Decode(&obj)
interfaceRaw, _ := json.Marshal(obj)
fmt.Printf("version2 is %s\n", interfaceRaw) // {"id":98470950831393239 }
```


TLDR; be careful when using  map[string]interface{} to hold json number value, use custom decoder with newDecoder.UseNumber() to decode the json string.