mc-agent

Self-hosted AI coding agent with RAG knowledge base and cross-project intelligence.

Built for developers who want their AI to understand their entire codebase. Trained on 30+ production projects across e-commerce, SaaS, platforms, and corporate websites.

npm i mc-agent

What is mc-agent?

mc-agent is a coding-focused AI agent designed to work with Claude Code and other MCP clients. It provides:

• RAG Knowledge Base — Indexes your codebase, Obsidian vault, and learned patterns for context-aware coding assistance
• Cross-Project Intelligence — Search and reuse code patterns across 30+ projects instantly
• MCP Server for Claude Code — 8 tools, 3 resources, 3 prompts that make Claude Code smarter about your projects
• Multi-Model Support — Ollama (local), OpenAI, or Anthropic
• Persistent Memory — Remembers decisions, patterns, and learnings across sessions

Primary use case: Supercharge Claude Code with deep knowledge of your codebase and coding patterns.

Quick Start

# Install
npm i mc-agent

# Add to Claude Code (recommended)
claude mcp add mc-agent -- npx mc-agent mcp

# Or run standalone with Ollama
mc

# Or with OpenAI
mc --openai

Prerequisites

For local LLM (recommended):

brew install ollama
ollama serve
ollama pull qwen3:8b   # or any model you prefer

Multi-Model Agents (New in v1.1)

Run with multiple specialized Ollama models that auto-route based on task:

mc --multi

Available Agents

| Agent | Model | Use Case | |-------|-------|----------| | @coder | qwen2.5-coder:7b | Code implementation | | @kimi | kimi-k2.5:latest | Complex reasoning | | @architect | qwen3:8b | System design & planning | | @reviewer | deepseek-coder:6.7b | Code review & security | | @fast | llama3.2:3b | Quick responses |

How It Works

mc --multi

mc-agent > implement a login form
[coder] Creating login form component...  # Auto-routes to qwen2.5-coder

mc-agent > @architect design the auth system
[architect] Planning authentication...    # Explicit routing to qwen3

mc-agent > review this code for security
[reviewer] Analyzing vulnerabilities...   # Auto-routes to deepseek-coder

Pull All Models

ollama pull qwen2.5-coder:7b
ollama pull kimi-k2.5:latest
ollama pull qwen3:8b
ollama pull deepseek-coder:6.7b
ollama pull llama3.2:3b

Add Custom Models

// ~/.mc-agent.json
{
  "provider": "multi",
  "defaultAgent": "coder",
  "agents": [
    {
      "name": "custom",
      "model": "mistral:7b",
      "description": "My custom model",
      "triggers": ["custom", "special"],
      "systemPrompt": "You are my custom assistant."
    }
  ]
}

Team Mode (New in v1.2)

Agents work together as a collaborative team with workflows:

mc --team

How Team Mode Works

mc-agent > implement a login feature

[Team Workflow: implement-feature]
Steps: architect → coder → reviewer → coder

--- Step 1/4: @architect ---
Task: Design the feature structure and approach
Planning authentication flow with JWT tokens...

--- Step 2/4: @coder ---  
Task: Implement the feature
Creating LoginForm component and auth API...

--- Step 3/4: @reviewer ---
Task: Review for bugs and security issues
Found: Missing CSRF protection, recommending...

--- Step 4/4: @coder ---
Task: Apply review fixes if needed
Adding CSRF tokens and input sanitization...

[Workflow Complete]

Built-in Workflows

| Trigger | Workflow | Agents | |---------|----------|--------| | "implement feature" | Full implementation | architect → coder → reviewer → coder | | "fix bug" | Bug investigation | reviewer → coder → reviewer | | "code review" | Comprehensive review | reviewer → architect → lead | | "refactor" | Planned refactoring | architect → reviewer → coder → reviewer |

Team Roles

| Agent | Role | Responsibility | |-------|------|----------------| | @lead | Orchestrator | Coordinates work, assigns tasks | | @architect | Designer | Plans structure and approach | | @coder | Implementer | Writes and fixes code | | @reviewer | Quality | Reviews for bugs & security | | @kimi | Reasoner | Complex problem solving |

Swarm Mode (New in v1.3)

Massive parallel processing with 100 or 1000 agents:

mc --swarm        # 100 agents (standard)
mc --swarm1000    # 1000 agents (turbo)

# Shortcuts
mc --100
mc --1000

How Swarm Mode Works

mc-agent > implement a complete e-commerce checkout

[SWARM ACTIVATED: 100 agents]
Pools: analyzers: 15, architects: 10, coders: 40, reviewers: 20, testers: 10, docs: 5
Tasks: 12 | Concurrency: 10

━━━ Phase 1/4: ANALYZERS (2 tasks) ━━━
[Batch 1: 2 parallel tasks]
[task_analyze_1] Analyze requirements for checkout...
[task_analyze_2] Design approach for payment flow...

