Iron Manus MCP (J.A.R.V.I.S.)

Claude-code MCP server that spawns agents as tools - An agent orchestration system that lets Claude autonomously break down complex workflows by structured phases and delegate to subagents with native context management.

Fit over 300k+ tokens in one session

📹 GIF Demo

🎥 Video Tutorials

Quick Demo	Demo + Explanations

Watch the quick demo	Watch the detailed walkthrough

What It Does

Iron Manus MCP is a comprehensive FSM-driven orchestration system that manages complex workflows through structured phases. It features a complete tool registry with JARVIS FSM controller and intelligent API selection from 65+ endpoints.

8-Phase Workflow: INIT → QUERY → ENHANCE → KNOWLEDGE → PLAN → EXECUTE → VERIFY → DONE

Key Features:

🔄 8-Phase Orchestration Loop - Structured workflow orchestration with complete FSM states
🧠 Optimized Context Management - Subagent delegation enables 300k+ token conversations
🛠️ Modular Tool Registry - 8+ specialized tools with extensible architecture
📡 65+ API Registry - Intelligent API discovery and selection system
🔒 SSRF Protection - Enterprise-grade security with allowlist validation
✅ 323/323 Tests Passing - Comprehensive test coverage with Vitest (100% success rate)
📦 ES Modules - Modern JavaScript with TypeScript 5.0 support

Quick Start

📦 Docker Images: v0.2.3 (stable, published)
📄 Source Code: v0.2.4 (latest, with comprehensive JSDoc documentation)

Option 1: Docker (Recommended - v0.2.3)

Docker Hub:

# Pull and run from Docker Hub (v0.2.3 - stable)
docker pull dnnyngyen/iron-manus-mcp:0.2.3
docker run -d --name iron-manus-mcp dnnyngyen/iron-manus-mcp:0.2.3

# Alternative: Use latest tag
docker pull dnnyngyen/iron-manus-mcp:latest
docker run -d --name iron-manus-mcp dnnyngyen/iron-manus-mcp:latest

# Or using docker-compose
curl -O https://raw.githubusercontent.com/dnnyngyen/iron-manus-mcp/main/docker-compose.yml
docker-compose up -d

GitHub Container Registry:

# Pull and run from GitHub Container Registry (v0.2.3 - stable)
docker pull ghcr.io/dnnyngyen/iron-manus-mcp:0.2.3
docker run -d --name iron-manus-mcp ghcr.io/dnnyngyen/iron-manus-mcp:0.2.3

# Alternative: Use latest tag
docker pull ghcr.io/dnnyngyen/iron-manus-mcp:latest
docker run -d --name iron-manus-mcp ghcr.io/dnnyngyen/iron-manus-mcp:latest

Option 2: From Source (v0.2.4 - Latest with JSDoc)

Quick Setup (Cross-Platform):

# Clone and install (v0.2.4 - includes comprehensive JSDoc documentation)
git clone https://github.com/dnnyngyen/iron-manus-mcp
cd iron-manus-mcp

# Automated cross-platform installation
npm run setup

Manual Installation:

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests (optional - 323 tests)
npm test

# Start server
npm start

📖 Platform-Specific Instructions: See docs/CROSS_PLATFORM_SETUP.md for detailed Windows, macOS, and Linux setup guides.

If git clone fails with network errors:

# Try with increased buffer and timeout
git clone --depth 1 https://github.com/dnnyngyen/iron-manus-mcp
# OR download as ZIP
curl -L https://github.com/dnnyngyen/iron-manus-mcp/archive/main.zip -o iron-manus-mcp.zip
unzip iron-manus-mcp.zip
cd iron-manus-mcp-main

If npm install hangs or fails:

Unix/Linux/macOS:

# Clean and retry
rm -rf node_modules package-lock.json
npm cache clean --force
npm install --no-optional

# If it still fails, install core dependencies first:
npm install @modelcontextprotocol/sdk@^1.13.2 typescript@^5.0.0
npm run build

Windows (PowerShell):

# Clean and retry
Remove-Item -Recurse -Force node_modules, package-lock.json -ErrorAction SilentlyContinue
npm cache clean --force
npm install --no-optional

# If it still fails, install core dependencies first:
npm install @modelcontextprotocol/sdk@^1.13.2 typescript@^5.0.0
npm run build

Windows (Command Prompt):

# Clean and retry
rmdir /s /q node_modules 2>nul
del package-lock.json 2>nul
npm cache clean --force
npm install --no-optional

# If it still fails, install core dependencies first:
npm install @modelcontextprotocol/sdk@^1.13.2 typescript@^5.0.0
npm run build

⚠️ Legacy File Prevention

This project uses knowledge graph state management. If you see files like iron_manus_*.json, immediately:

Unix/Linux/macOS:

Stop the server: pkill -f iron-manus
Remove files: rm -f iron_manus_*.json
Clean rebuild: rm -rf dist/ && npm run build

Windows (PowerShell):

Stop the server: Get-Process -Name "*iron-manus*" | Stop-Process -Force
Remove files: Remove-Item iron_manus_*.json -Force -ErrorAction SilentlyContinue
Clean rebuild: Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue; npm run build

Windows (Command Prompt):

Stop the server: taskkill /f /im node.exe /fi "WINDOWTITLE eq iron-manus*"
Remove files: del iron_manus_*.json 2>nul
Clean rebuild: rmdir /s /q dist 2>nul && npm run build

See LEGACY_PREVENTION.md for details.

For MCP Integration: Add to your MCP client configuration or register with Claude Code:

# Register with Claude Code (adjust path as needed)
claude mcp add iron-manus-mcp node dist/index.js

# Or add to MCP client settings.json:
{
  "mcpServers": {
    "iron-manus-mcp": {
      "command": "node",
      "args": ["path/to/iron-manus-mcp/dist/index.js"]
    }
  }
}

For Claude Code Hooks (Optional):

Unix/Linux/macOS:

# Copy example hooks configuration
cp .claude/hooks-example.json .claude/hooks.json

# Requires Python 3.7+ for validation scripts
python3 --version

Windows (PowerShell):

# Copy example hooks configuration
Copy-Item .claude\hooks-example.json .claude\hooks.json

# Requires Python 3.7+ for validation scripts
python --version

Windows (Command Prompt):

# Copy example hooks configuration
copy .claude\hooks-example.json .claude\hooks.json

# Requires Python 3.7+ for validation scripts
python --version

Docker Usage

Docker Compose (Recommended)

The easiest way to run Iron Manus MCP is using Docker Compose:

# docker-compose.yml
services:
  iron-manus-mcp:
    image: dnnyngyen/iron-manus-mcp:0.2.3  # or :latest
    container_name: iron-manus-mcp
    restart: unless-stopped
    stdin_open: true
    tty: true
    environment:
      - KNOWLEDGE_MAX_CONCURRENCY=2
      - KNOWLEDGE_TIMEOUT_MS=4000
      - ALLOWED_HOSTS=api.github.com,httpbin.org,api.openai.com
      - ENABLE_SSRF_PROTECTION=true

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f iron-manus-mcp

# Stop the service
docker-compose down

Docker Commands

# Pull latest stable version (v0.2.3)
docker pull dnnyngyen/iron-manus-mcp:0.2.3

# Run with custom environment variables
docker run -d \
  --name iron-manus-mcp \
  -e KNOWLEDGE_MAX_CONCURRENCY=3 \
  -e ALLOWED_HOSTS="api.github.com,httpbin.org" \
  dnnyngyen/iron-manus-mcp:0.2.3

# View container logs
docker logs iron-manus-mcp

# Stop and remove container
docker stop iron-manus-mcp && docker rm iron-manus-mcp

Available Tags

Docker Registry Tags:

0.2.3 - Current stable published version (recommended for production)
latest - Points to v0.2.3 stable release
stable - Alias for v0.2.3

Available Registries:

Docker Hub: dnnyngyen/iron-manus-mcp:0.2.3
GitHub Container Registry: ghcr.io/dnnyngyen/iron-manus-mcp:0.2.3

Note: Source code v0.2.4 includes comprehensive JSDoc documentation improvements. Docker images will be updated to v0.2.4 in the next release.

Example Usage

Input:

await mcp.callTool({
  name: 'JARVIS',
  args: {
    session_id: 'demo',
    initial_objective: 'Build a TypeScript API with tests'
  }
});

8-Phase Flow:

INIT - Initialize session and establish context
QUERY - Analyze request and detect role
ENHANCE - Add missing requirements and context
KNOWLEDGE - Auto-discover relevant APIs and patterns
PLAN - Create structured tasks with meta-prompts
EXECUTE - Process tasks with specialized tools
VERIFY - Validate completion and quality
DONE - Complete session and cleanup

Available Tools

JARVIS - Main FSM controller (8-phase orchestration)
APISearch - Intelligent API discovery from 65+ endpoint registry
MultiAPIFetch - Parallel HTTP requests with SSRF protection
IronManusStateGraph - Project-scoped FSM state management
APIValidator - Response validation and confidence scoring

Development

Prerequisites:

Node.js 18+ (tested with 18.x, 20.x, 22.x)
npm 8+
TypeScript 5.0+
Python 3.7+ (for optional Claude Code hooks)
Git (for source installation)

Available Scripts:

npm run build        # TypeScript compilation
npm test            # Run full test suite (323 tests)
npm run test:nocov   # Run tests without coverage
npm run lint        # ESLint checking (with enhanced rules)
npm run format      # Prettier formatting
npm start          # Start compiled server
npm run dev         # Fast incremental compilation + watch mode
npm run dev:simple  # Simple dev script (fallback)
npm run check       # Run lint + format + tests in parallel
npm run check:fix   # Auto-fix lint/format issues + run tests

Configuration: Environment variables with enhanced validation:

KNOWLEDGE_MAX_CONCURRENCY=2          # API concurrency limit (1-10)
KNOWLEDGE_TIMEOUT_MS=4000            # Request timeout (1000-30000ms)
ALLOWED_HOSTS="api.github.com,httpbin.org"  # SSRF whitelist
ENABLE_SSRF_PROTECTION=true          # Security toggle (required in production)
MIN_COMPLETION_PERCENT=70            # Quality threshold (50-100)
USER_AGENT="Iron-Manus-MCP/0.2.4"    # Service identification

Enhanced Features (v0.2.4+):

✅ Zod Schema Validation - Type-safe configuration with detailed error messages
⚡ Optimized Dev Experience - Incremental TypeScript compilation with parallel tools
🔧 Enhanced ESLint Rules - Strict type checking and code quality enforcement
🚀 Parallel Script Execution - Run lint, format, and tests concurrently

Testing

Comprehensive test suite with 323 tests using Vitest:

# Run all tests
npm test

# Run tests without coverage
npm run test:nocov

# Run specific test types
npm run test:unit
npm run test:integration
npm run test:e2e

Test Coverage:

Configuration management
SSRF protection and security
FSM state transitions
Tool integrations
API registry functionality
Server initialization and MCP compliance

Security

Enhanced Security with Claude Code Hooks Integration

Iron Manus MCP now features comprehensive security validation through Claude Code Hooks integration, providing deterministic security enforcement alongside the cognitive FSM layer.

Built-in Security Features:

Blocks private/localhost IPs (192.168.x.x, 127.x.x.x, etc.)
Validates URL schemes (HTTP/HTTPS only)
Enforces allowlist when configured
Request timeout and size limits
Rate limiting per API endpoint

Claude Code Hooks Security Enhancements:

Command Validation: PreToolUse hooks block dangerous bash commands (rm -rf, etc.)
Enhanced SSRF Protection: Additional URL validation with allowlist enforcement
Code Quality Gates: Output validation prevents security issues in generated code
Session Monitoring: Comprehensive tracking of FSM progression and security events

See .claude/HOOKS_INTEGRATION.md for complete hook configuration and security implementation details.

Architecture

Core Components:

FSM Engine - 8-phase state machine orchestration
Tool Registry - Modular tool architecture with dependency injection
API Registry - 65+ APIs with role-based selection
Security Layer - SSRF guard with comprehensive validation
Type System - Full TypeScript interfaces and schemas

License

MIT - See LICENSE file for details.

Version History

v0.2.4 - (Source) Comprehensive JSDoc documentation, professional standards
v0.2.3 - (Docker) Published Docker images with clean configuration
v0.2.2 - Stable release with comprehensive test coverage and build improvements
v0.2.1 - Claude Code Hooks integration with enhanced security validation
v0.2.0 - Complete refactor with Jest→Vitest migration, repository flattening, 8-phase FSM
v0.1.x - Initial release with 6-phase workflow

Current Status: Docker images (v0.2.3) provide stable functionality, while source code (v0.2.4) includes the latest documentation improvements.

Built for modern AI orchestration - Structured workflows meet intelligent automation.

Server	Summary	Actions
Claude Desktop MCP	A Model Context Protocol (MCP) server that enables Claude Code to communicate with Claude Desktop. T...	View
Qonto	MCP Server for the Qonto API.	View
AnkiConnect	A Model Context Protocol (MCP) server that provides seamless integration with Anki through the AnkiC...	View
Document Evaluation MCP Server	No documentation available.	View
MCP Sync	複数のAIコーディングツール間でMCP（Model Context Protocol）設定を同期するためのCLIツールです。	View
MCP Desktop Automation	A Model Context Protocol server that provides desktop automation capabilities using RobotJS and scre...	View

Iron Manus MCP

Iron Manus MCP

Iron Manus MCP (J.A.R.V.I.S.)

Fit over 300k+ tokens in one session

📹 GIF Demo

🎥 Video Tutorials

What It Does

Quick Start

Option 1: Docker (Recommended - v0.2.3)

Option 2: From Source (v0.2.4 - Latest with JSDoc)

⚠️ Legacy File Prevention

Docker Usage

Docker Compose (Recommended)

Docker Commands

Available Tags

Example Usage

Available Tools

Development

Testing

Security

Enhanced Security with Claude Code Hooks Integration

Architecture

License

Version History

Related in Productivity - Secure MCP Servers

Google flagged your site unsafe?