mcp-agent-foundry 1.3.0 → 1.3.1

package/README.md

@@ -5,7 +5,7 @@
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js >=20](https://img.shields.io/badge/Node.js-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 [![npm version](https://img.shields.io/npm/v/mcp-agent-foundry.svg)](https://www.npmjs.com/package/mcp-agent-foundry)
-[![Tests](https://img.shields.io/badge/tests-131%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests/)
 
 Agent Foundry extends Claude Code with multi-provider AI orchestration and git worktree isolation. Each coding agent receives its own isolated worktree - a separate checkout on a dedicated branch - enabling true parallel development without file conflicts. Get second opinions from external AI models without leaving Claude Code.
 
@@ -13,6 +13,8 @@ Agent Foundry extends Claude Code with multi-provider AI orchestration and git w
 
 ## Features
 
+- **Zero-Config Setup** - Auto-registers with Claude Code on npm install
+- **13+ AI Providers** - From budget (DeepSeek, Groq) to premium (OpenAI, Anthropic)
 - **Multi-Provider AI Orchestration** - Route tasks to Anthropic, OpenAI, Google Gemini, DeepSeek, Z.AI (GLM-4), Kimi, or local Ollama models
 - **Git Worktree Isolation** - Each coding agent works in an isolated directory on its own branch
 - **Pipeline Execution** - Multi-step DAG workflows with dependency ordering and parallel execution
@@ -33,7 +35,12 @@ Agent Foundry extends Claude Code with multi-provider AI orchestration and git w
 npm install -g mcp-agent-foundry
 ```
 
-### Setup
+That's it! Agent Foundry automatically registers with Claude Code during installation.
+Restart Claude Code to activate.
+
+To verify: Run `/mcp` in Claude Code - you should see `agent-foundry · ✓ connected`
+
+### Initial Setup
 
 ```bash
 agent-foundry setup
@@ -45,34 +52,6 @@ This interactive wizard will:
 3. Set up agent roles
 4. Create your configuration file
 
-### Connect to Claude Code
-
-Add to your Claude Code configuration (`~/.claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "agent-foundry": {
-      "command": "agent-foundry",
-      "args": ["start"]
-    }
-  }
-}
-```
-
-Or specify the full path:
-
-```json
-{
-  "mcpServers": {
-    "agent-foundry": {
-      "command": "node",
-      "args": ["/path/to/agent-foundry/dist/index.js"]
-    }
-  }
-}
-```
-
 ---
 
 ## How It Works
@@ -125,6 +104,58 @@ Or specify the full path:
 
 ---
 
+## Intelligent Failover System
+
+Agent Foundry includes automatic provider failover with health tracking:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Request to Role                          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ Primary Provider │
+                    │   (e.g. DeepSeek)│
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+         ✓ Success                    ✗ Error (429, 500, etc.)
+              │                             │
+              ▼                             ▼
+         Return Result            ┌─────────────────┐
+                                  │ Health Tracker   │
+                                  │ marks unhealthy  │
+                                  └────────┬────────┘
+                                           │
+                                           ▼
+                                  ┌─────────────────┐
+                                  │ Circuit Breaker │
+                                  │ checks state    │
+                                  └────────┬────────┘
+                                           │
+                                           ▼
+                                  ┌─────────────────┐
+                                  │ Fallback Chain  │
+                                  │ (OpenAI → Anthropic)│
+                                  └────────┬────────┘
+                                           │
+                                           ▼
+                                    Next Provider
+```
+
+### Key Features
+
+- **Automatic Retry** - Exponential backoff on transient errors
+- **Health Tracking** - Monitors provider success/failure rates
+- **Cooldown Periods** - Unhealthy providers are temporarily skipped
+- **Circuit Breakers** - Prevents cascading failures
+- **Cost-Aware Routing** - Optionally prefer cheaper providers
+- **Configurable Error Codes** - Define which errors trigger failover
+
+---
+
 ## MCP Tools
 
 | Tool | Description |
@@ -162,19 +193,24 @@ providers:
   openai:
     api_key: ${OPENAI_API_KEY}
     default_model: gpt-4o
-  deepseek:
-    api_key: ${DEEPSEEK_API_KEY}
-    base_url: https://api.deepseek.com
-    default_model: deepseek-reasoner
   anthropic:
     api_key: ${ANTHROPIC_API_KEY}
     default_model: claude-sonnet-4-20250514
+  deepseek:
+    api_key: ${DEEPSEEK_API_KEY}
+    default_model: deepseek-reasoner
   google:
     api_key: ${GOOGLE_API_KEY}
     default_model: gemini-2.5-pro
+  groq:
+    api_key: ${GROQ_API_KEY}
+    default_model: llama-3.3-70b-versatile
+  openrouter:
+    api_key: ${OPENROUTER_API_KEY}
+    default_model: anthropic/claude-3.5-sonnet
   ollama:
     base_url: http://localhost:11434
-    default_model: llama3.2
+    default_model: llama3.3:70b
 
 roles:
   coder:
@@ -247,15 +283,28 @@ worktrees:
 
 ### Environment Variables
 
-Set your API keys as environment variables:
-
 ```bash
-export OPENAI_API_KEY="sk-..."
+# Premium Providers
 export ANTHROPIC_API_KEY="sk-ant-..."
-export DEEPSEEK_API_KEY="sk-..."
+export OPENAI_API_KEY="sk-..."
 export GOOGLE_API_KEY="..."
-export ZAI_API_KEY="..."        # Z.AI GLM-4
-export KIMI_API_KEY="..."       # Moonshot Kimi
+
+# Budget-Friendly Providers
+export DEEPSEEK_API_KEY="sk-..."
+export ZAI_API_KEY="..."
+export KIMI_API_KEY="..."
+export KIMI_CODE_API_KEY="..."     # Kimi Code subscription
+
+# Router/Aggregator
+export OPENROUTER_API_KEY="sk-or-..."
+
+# Fast Inference
+export GROQ_API_KEY="gsk_..."
+export TOGETHER_API_KEY="..."
+export FIREWORKS_API_KEY="..."
+
+# Web Search
+export PERPLEXITY_API_KEY="pplx-..."
 ```
 
 ---
@@ -310,15 +359,23 @@ agent-foundry help          # Show help
 
 ## Supported Providers
 
-| Provider | Models | Access Mode | Cost |
-|----------|--------|-------------|------|
-| **Anthropic** | Claude Sonnet 4, Claude Opus 4 | API | $$$ |
-| **OpenAI** | GPT-4o, GPT-4 Turbo, o1, o1-mini | API | $$$ |
-| **Google Gemini** | Gemini 2.5 Pro, Gemini 2.5 Flash | API | $$ |
-| **DeepSeek** | DeepSeek R1, DeepSeek Chat | API | $ (cheapest) |
-| **Z.AI** | GLM-4, GLM-4.7 | API | $ |
-| **Kimi** | Moonshot v1 | API | $ |
-| **Ollama** | Llama 3.2, Mistral, CodeLlama, etc. | Local | Free |
+| Provider | Models | API Key Env Var | Cost |
+|----------|--------|-----------------|------|
+| **Anthropic** | Claude Opus 4, Claude Sonnet 4 | `ANTHROPIC_API_KEY` | $$$ |
+| **OpenAI** | GPT-4o, GPT-4 Turbo, o1, o1-mini, o3-mini | `OPENAI_API_KEY` | $$$ |
+| **Google Gemini** | Gemini 2.5 Pro, Gemini 2.5 Flash | `GOOGLE_API_KEY` | $$ |
+| **DeepSeek** | DeepSeek R1, DeepSeek Chat, DeepSeek Coder | `DEEPSEEK_API_KEY` | $ |
+| **OpenRouter** | Access 100+ models via single API | `OPENROUTER_API_KEY` | Varies |
+| **Perplexity** | pplx-70b-online, pplx-7b-online (web search) | `PERPLEXITY_API_KEY` | $$ |
+| **Groq** | Llama 3.3 70B, Mixtral (ultra-fast inference) | `GROQ_API_KEY` | $ |
+| **Together AI** | Llama, Mistral, CodeLlama, Qwen | `TOGETHER_API_KEY` | $ |
+| **Fireworks AI** | Llama, Mixtral (optimized inference) | `FIREWORKS_API_KEY` | $ |
+| **Z.AI** | GLM-4, GLM-4.7 | `ZAI_API_KEY` | $ |
+| **Kimi (Moonshot)** | moonshot-v1-128k | `KIMI_API_KEY` | $ |
+| **Kimi Code** | Kimi coding assistant (subscription) | `KIMI_CODE_API_KEY` | Subscription |
+| **Ollama** | Llama 3.3, Mistral, CodeLlama, Qwen, etc. | N/A (local) | Free |
+
+**Cost Legend**: $ = Budget, $$ = Moderate, $$$ = Premium
 
 ---
 
@@ -412,9 +469,19 @@ agent-foundry/
 │   │   ├── anthropic.ts      # Anthropic Claude
 │   │   ├── openai.ts         # OpenAI GPT-4o
 │   │   ├── gemini.ts         # Google Gemini
+│   │   ├── deepseek.ts       # DeepSeek R1
 │   │   ├── ollama.ts         # Local Ollama
 │   │   ├── zai.ts            # Z.AI GLM
-│   │   └── kimi.ts           # Moonshot Kimi
+│   │   ├── kimi.ts           # Moonshot Kimi
+│   │   ├── openrouter.ts     # OpenRouter (100+ models)
+│   │   ├── perplexity.ts     # Perplexity (web search)
+│   │   ├── groq.ts           # Groq (fast inference)
+│   │   ├── together.ts       # Together AI
+│   │   └── fireworks.ts      # Fireworks AI
+│   ├── failover/
+│   │   ├── orchestrator.ts   # Retry and failover logic
+│   │   ├── health-tracker.ts # Provider health monitoring
+│   │   └── pricing.ts        # Cost-aware routing
 │   ├── persistence/          # State persistence
 │   ├── config/               # Configuration management
 │   └── router/               # Routing engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-agent-foundry",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Multi-Agent AI Orchestration with Git Worktree Isolation for Claude Code",
   "type": "module",
   "main": "dist/index.js",