Server Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The SuperAgent MCP server is a Node.js application built on the Model Context Protocol (MCP) SDK. Its primary purpose is to act as a bridge between MCP-compatible clients and various Command Line Interface (CLI) agents, specifically Codex, Gemini, and Continue. The server facilitates parallel execution of tasks, manages specialized agent personas, and provides a unified interface for tool discovery and invocation.
Sources: README.md:1-10, src/server.ts:101-104
Core Architecture
The server utilizes a standard MCP architecture, employing StdioServerTransport for communication with clients. It initializes with a set of capabilities focused on "tools," which are dynamically generated based on available system prompts and CLI wrappers.
System Components
The following diagram illustrates the high-level architecture of the SuperAgent server and its interaction with external CLI tools and the local filesystem.
The architecture separates request handling from agent execution, using a specialized loader to manage persona-based system prompts stored locally.
Sources: src/server.ts:251-265, src/agentLoader.ts:10-15, README.md:1-10
Tool Definitions and Discovery
The server exposes four primary tools to MCP clients. These tools are defined dynamically to include information about specialized agents currently available in the system.
| Tool Name | Description | Required Environment |
|---|---|---|
codex | Parallel execution of Codex CLI agent with full system access. | None |
gemini | Parallel execution of Gemini CLI agent in "YOLO" (auto-approve) mode. | None |
continue | Parallel execution of Continue CLI agent in headless mode. | CONTINUE_CONFIG_PATH |
list-agents | Lists all specialized agents and their descriptions. | None |
Sources: src/server.ts:46-77, README.md:21-28
Specialized Agent Loading
Agents are defined as Markdown files with YAML frontmatter. The agentLoader.ts module is responsible for:
- Parsing: Extracting
name,description, andsystemPromptfrom files. - Synchronization: Ensuring the
~/.superagent/agentsdirectory exists and contains default agents during post-installation or startup. - Discovery: Providing the list of agents to the
list-agentstool and the descriptions of other tools.
Sources: src/agentLoader.ts:74-106, scripts/postinstall.js:15-45
Request Handling Flow
When a tool is called, the server processes the request through a standardized execution flow. This involves input validation using Zod schemas, invoking the respective runner, and formatting the results for the client.
Execution Sequence
The following sequence diagram shows the process of invoking a specialized agent through the codex tool.
The server handles multiple tasks concurrently as defined by the concurrency parameter in the request.
Sources: src/server.ts:121-160, src/codexAgent.ts:168-185
CLI Integration and Runners
The server does not implement agent logic directly; instead, it orchestrates external CLI processes.
Codex Integration
The invokeCodex function spawns the codex CLI with specific flags:
--json: For structured event output.--skip-git-repo-check: To allow execution outside of git repositories.--dangerously-bypass-approvals-and-sandbox: To grant the agent full system permissions for automated tasks.
The runner parses the standard output (stdout) line-by-line, as Codex outputs multiple JSON objects representing different event types (e.g., agent_message, assistant_message).
Sources: src/codexAgent.ts:45-55, src/codexAgent.ts:114-128
Gemini Integration
The invokeGemini function utilizes the gemini CLI. It uses the -y or --yolo flag for automatic approval of actions. Unlike Codex, which uses stdin, Gemini accepts the full prompt as a command-line argument and provides a structured JSON response via the --output-format json flag.
Sources: src/geminiAgent.ts:43-58, src/geminiAgent.ts:109-115
Process Management and Lifecycle
The server includes logic for graceful shutdowns and environment preparation.
- Signal Handlers: The server listens for termination signals to ensure child processes are cleaned up.
- Post-install Setup: A
postinstall.jsscript initializes the local agent library by copying bundled Markdown files from the package to the user's home directory (~/.superagent/agents). - Input Validation: All tool inputs are strictly validated using Zod schemas (
CodexInvokeSchema,GeminiInvokeSchema, etc.) before being passed to runners.
Sources: src/server.ts:252-258, scripts/postinstall.js:15-45, package.json:11-16
Summary
The SuperAgent Server implementation provides a robust, schema-driven bridge for executing CLI-based agents through the Model Context Protocol. By delegating actual execution to external binaries (Codex, Gemini) and managing specialized personas through a local Markdown-based library, it offers a flexible and extensible platform for multi-agent orchestration.