━━━ Phase 2/4: CODERS (5 tasks) ━━━
[Batch 1: 5 parallel tasks]
[task_impl_1] Implement cart component...
[task_impl_2] Implement payment form...
[task_impl_3] Implement address form...
[task_impl_4] Implement order summary...
[task_impl_5] Implement checkout API...

━━━ Phase 3/4: REVIEWERS (1 task) ━━━
[task_review] Security review of checkout flow...

━━━ Phase 4/4: TESTERS (1 task) ━━━
[task_test] Write integration tests...

━━━ SWARM COMPLETE ━━━
Total: 12 tasks | Done: 12 | Failed: 0
Agents used: 100

Agent Pools

| Pool | 100 Agents | 1000 Agents | Role | |------|------------|-------------|------| | analyzers | 15 | 150 | Analyze requirements | | architects | 10 | 100 | Design solutions | | coders | 40 | 400 | Write code | | reviewers | 20 | 200 | Review & security | | testers | 10 | 100 | Write tests | | docs | 5 | 50 | Documentation |

When to Use

• --swarm (100) — Standard development tasks, feature implementation
• --swarm1000 (1000) — Large refactors, codebase migrations, comprehensive audits

Usage

Interactive Mode

mc                      # Start interactive agent
mc --model llama3.2     # Use specific Ollama model
mc --openai             # Use OpenAI instead

CLI Commands

mc projects             # List all your projects with activity status
mc project <name>       # Show project details (stack, git, memory)
mc context              # Show auto-loaded context for current directory
mc search <query>       # Search knowledge base
mc help                 # Show all commands

REPL Commands (inside the agent)

/help           Show all commands
/projects       List projects
/project X      Show project details
/search Q       Search knowledge base
/memory Q       Search agent memories
/context        Show token usage
/exit           Quit

Knowledge Base (RAG) for Coding

mc-agent's RAG system is optimized for coding through Claude Code. It indexes:

• 30+ production projects — E-commerce, SaaS, platforms, corporate sites
• Code patterns — Authentication, API integrations, component libraries
• Stack standards — Next.js, TypeScript, Tailwind, shadcn/ui, WordPress/WooCommerce
• Deployment configs — Railway, Docker, CI/CD pipelines
• Session memories — Past decisions, learnings, and project context

~/Documents/Obsidian/
├── Portfolio/          # Project documentation & specs
├── Memories/           # Agent notes & coding learnings
│   └── Agent Notes/    # Auto-generated from sessions
├── Sessions/           # Conversation logs with metrics
└── Patterns/           # Reusable code patterns

How It Works with Claude Code

1. Add mc-agent as MCP server — claude mcp add mc-agent -- npx mc-agent mcp
2. Claude Code gains access — 8 tools for searching patterns, projects, memories
3. Context-aware coding — Claude knows your stack, your patterns, your preferences
4. Cross-project reuse — Ask Claude to copy an auth pattern from project A to project B

Configure Vault Path

// ~/.mc-agent.json
{
  "vaultPath": "~/Documents/Obsidian/YourVault"
}

MCP Server

Expose mc-agent as an MCP server for Claude Code, VS Code, or any MCP client.

Add to Claude Code

claude mcp add mc-agent -- npx -y mc-agent mcp

Available Tools

| Tool | Description | |------|-------------| | mc_project_info | Get project details (stack, git, status) | | mc_project_list | List all projects with activity | | mc_vault_search | Search knowledge base | | mc_project_memory | Get stored context for a project | | mc_agency_context | Get stack standards and patterns | | mc_memory_store | Store a note for future reference | | mc_memory_search | Search past memories | | mc_cross_project_search | Grep across all projects |

Resources

| URI | Description | |-----|-------------| | mc://portfolio | Full project portfolio | | mc://agency-context | Stack standards & patterns | | mc://dashboard | Knowledge base summary |

Prompts

| Prompt | Description | |--------|-------------| | scaffold-project | Generate new project from templates | | copy-pattern | Copy code pattern between projects | | project-review | Review project against standards |

Configuration

Create ~/.mc-agent.json:

{
  "provider": "ollama",
  "ollamaModel": "qwen3:8b",
  "ollamaHost": "http://localhost:11434",
  "openaiModel": "gpt-4o",
  "anthropicModel": "claude-sonnet-4-20250514",
  "githubPath": "~/Documents/GitHub",
  "vaultPath": "~/Documents/Obsidian/Vault",
  "maxTokenBudget": 100000,
  "confirmDestructive": true
}

Environment Variables

