Nexus Agents

Multi-agent orchestration MCP server with model diversity and workflow automation

Overview

Nexus Agents is an MCP (Model Context Protocol) server that coordinates multiple AI experts to handle software development tasks. It provides a unified interface for different AI models and enables multi-agent collaboration through a Tech Lead and specialized experts.

Key Capabilities

• Multi-Agent Orchestration - Tech Lead coordinates specialized experts for complex tasks
• Model Diversity - Support for Claude, OpenAI, Gemini, and Ollama
• Workflow Automation - YAML-based templates for repeatable processes
• Security-First Design - Defense in depth with secrets vault and input validation

Quick Start

Installation

# Install the package
npm install nexus-agents

# Or install globally for CLI usage
npm install -g nexus-agents

CLI Usage

Start the MCP server:

# If installed globally
nexus-agents

# Or with npx
npx nexus-agents

Programmatic Usage

import {
  createServer,
  startStdioServer,
  TechLead,
  createClaudeAdapter,
  ExpertFactory,
} from 'nexus-agents';

// Start MCP server
const result = await startStdioServer({
  name: 'my-server',
  version: '1.0.0',
});

// Or use programmatically
const adapter = createClaudeAdapter({
  model: 'claude-sonnet-4-20250514',
});
const techLead = new TechLead({ adapter });

