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

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

Team Roles

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

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

Resources

Prompts

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?

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

License

© 2024-2025 Multichoice Agency. All rights reserved.

This software is provided for use under the Multichoice Agency license. For commercial licensing inquiries, contact info@multichoiceagency.nl.