Data Types & SDK

Relevant source files

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

• src/types.ts
• src/server.ts
• src/agentLoader.ts
• src/codexAgent.ts
• README.md
• package.json

The SuperAgent MCP server serves as a bridge between Model Context Protocol (MCP) clients and various CLI-based agents like Codex, Gemini, and Continue. The system relies on a structured set of data types and schemas to manage parallel execution, tool discovery, and agent lifecycle management.

At its core, the project utilizes the @modelcontextprotocol/sdk to expose internal logic as standardized tools. This allows MCP-compatible clients to invoke complex CLI tasks through a unified interface.

Sources: README.md:3-8, src/server.ts:1-15

Core Data Structures

Agent Definition

The system manages specialized agents through an Agent interface. These agents are defined in Markdown files with frontmatter and are loaded into the server's runtime to provide specific behavioral contexts.

Field	Type	Description
name	string	Unique identifier for the agent (e.g., "technical-writer").
description	string	Human-readable explanation of the agent's purpose.
category	string (optional)	Functional grouping (e.g., "communication", "engineering").
systemPrompt	string	The core behavioral instructions (body of the Markdown file).

Sources: src/agentLoader.ts:7-12, src/agentLoader.ts:77-101

Tool Invocation Schemas

SuperAgent uses Zod schemas to validate requests for its primary tools. These schemas define the parameters required to execute CLI tasks across different engines.

Server & SDK Integration

The server initializes using the Server class from the MCP SDK, defining its identity and capabilities. It leverages StdioServerTransport for communication.

Tool Definitions

The server dynamically generates tool definitions, incorporating the list of available specialized agents into the tool descriptions.

Tool Name	Input Schema	Purpose
codex	CodexInvokeSchema	Runs Codex CLI with parallel execution and full system access.
gemini	GeminiInvokeSchema	Runs Gemini CLI in "YOLO" mode (auto-approvals).
continue	ContinueInvokeSchema	Runs Continue CLI in headless mode.
list-agents	Empty Object	Returns a list of all registered specialized agents.

Sources: src/server.ts:40-75, src/server.ts:220-230

Execution Flow

When a tool is called, the server parses the arguments, invokes the corresponding runner, and formats the result into a TextContent array for the MCP client.

CLI Interaction SDK

The project implements an internal "SDK" layer to handle the specifics of spawning CLI processes and parsing their output, particularly for Codex.

Codex Invocation Data

The invokeCodex function manages individual process lifecycles and parses streaming JSON events into a coherent response.

Type	Definition
CodexInvocationOptions	Configuration for a single run including prompt, timeout, and working directory.
CodexInvocationResponse	Result containing exit code, duration, stdout/stderr, and the parsed assistantReply.
CodexInvocationEvent	A dictionary representing a single line of JSON output from the CLI.

Sources: src/codexAgent.ts:5-30

Response Parsing Logic

The system extracts the assistant's message from the CLI's JSON stream by searching for specific message types (agent_message or assistant_message) within the event list.

// Example of the response extraction logic
function parseAssistantReply(events: CodexInvocationEvent[]): string {
  const replies: string[] = [];
  for (const event of events) {
    if (event["type"] === "message") {
      const data = event["data"] as Record<string, unknown>;
      if (data?.["role"] === "assistant") {
        // Extract text chunks...
      }
    }
  }
  return replies.join("\n").trim();
}

Sources: src/codexAgent.ts:86-118

Summary

The Data Types & SDK layer of SuperAgent MCP provides the necessary abstractions to turn disparate CLI tools into a unified, programmable interface. By combining Zod-based validation, Markdown-based agent definitions, and the Model Context Protocol SDK, it enables complex, multi-agent workflows within any MCP-supported environment.