// Create experts dynamically
const factory = new ExpertFactory(adapter);
const codeExpert = factory.create({ type: 'code' });

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nexus-agents": {
      "command": "npx",
      "args": ["nexus-agents"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Features

Multi-Agent Orchestration

The Tech Lead agent analyzes incoming tasks and delegates to specialized experts:

| Expert | Specialization | | ------------------------ | ------------------------------------------------------ | | Code Expert | Implementation, debugging, optimization, refactoring | | Architecture Expert | System design, patterns, trade-offs, scalability | | Security Expert | Vulnerability analysis, secure coding, threat modeling | | Documentation Expert | Technical writing, API docs, code comments | | Testing Expert | Test strategies, coverage analysis, test generation |

Experts can collaborate on complex tasks. The Tech Lead combines their outputs into a single response.

Model Adapters

Use different AI models through unified interfaces:

| Provider | Models | Best For | | ---------- | ----------------------- | -------------------------- | | Claude | Haiku, Sonnet, Opus | General coding, analysis | | OpenAI | GPT-4o, GPT-4o-mini, o1 | Reasoning, code generation | | Gemini | Pro, Ultra | Long context, multimodal | | Ollama | Llama, CodeLlama, etc. | Local inference, privacy |

Model selection uses semantic classification with tier escalation:

Fast (quick queries) -> Balanced (most tasks) -> Powerful (complex reasoning)

Workflow Engine

Define reusable workflows in YAML:

name: code-review
description: Comprehensive code review workflow
steps:
  - agent: security_expert
    action: scan_vulnerabilities
    output: security_report

  - agent: code_expert
    action: review_quality
    input: ${security_report}
    output: quality_report

  - agent: testing_expert
    action: analyze_coverage
    parallel: true

  - agent: documentation_expert
    action: check_documentation
    parallel: true

MCP Tools

The server exposes these MCP tools for integration:

| Tool | Description | | --------------- | -------------------------------------------- | | orchestrate | Analyze task and coordinate expert execution | | create_expert | Dynamically create a specialized expert | | run_workflow | Execute a predefined workflow template |

Architecture

nexus-agents/
├── packages/
│   └── nexus-agents/         # Main package
│       ├── src/
│       │   ├── core/         # Shared types, Result<T,E>, errors, logger
│       │   ├── config/       # Configuration loading and validation
│       │   ├── adapters/     # Model adapters (Claude, OpenAI, Gemini, Ollama)
│       │   ├── agents/       # Agent framework (TechLead, Experts)
│       │   ├── workflows/    # Workflow engine and templates
│       │   ├── mcp/          # MCP server and tool definitions
│       │   ├── cli-adapters/ # External CLI integration (Claude/Gemini/Codex CLIs)
│       │   ├── context/      # Token counting, work balancing, memory
│       │   ├── consensus/    # Multi-agent voting and decisions
│       │   ├── index.ts      # Main exports
│       │   └── cli.ts        # CLI entry point
│       └── package.json
├── .claude/
│   ├── rules/                # Claude Code rules
│   └── skills/               # Project-specific skills
└── pnpm-workspace.yaml

See ARCHITECTURE.md for detailed module descriptions.

Dependency Flow

MCP Server (external boundary)
    ↓
Workflow Engine (orchestrates execution)
    ↓
Agents Layer (TechLead, Experts)
    ↓
Adapters Layer (Claude, OpenAI, Gemini, Ollama)
    ↓
Core Layer (Types, Result<T,E>, Errors, Logger)

Core Interfaces

// Unified model interaction
interface IModelAdapter {
  complete(request: CompletionRequest): Promise<Result<Response, ModelError>>;
  stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
  countTokens(text: string): Promise<number>;
}

// Base agent contract
interface IAgent {
  readonly id: string;
  readonly role: AgentRole;
  execute(task: Task): Promise<Result<TaskResult, AgentError>>;
  handleMessage(msg: AgentMessage): Promise<Result<AgentResponse, AgentError>>;
}

// Workflow execution
interface IWorkflowEngine {
  loadTemplate(path: string): Promise<Result<WorkflowDefinition, ParseError>>;
  execute(
    workflow: WorkflowDefinition,
    inputs: unknown
  ): Promise<Result<WorkflowResult, WorkflowError>>;
}

Configuration

Environment Variables

| Variable | Description | Required | | ------------------- | --------------------------------- | ------------------------------------- | | ANTHROPIC_API_KEY | Claude API key | Yes (for Claude) | | OPENAI_API_KEY | OpenAI API key | For OpenAI models | | GOOGLE_AI_API_KEY | Google AI API key | For Gemini models | | OLLAMA_HOST | Ollama server URL | For Ollama (default: localhost:11434) | | NEXUS_LOG_LEVEL | Log level (debug/info/warn/error) | No |

API Reference

Adapters

import {
  createClaudeAdapter,
  createOpenAIAdapter,
  createGeminiAdapter,
  createOllamaAdapter,
  AdapterFactory,
} from 'nexus-agents';

// Create individual adapters
const claude = createClaudeAdapter({ model: 'claude-sonnet-4-20250514' });
const openai = createOpenAIAdapter({ model: 'gpt-4o' });
const gemini = createGeminiAdapter({ model: 'gemini-1.5-pro' });
const ollama = createOllamaAdapter({ model: 'llama3:8b' });

// Or use the factory
const factory = new AdapterFactory();
const adapter = factory.create({ provider: 'anthropic', model: 'claude-sonnet-4-20250514' });

Agents

import { TechLead, ExpertFactory, Expert } from 'nexus-agents';

// Create TechLead for orchestration
const techLead = new TechLead({ adapter });

// Create experts
const factory = new ExpertFactory(adapter);
const codeExpert = factory.create({ type: 'code' });
const securityExpert = factory.create({ type: 'security' });

MCP Server

import { createServer, startStdioServer, registerTools } from 'nexus-agents';

// Create and start server
const result = await startStdioServer({
  name: 'my-server',
  version: '1.0.0',
});

if (result.ok) {
  const { server } = result.value;
  // Server is running with stdio transport
}

Development

Prerequisites

• Node.js 22.x LTS
• pnpm 9.x
• TypeScript 5.8+

Setup

# Clone the repository
git clone https://github.com/williamzujkowski/nexus-agents.git
cd nexus-agents

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Start development mode
pnpm dev

Commands

# Development
pnpm dev              # Start dev server with watch mode
pnpm build            # Build the package
pnpm clean            # Clean build artifacts

# Quality
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix linting issues
pnpm typecheck        # Run TypeScript type checking
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage

Contributing

We welcome contributions! Please see our guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit with conventional commits (git commit -m 'feat(agents): add amazing feature')
4. Push to your branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Code Standards

• Files must be under 400 lines
• Functions must be under 50 lines
• Test coverage must be at least 80%
• All code must pass linting and type checking

See CODING_STANDARDS.md for detailed guidelines. See CONTRIBUTING.md for contribution workflow.

Commit Convention

We use Conventional Commits:

feat(scope): add new feature
fix(scope): fix bug
refactor(scope): refactor code
docs(scope): update documentation
test(scope): add tests
chore(scope): maintenance tasks

License

MIT - See LICENSE for details.

Acknowledgments

This project is a clean-room rewrite inspired by claude-team-mcp, with attribution preserved per MIT license.

Built with Claude Code