Local Development Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Local Development Workflow for SuperAgent-MCP centers on building and running a Model Context Protocol (MCP) server that orchestrates external CLI agents like Codex, Gemini, and Continue. The project is a TypeScript-based Node.js application that leverages the @modelcontextprotocol/sdk to expose agentic capabilities as tools to compatible clients.
Developers working on this project interact with a system that manages specialized agent definitions stored as Markdown files in the user's home directory. The workflow includes building the TypeScript source, managing local agent prompts, and configuring environment variables to enable third-party integrations.
Sources: README.md:3-10, package.json:1-15
Build and Environment Setup
Local development requires Node.js 18 or newer. The project uses standard npm scripts to manage the lifecycle of the TypeScript server, including compilation and execution of the compiled JavaScript in the dist/ directory.
Core Development Commands
| Command | Action | Description |
|---|---|---|
npm install | Installation | Installs dependencies and runs the post-install setup script. |
npm run build | Compilation | Compiles TypeScript source files into the dist/ folder using tsc. |
npm start | Execution | Runs the compiled server from dist/server.js. |
npm run dev | Development | Directly runs the TypeScript entrypoint using ts-node. |
Sources: package.json:11-16, README.md:46-52
Environment Configuration
Certain tools within the local development environment require specific environment variables to function correctly. Specifically, the continue tool depends on the CONTINUE_CONFIG_PATH to locate its configuration file.
export CONTINUE_CONFIG_PATH="/path/to/.continue/config.yaml"
Sources: README.md:41-43, src/server.ts:65-66
Agent Management Workflow
A critical part of the development workflow is the management of specialized agent prompts. These are stored as Markdown files with frontmatter and are synchronized between the package source and the user's local environment.
Initialization and Synchronization
During npm install or when the server starts, a synchronization process ensures that default agents are available in the local developer environment.
The system prioritizes local customizations by checking if a file already exists in ~/.superagent/agents before attempting to copy it from the package source.
Sources: scripts/postinstall.js:15-38, src/agentLoader.ts:44-53
Agent File Structure
Developers can extend the system by adding new .md files to the ~/.superagent/agents directory. Each file must follow a specific format:
---
name: agent-name
description: A short description of the agent's purpose
category: specialized
---
# System Prompt
This is the system instruction that will be passed to the underlying CLI tool.
Sources: src/agentLoader.ts:71-96, README.md:34-37
Development Lifecycle of Tool Invocations
The server operates by receiving JSON-RPC requests via standard I/O (stdio). When a developer or client invokes a tool like codex, the server processes the request, loads any requested agent prompts, and spawns the corresponding CLI process.
Execution Flow
Tool Discovery
Developers use the list-agents tool to verify which agents are currently loaded and available for use in the codex, gemini, or continue tools. This tool reads the ~/.superagent/agents directory at runtime.
Sources: src/server.ts:88-103, src/agentLoader.ts:115-127
Internal Architecture Summary
| Component | Responsibility | Relevant Files |
|---|---|---|
| Server Entry | Manages MCP lifecycle and tool registration via Stdio. | src/server.ts |
| Agent Loader | Parses and loads Markdown agent definitions with frontmatter. | src/agentLoader.ts |
| Runner | Handles parallel execution and batching of agent tasks. | src/server.ts, src/runner.js |
| CLI Invoker | Manages the spawn process for Codex/Gemini and handles stdin/stdout. | src/codexAgent.ts |
| Post-install | Ensures local filesystem setup for agent prompts. | scripts/postinstall.js |
Sources: src/server.ts:245-257, src/agentLoader.ts:9-12, src/codexAgent.ts:172-180
The local development workflow allows for rapid iteration by combining TypeScript's type safety with the flexibility of Markdown-based agent prompting, all managed through a standard MCP interface.