@swarmify/agents-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Muqsit Nawaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @swarmify/agents-mcp
+
+True multi-agent coding in your IDE. Spawn Claude, Codex, Gemini, and Cursor agents from a single MCP server.
+
+This [Model Context Protocol](https://modelcontextprotocol.io/) server gives your AI coding agent the ability to spawn, orchestrate, and manage other AI agents. CLI-first, token-optimized, and works with any MCP-compatible host.
+
+## Installation
+
+```bash
+# Claude Code
+claude mcp add swarmify-agents -- npx -y @swarmify/agents-mcp
+
+# Gemini CLI
+gemini mcp add swarmify-agents -- npx -y @swarmify/agents-mcp
+
+# OpenCode (interactive)
+opencode mcp add
+# Name: swarmify-agents
+# Type: Local
+# Command: npx -y @swarmify/agents-mcp
+```
+
+The server auto-discovers which agent CLIs you have installed and only exposes those in the `spawn` tool.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `spawn` | Start an agent on a task. Returns immediately with agent ID. |
+| `status` | Get agent progress: files changed, commands run, last messages. |
+| `stop` | Stop one agent or all agents in a task. |
+| `tasks` | List all tasks with their agents and activity. |
+
+### spawn
+
+```
+spawn(task_name, agent_type, prompt, mode?, cwd?, effort?)
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `task_name` | Yes | Groups related agents (e.g., "auth-feature") |
+| `agent_type` | Yes | `claude`, `codex`, `gemini`, or `cursor` |
+| `prompt` | Yes | The task for the agent |
+| `mode` | No | `plan` (read-only, default) or `edit` (can write files) |
+| `cwd` | No | Working directory for the agent |
+| `effort` | No | `medium` (default) or `high` for max-capability models |
+
+### status
+
+```
+status(task_name, filter?)
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `task_name` | Yes | Task to check |
+| `filter` | No | `running` (default), `completed`, `failed`, `stopped`, or `all` |
+
+Returns files created/modified/read/deleted, bash commands executed, and last messages.
+
+### stop
+
+```
+stop(task_name, agent_id?)
+```
+
+Stop all agents in a task, or a specific agent by ID.
+
+### tasks
+
+```
+tasks(limit?)
+```
+
+List all tasks sorted by most recent activity.
+
+## Token Optimization
+
+This server is designed to minimize token usage for the calling agent:
+
+| Optimization | Benefit |
+|--------------|---------|
+| Status defaults to `filter='running'` | Only shows active agents, not completed history |
+| Bash commands truncated to 120 chars | Heredocs collapsed to `cat <<EOF > path` |
+| Last 5 messages only | Not full conversation history |
+| File operations deduplicated | Sets of created/modified/read/deleted paths |
+| Spawn returns immediately | No blocking, poll with status later |
+
+## Supported Agents
+
+The server auto-discovers installed CLIs at startup:
+
+| Agent | CLI | Best For |
+|-------|-----|----------|
+| Claude | `claude` | Maximum capability, research, exploration |
+| Codex | `codex` | Fast, cheap. Self-contained features |
+| Gemini | `gemini` | Complex multi-system features, architectural changes |
+| Cursor | `cursor-agent` | Debugging, bug fixes, tracing through codebases |
+
+Install the CLIs you want to use. The server reports available and missing agents on startup.
+
+## Modes
+
+| Mode | File Access | Use Case |
+|------|-------------|----------|
+| `plan` | Read-only | Research, exploration, code review |
+| `edit` | Read + Write | Implementation, refactoring, fixes |
+
+Default is `plan` for safety. Pass `mode='edit'` when agents need to modify files.
+
+Data & config are stored under `~/.swarmify` (with a legacy fallback to `~/.agent-swarm`; if neither is writable, it falls back to your temp dir).
+
+Requires Node.js >= 18.17 (ESM, fs.rm, etc.).
+
+## Effort Levels
+
+| Level | Models Used |
+|-------|-------------|
+| `medium` | Balanced models (default) |
+| `high` | Max-capability models per agent |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_SWARM_DEFAULT_MODE` | Set default mode (`plan` or `edit`) |
+
+## License
+
+MIT

package/dist/agents.d.ts

@@ -0,0 +1,85 @@
+import { AgentType } from './parsers.js';
+export declare enum AgentStatus {
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    STOPPED = "stopped"
+}
+export type { AgentType } from './parsers.js';
+export declare const AGENT_COMMANDS: Record<AgentType, string[]>;
+export type EffortLevel = 'medium' | 'high';
+export declare const EFFORT_MODEL_MAP: Record<EffortLevel, Record<AgentType, string>>;
+declare const VALID_MODES: readonly ["plan", "edit"];
+type Mode = typeof VALID_MODES[number];
+export declare function resolveMode(requestedMode: string | null | undefined, defaultMode?: Mode): Mode;
+export declare function checkCliAvailable(agentType: AgentType): [boolean, string | null];
+export declare function checkAllClis(): Record<string, {
+    installed: boolean;
+    path: string | null;
+    error: string | null;
+}>;
+export declare function getAgentsDir(): Promise<string>;
+export declare class AgentProcess {
+    agentId: string;
+    taskName: string;
+    agentType: AgentType;
+    prompt: string;
+    cwd: string | null;
+    mode: Mode;
+    pid: number | null;
+    status: AgentStatus;
+    startedAt: Date;
+    completedAt: Date | null;
+    private eventsCache;
+    private lastReadPos;
+    private baseDir;
+    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null);
+    get isEditMode(): boolean;
+    getAgentDir(): Promise<string>;
+    getStdoutPath(): Promise<string>;
+    getMetaPath(): Promise<string>;
+    toDict(): any;
+    duration(): string | null;
+    get events(): any[];
+    /**
+     * Return the latest timestamp we have seen in the agent's events.
+     * Falls back to null when none are available.
+     */
+    private getLatestEventTime;
+    readNewEvents(): Promise<void>;
+    saveMeta(): Promise<void>;
+    static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
+    isProcessAlive(): boolean;
+    updateStatusFromProcess(): Promise<void>;
+    private reapProcess;
+}
+export declare class AgentManager {
+    private agents;
+    private maxAgents;
+    private maxConcurrent;
+    private agentsDir;
+    private filterByCwd;
+    private cleanupAgeDays;
+    private defaultMode;
+    private constructorAgentsDir;
+    constructor(maxAgents?: number, maxConcurrent?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number);
+    private initialize;
+    getDefaultMode(): Mode;
+    private loadExistingAgents;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel): Promise<AgentProcess>;
+    private buildCommand;
+    private applyEditMode;
+    get(agentId: string): Promise<AgentProcess | null>;
+    listAll(): Promise<AgentProcess[]>;
+    listRunning(): Promise<AgentProcess[]>;
+    listCompleted(): Promise<AgentProcess[]>;
+    listByTask(taskName: string): Promise<AgentProcess[]>;
+    stopByTask(taskName: string): Promise<{
+        stopped: string[];
+        alreadyStopped: string[];
+    }>;
+    stop(agentId: string): Promise<boolean>;
+    private cleanupPartialAgent;
+    private cleanupOldAgents;
+}
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}