Agent Library System

Relevant source files

The following files were used as context for generating this wiki page:

• src/agentLoader.ts
• scripts/postinstall.js
• README.md
• src/server.ts
• src/types.ts
• agents/general-purpose.md

The Agent Library System is a core component of SuperAgent-MCP designed to manage, load, and provide specialized system prompts to various CLI agents (Codex, Gemini, and Continue). It enables the orchestration of complex tasks by leveraging curated expert personas defined as Markdown files with frontmatter.

The system ensures that these specialized agent definitions are available locally on the user's machine, allowing for both the execution of built-in personas and user-driven extensions. By decoupling the agent logic from the execution tools, the system provides a flexible framework for multi-step research, code analysis, and architectural design.
Sources: README.md:1-12, src/agentLoader.ts:1-12

Architecture and Components

The system relies on a standardized file structure and a dedicated loader to manage agent definitions. Agents are stored in a local directory, typically ~/.superagent/agents, to allow for persistence and local customization.

Data Flow for Agent Discovery

The following diagram illustrates how the system discovers and loads agents from the local filesystem to be served via the MCP protocol.

The discovery process begins during installation or server startup, ensuring the local library is synchronized with the package defaults.
Sources: scripts/postinstall.js:10-40, src/agentLoader.ts:81-105

Agent Definition Format

Agents are defined using Markdown files (.md) that include a YAML-like frontmatter block. This block contains metadata used for discovery and categorization.

Field	Type	Description
name	string	Unique identifier for the agent (e.g., python-expert)
description	string	Short summary of the agent's capabilities
category	string	Optional grouping (e.g., engineering, quality)
body	string	The actual system prompt content following the frontmatter

Sources: src/agentLoader.ts:68-88, agents/general-purpose.md:1-8

Core Logic and Implementation

Agent Loading Process

The agentLoader.ts module is responsible for scanning the agents directory and transforming file content into Agent interfaces.

export interface Agent {
  name: string;
  description: string;
  category?: string;
  systemPrompt: string;
}

Sources: src/agentLoader.ts:7-12

The parseAgentFile function uses regular expressions to extract frontmatter and the message body:

1. It identifies the frontmatter block delimited by ---.
2. It matches name:, description:, and category: fields.
3. It treats everything following the second --- as the systemPrompt.
   Sources: src/agentLoader.ts:68-100

Installation and Synchronization

To ensure a consistent experience across different environments (local or via npx), a post-install script and a runtime check manage the synchronization of agent files.

This logic ensures that default agents are provided while protecting any modifications a user has made to their local definitions.
Sources: scripts/postinstall.js:12-45, src/agentLoader.ts:39-66

Integration with MCP Tools

The Agent Library is exposed to MCP clients through the list-agents tool and the agent parameter in execution tools (codex, gemini, continue).

Available Tools and Parameters

The server.ts file dynamically constructs tool definitions based on the loaded agents.

Tool Name	Parameter	Description
list-agents	N/A	Returns a formatted list of all available agent names and descriptions.
codex/gemini	agent	Optional string mapping to an agent name to apply its system prompt.

Sources: src/server.ts:51-85, src/types.ts:5-13

System Prompt Application

When a tool is invoked with an agent parameter, the system:

1. Looks up the agent by name using getAgent(name).
2. Appends the systemPrompt from the library to a META_INSTRUCTION.
3. Sends the combined instruction to the underlying CLI agent.
   Sources: src/agentLoader.ts:114-117, src/codexAgent.ts:128-144

Summary

The Agent Library System provides the foundational expertise for SuperAgent-MCP. By combining a Markdown-based definition format with a robust loading and synchronization strategy, it allows the server to offer a wide array of specialized personas—from backend-architect to security-engineer—while remaining extensible for end-users.
Sources: README.md:15-30, src/server.ts:90-105