OLLAMA_MODEL=qwen3:8b           # Override Ollama model
MC_AGENT_PROVIDER=openai        # Override provider
OPENAI_API_KEY=sk-...           # Required for OpenAI
ANTHROPIC_API_KEY=sk-ant-...    # Required for Anthropic

Architecture

mc-agent/
├── src/
│   ├── index.ts              # CLI entrypoint
│   ├── repl.ts               # Interactive REPL
│   ├── config.ts             # Configuration loader
│   ├── types.ts              # TypeScript types
│   ├── llm/
│   │   ├── provider.ts       # LLM abstraction
│   │   ├── ollama.ts         # Ollama client
│   │   ├── openai.ts         # OpenAI client
│   │   ├── anthropic.ts      # Anthropic client
│   │   └── context.ts        # Context window management
│   ├── knowledge/
│   │   ├── vault.ts          # Obsidian vault reader (RAG)
│   │   ├── memory.ts         # Persistent memory
│   │   ├── projects.ts       # Project scanner
│   │   └── agency.ts         # Learned patterns
│   ├── tools/
│   │   ├── registry.ts       # Tool definitions
│   │   ├── file.ts           # File operations
│   │   ├── bash.ts           # Shell commands
│   │   ├── git.ts            # Git operations
│   │   └── search.ts         # Code search
│   └── mcp/
│       └── server.ts         # MCP server implementation

Context Management

• Auto-loads: CLAUDE.md, package.json, tsconfig.json, project structure
• Token Budgeting: Estimates usage, compresses when approaching limits
• Smart Compression: Keeps system prompt + recent messages + key context

Cross-Project Intelligence

The agent understands patterns from your codebase:

• Scans ~/Documents/GitHub/ for all projects
• Detects stack (Next.js, React, TypeScript, etc.)
• Tracks activity via git commits
• Enables cross-project code search and pattern copying

Why mc-agent?

| Feature | mc-agent | Claude Code | Cursor | GitHub Copilot | |---------|----------|-------------|--------|----------------| | Self-hosted LLM | ✅ | ❌ | ❌ | ❌ | | RAG knowledge base | ✅ | ❌ | Limited | ❌ | | Cross-project search | ✅ | ❌ | ❌ | ❌ | | Persistent memory | ✅ | ❌ | ❌ | ❌ | | MCP server | ✅ | N/A | ❌ | ❌ | | Your data stays local | ✅ | ❌ | ❌ | ❌ |

Development

git clone https://github.com/Multichoiceagency/mc-agent.git
cd mc-agent
npm install
npm run dev           # Development with tsx
npm run build         # Build for production
npm run start         # Run built version

Cursor / VS Code Extension

Install the extension for a native IDE experience with sidebar panel:

# Install from VSIX (local)
cursor --install-extension cursor-extension/mc-agent-cursor-1.3.2.vsix

# Or search "MC Agent" in Extensions

Sidebar Panel

The MC Agent icon appears in the Activity Bar (left sidebar, next to Explorer/Search/Git icons):

• 🤖 Chat — Interactive chat with quick actions
• 📜 History — Previous conversations
• ⚙️ Settings — Quick access to configuration

Extension Shortcuts

| Shortcut | Action | |----------|--------| | Cmd+Shift+A | Ask MC Agent | | Cmd+Shift+E | Explain selection | | Cmd+Shift+X | Fix selection | | Cmd+Shift+R | Refactor selection | | Cmd+Alt+R | Review file | | Cmd+Shift+T | Generate tests | | Cmd+Shift+S | Swarm mode |

Configuration

Open Settings (Cmd+,) and search for "MC Agent":

• Agent Mode — Select swarm, turbo, team, or multi
• Ollama Host — Your Ollama server URL
• Model — Choose from qwen2.5-coder, deepseek-coder, llama3.2, etc.
• Vault Path — Path to Obsidian vault for RAG

Right-click on selected code for context menu actions.

Web Dashboard (New in v1.4)

A Claude Code-style PWA dashboard for browser-based development:

# Start the dashboard
npm run dashboard

# Or build for production
npm run dashboard:build
npm run dashboard:start

Open http://localhost:3344

Features

• 🎨 Claude Code-style UI — Dark theme, clean interface
• 📱 PWA Support — Install as native app on any device
• 🤖 All Agent Modes — Single, Multi, Team, Swarm (100), Turbo (1000)
• 💬 Streaming Responses — Real-time output from Ollama
• ⚙️ Configurable — Custom Ollama host and model selection

PWA Installation

Desktop (Chrome/Edge):

1. Open dashboard in browser
2. Click install icon in address bar
3. Click "Install"

Mobile (iOS/Android):

1. Open dashboard in browser
2. Tap Share → "Add to Home Screen"

License

© 2024-2025 Multichoice Agency. All rights reserved.

This software is provided for use under the Multichoice Agency license. For commercial licensing inquiries, contact [email protected].