# MCP Local LLM Server

A privacy-first MCP (Model Context Protocol) server that provides **unique LLM-enhanced tools** for VS Code Copilot. All analysis uses your local LLM - code never leaves your machine.

## Key Features

- **Privacy-First**: All LLM analysis runs locally - your code never leaves your machine
- **VS Code Copilot Optimized**: Designed to complement (not duplicate) VS Code's built-in tools
- **LLM-Enhanced Tools**: Every tool adds intelligent analysis, not just raw data
- **Symbol-Aware**: Understands code structure, not just text patterns
- **Security Scanning**: Automatic detection of secrets, API keys, and vulnerabilities
- **Multiple Backends**: Ollama, LM Studio, OpenRouter support

## Documentation Map

- `docs/API_REFERENCE.md` - full tool schemas and usage
- `docs/TOOL_VISIBILITY_TIERS.md` - tool surfacing strategy (core/discoverable/hidden)
- `docs/examples/client-configuration-guide.md` - IDE/client setup patterns
- `docs/operations/scripts-guide.md` - operational scripts and maintenance
- `docs/operations/test-utils.md` - test harness utilities
- `docs/prompts/` - curated prompt suites for QA/regression workflows

## Prerequisites

- Node.js 20+ and npm
- One local LLM backend running (LM Studio or Ollama)
- Python 3.10+ (only required for `run_all_tests_ALL.py`)

## Quick Start

### Windows Users - Automated Setup

```cmd
# Start the server (auto-installs dependencies if needed)
start.bat

# Stop the server
stop.bat
```

### Manual Installation

```bash
# Install dependencies from the project root
npm install
npm run build

# Configure (optional)
cp env.settings.example env.settings

# Start
npm start
```

### VS Code Integration

There are several ways to configure MCP Local LLM with VS Code. Choose the method that best fits your workflow.

#### Option 1: Environment Variable (Recommended for Distribution)

**Step 1:** Set an environment variable pointing to your mcpLocalLLM installation:

**Windows (PowerShell - add to profile for persistence):**
```powershell
$env:MCP_LOCAL_LLM_PATH = "C:\path\to\mcpLocalLLM"
[Environment]::SetEnvironmentVariable("MCP_LOCAL_LLM_PATH", "C:\path\to\mcpLocalLLM", "User")
```

**macOS/Linux:**
```bash
# Add to ~/.bashrc or ~/.zshrc
export MCP_LOCAL_LLM_PATH="/path/to/mcpLocalLLM"
```

**Step 2:** Create `.vscode/mcp.json` in any project:
```json
{
  "mcp": {
    "servers": {
      "mcp-local-llm": {
        "command": "node",
        "args": [
          "${env:MCP_LOCAL_LLM_PATH}/dist/index.js",
          "--settings",
          "${env:MCP_LOCAL_LLM_PATH}/env.settings"
        ]
      }
    }
  }
}
```

This same configuration works across all projects without modification.

#### Option 2: Absolute Path (Simple, Project-Specific)

Create `.vscode/mcp.json` with the full path:
```json
{
  "mcp": {
    "servers": {
      "mcp-local-llm": {
        "command": "node",
        "args": [
          "C:/Users/yourname/mcpLocalLLM/dist/index.js",
          "--settings",
          "C:/Users/yourname/mcpLocalLLM/env.settings"
        ]
      }
    }
  }
}
```

> **Note:** Pass `--settings <path>` to ensure the server uses the intended settings file (especially when you have multiple installs).

#### Option 3: Per-Project Configuration with Custom Workspace

For projects that need custom workspace settings, create a project-local `env.settings`:

**Step 1:** Copy `env.settings.example` to your project as `env.settings`

**Step 2:** Configure workspace roots + allowlist via the Web UI (`http://127.0.0.1:3000/`) or by editing `[config] CONFIG_JSON` in `env.settings`.

**Step 3:** Point your `.vscode/mcp.json` to this settings file:
```json
{
  "mcp": {
    "servers": {
      "mcp-local-llm": {
        "command": "node",
        "args": [
          "${env:MCP_LOCAL_LLM_PATH}/dist/index.js",
          "--settings",
          "${workspaceFolder}/env.settings"
        ]
      }
    }
  }
}
```

#### Optional: OpenRouter for Testing

If you want to test with an external SOTA backend (not needed for normal use):
```json
{
  "mcp": {
    "servers": {
      "mcp-local-llm": {
        "command": "node",
        "args": [
          "${env:MCP_LOCAL_LLM_PATH}/dist/index.js",
          "--settings",
          "${env:MCP_LOCAL_LLM_PATH}/env.settings"
        ],
        "env": {
          "TESTING_MODE_ENABLED": "true",
          "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
        }
      }
    }
  }
}
```

### Other IDEs

#### Cursor

Create `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "mcp-local-llm": {
      "command": "node",
      "args": ["${env:MCP_LOCAL_LLM_PATH}/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

#### Windsurf

Create `.windsurf/mcp.json`:
```json
{
  "mcpServers": {
    "mcp-local-llm": {
      "command": "node",
      "args": ["${env:MCP_LOCAL_LLM_PATH}/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

#### Claude Desktop

Add to `claude_desktop_config.json`:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-local-llm": {
      "command": "node",
      "args": ["C:/path/to/mcpLocalLLM/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "C:/path/to/your/project"
      }
    }
  }
}
```

> **Important:** Set `WORKSPACE_ROOT` to your project for proper path resolution.

#### Roo Code / Kilo Code

```json
{
  "mcpServers": {
    "mcp-local-llm": {
      "command": "node",
      "args": ["C:/path/to/mcpLocalLLM/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "C:/path/to/your/project"
      }
    }
  }
}
```

#### Zed

```json
{
  "mcpServers": {
    "mcp-local-llm": {
      "command": "node",
      "args": ["/path/to/mcpLocalLLM/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}
```



## Available Tools (48 registered; 47 enabled by default)

The tool surface is consolidated into three tiers to keep ListTools small while preserving full capability.

### Core Tools (always exposed via ListTools)

| Tool | Description |
|------|-------------|
| `agent_task` | Autonomous multi-step task execution |
| `mcp_health` | Server health and diagnostics |
| `search` | Unified search (intelligent/structured/gather/filenames) |
| `analyze_file` | LLM-powered file analysis |
| `suggest_edit` | LLM-powered edit suggestions |
| `local_code_review` | Privacy-preserving code review |
| `security` | Secret scanning, risk analysis, redaction, and fixes |
| `summarize` | File/directory/repo summaries |
| `workspace` | Workspace metadata, snapshots, and exploration |
| `discover_tools` | Find additional tools by category or capability |

### Discoverable Tools (via `discover_tools`)

Categories:
- `code_analysis` - find_duplicates, code_quality_analyzer, analyze_file, code_helper, mcp_analyze_complexity
- `security` - security, local_code_review, analyze_impact
- `testing` - analyze_test_gaps
- `documentation` - generate_docs, mcp_diff_summarizer, summarize, generate_agents_md
- `refactoring` - suggest_refactoring, refactor_helper, suggest_edit, draft_file, find_and_fix
- `planning` - agent_task, mcp_plan_implementation, cli_orchestrate
- `search` - search, codebase_qa, todos, index_symbols, cross_file_links
- `llm_assistance` - code_helper, regex_helper, refactor_helper, mcp_error_explainer, mcp_translate_code, mcp_summarize_logs
- `execution` - linter, formatter
- `workspace` - workspace, analyze_file
- `system` - mcp_health

### Agent-Only Tools (hidden from ListTools)

Hidden by default but callable by name (or via `agent_task`):
`llm_chat`, `agent_task_result`, `agent_queue_status`, `mcp_server`, `mcp_ask`, `system_profile`, `model_info`, `mcp_debug`, `mcp_terminal_command`, `refine_prompt`, `read_file`, `verify_plan`

For complete schemas and usage examples, see docs/API_REFERENCE.md.

## MCP Prompts (Guided Workflows)

Invoke these prompts to run multi-tool workflows:

| Prompt | Description |
|--------|-------------|
| `/analyze-security` | Comprehensive security analysis |
| `/find-todos` | Find and prioritize technical debt |
| `/review-changes` | Privacy-preserving code review |
| `/explain-code` | Detailed code explanation |
| `/generate-tests` | Generate comprehensive tests |
| `/suggest-improvements` | Get refactoring suggestions |

## Automated Prompt-Based QA

This repository uses a second QA layer in addition to unit/integration/e2e tests:
prompt-driven black-box evaluations stored in `docs/prompts/`.

### Why This Exists

- Deterministic tests catch functional regressions quickly.
- Prompt-based QA catches behavior quality issues that static assertions miss:
  prompt interpretation quality, report usefulness, orchestration behavior, and real-world operator ergonomics.

### Prompt Catalog (`docs/prompts/`)

| Prompt File | Primary Use |
|-------------|-------------|
| `00_smoke.md` | Fast smoke validation |
| `10_regression_feedback_4_5.md` | Regression checks for historical feedback batches 4/5 |
| `20_regression_feedback_6.md` | Regression checks for historical feedback batch 6 |
| `30_edge_cases.md` | Edge-case behavior and failure-mode validation |
| `40_production_readiness.md` | Production-readiness checklist run |
| `MCP_TEST_BLACK_BOX_COMPACT.md` | Compact black-box evaluation for small local models |
| `MCP_TEST_BLACK_BOX_STANDARD.md` | Standard black-box evaluation |
| `MCP_TEST_COMPACT_V2.md` | Compact black-box evaluation v2 |
| `MCP_TEST_COMPREHENSIVE_V2.md` | Comprehensive black-box evaluation v2 |
| `MCP_TEST_CRITICAL_COMPACT.md` | Compact critical bug hunt |
| `MCP_TEST_CRITICAL_STANDARD.md` | Standard critical-component validation |
| `MCP_FINAL_TEST.md` | Single comprehensive final validation prompt |
| `AGENT_TEST_PROMPT.md` | End-to-end agent-oriented tool testing prompt |
| `DEBUG-FIX-PROMPT.md` | Turn accumulated QA reports into a focused fix pass |
| `QA_feedback_empty.md` | Template for recording findings in a consistent format |

### Recommended QA Workflow

1. Run deterministic baseline tests first:
   - `python run_all_tests_ALL.py`
   - `npm test`
2. Execute prompt suites against target backends/models (local and/or CLI backends).
3. Save each run report using the `QA_feedback_empty.md` structure into a reports folder (for example `TEST_PROMPTS/REPORTS/QA_feedback_01.md`, `QA_feedback_02.md`, etc.).
4. For each finding, explicitly classify:
   - real repository issue, or
   - evaluator/model mistake (false positive or prompt misunderstanding).
5. Use `docs/prompts/DEBUG-FIX-PROMPT.md` with the reports folder to drive an implementation pass.
6. Re-run deterministic tests and at least one black-box prompt before publishing.

### Automation vs Manual Testing Effectiveness

| Dimension | Prompt-Based QA | Manual Testing |
|-----------|------------------|----------------|
| Breadth per run | High (many behaviors covered quickly) | Medium |
| Repeatability | High when prompts + config are versioned | Medium/Low |
| Speed to first signal | High | Medium/Low |
| False-positive risk | Medium (model/evaluator noise exists) | Low/Medium |
| UX/intent nuance detection | Medium/High | High |
| Best use | Continuous regression sweeps | Final human sign-off and edge judgment |

Practical guidance:
- Do not replace manual testing with prompt automation.
- Use prompt-based QA for scale and regression detection, then use manual testing for final adjudication and release confidence.

## Why These Tools?

### VS Code Copilot Bypass Strategy

VS Code Copilot 1.106+ automatically disables MCP tools that duplicate built-in functionality. This server provides **unique value** that VS Code cannot replicate:

1. **Local LLM Intelligence**: Every tool is enhanced with local LLM analysis
2. **Privacy Preservation**: Code analysis never leaves your machine
3. **Automatic Redaction**: Secrets and sensitive data automatically removed
4. **Symbol Awareness**: Understands code structure, not just text
5. **Security Scanning**: Built-in vulnerability detection

### Tools NOT Included (VS Code Has Better Versions)

These tools were intentionally removed because VS Code Copilot has superior built-in equivalents:
- `read_file` (hidden alias of `analyze_file`, not exposed via ListTools) -> Use VS Code's `#readFile`
- `edit_file` -> Use VS Code's `#editFiles`
- `create_file` -> Use VS Code's `#createFile`
- `list_dir` -> Use VS Code's `#listDirectory`
- `git_status/diff/log/commit` -> Use VS Code's Source Control
- `execute_script` -> Use VS Code's `#runInTerminal`
- `run_tests` -> Use VS Code's `#runTests`

## Configuration

### Initial Setup

```bash
# Copy the example settings
cp env.settings.example env.settings

# Edit to match your setup (optional - defaults work for most users)
# The example file is well-commented and explains all options
```

Note: The repository `env.settings.example` is the canonical source of defaults. When building the npm package the build process copies this file into `dist_package/env.settings.example` (via `node scripts/generate_package_files.js`) so the package uses the same example. A parity test (`tests/config.settings-parity.test.ts`) runs in CI to ensure the packaged example always matches the repository file, preventing accidental drift.

### Backend Configuration (`env.settings`)

Backends/defaults live in `[config] CONFIG_JSON` inside `env.settings` (or configure via the Web UI at `http://127.0.0.1:3000/`).

### Workspace Configuration

Workspace roots + allowlist live in `[config] CONFIG_JSON` inside `env.settings`.

> **Tip:** Relative paths in `env.settings` are resolved relative to the settings file's directory, not the current working directory.

### Dynamic Workspace Detection

The MCP server automatically detects your workspace using this priority:

1. **MCP Client Roots** (if supported): The server requests workspace roots from the client via the MCP protocol (`roots/list`). This happens automatically on connection.
2. **`WORKSPACE_ROOT` Environment Variable**: Fallback for explicit control.
3. **Global Install Auto-Detection**: When config is in a global location (`~/.mcp-local-llm`, npm global), **the current working directory is used as workspace automatically**.
4. **Project Auto-Detection**: If launched from a directory containing `package.json`, `pyproject.toml`, `.git`, etc., that directory is used.
5. **Settings File Default**: Falls back to `workspace.roots` from `env.settings`

> **Global npm install users:** Workspace is now detected automatically from your project's working directory. No configuration needed.

> **Troubleshooting:** If tools report "Outside workspace" errors, check the startup logs for `[Config] Workspace from cwd...` messages.


### Tool Groups

Tools are organized into groups that can be enabled/disabled (examples only; see docs/API_REFERENCE.md for the full list):

| Group | Example Tools | Purpose |
|-------|---------------|---------|
| `core.summary` | summarize | LLM summarization |
| `core.chat` | llm_chat | Direct LLM access |
| `core.discovery` | discover_tools | Tool discovery |
| `planning` | agent_task, verify_plan, cli_orchestrate | Planning and delegation |
| `analysis.extended` | workspace, todos, codebase_qa, analyze_test_gaps, analyze_impact | Codebase analysis |
| `privacy` | security | Security tools |
| `llm.enhanced` | analyze_file, search, local_code_review, generate_docs, suggest_refactoring, suggest_edit, find_and_fix | LLM-enhanced tools |
| `code.analysis` | find_duplicates, code_quality_analyzer | Code quality |
| `llm.assistance` | code_helper, regex_helper, refactor_helper, mcp_error_explainer, mcp_translate_code | LLM assistance |
| `execution` | linter, formatter | Code quality automation |
| `system.info` | mcp_health, system_profile, model_info, mcp_debug | System diagnostics |
| `mcp.client` | mcp_server, mcp_ask | External MCP integration |

## Privacy & Security

- **Offline by Default**: Only local backends unless explicitly configured
- **Content Redaction**: Automatic removal of secrets, API keys, sensitive data
- **Path Restrictions**: Directory allowlist prevents unauthorized access
- **Size Limits**: Prevents large file transfers

## Agent Scenarios Testing

The project includes comprehensive agent scenarios tests that validate complex workflows and integration with external MCP servers.

### Running Agent Scenarios Tests

#### Basic Tests (No External Services Required)

```bash
# Run configuration and structure validation tests
npx vitest run tests/agent_tasks/agent.scenarios.basic.test.ts

# Run all basic tests together
npx vitest run tests/agent_tasks/agent.scenarios.basic.test.ts
```

#### Full End-to-End Tests (Requires External Services)

```bash
# Run complete agent scenarios (requires LM Studio, local server, MCP servers)
npx vitest run tests/agent_tasks/agent.scenarios.e2e.test.ts

# Run specific test suites
npx vitest run tests/agent_tasks/agent.scenarios.e2e.test.ts -t "Read-Only Operations"
npx vitest run tests/agent_tasks/agent.scenarios.e2e.test.ts -t "Chrome DevTools"
npx vitest run tests/agent_tasks/agent.scenarios.e2e.test.ts -t "Context7"
```

### Test Requirements

| Test Suite | Requirements | Description |
|------------|--------------|-------------|
| **Basic Tests** | None | Configuration loading and structure validation |
| **Read-Only Operations** | LM Studio backend | Repo audits, security analysis |
| **Chrome DevTools** | Chrome DevTools MCP | Browser automation, screenshots |
| **Context7** | Context7 MCP | Library documentation validation |
| **Local Server** | Local MCP server | API integration, server management |

### Configuration

The test runner uses centralized automated settings (via `run_all_tests_ALL.py`):

- **Canonical Settings File**: `config/env-automated-tests.settings`
- **Compatibility Fallback**: `env-automated-tests.settings` (root)
- **Primary Backend**: configured in `[config] CONFIG_JSON` (defaults)
- **MCP Servers**: configured under `mcpServers` (optional)
- **Workspace**: configured under `workspace` / `policy.allowlistPaths`
- **Tool Groups**: configured under `toolGroups` / `[advanced] TOOL_GROUP_MODE`
- **Runner Usage**:
  - Full suite: `python run_all_tests_ALL.py`
  - Force Copilot CLI: `python run_all_tests_ALL.py --backend copilot-cli`
  - Force OpenCode CLI: `python run_all_tests_ALL.py --backend opencode-cli`
  - All backends: `python run_all_tests_ALL.py --all-backends`
  - Benchmark backends: `python run_all_tests_ALL.py --benchmarking`

### Test Output

- **Configuration Tests**: 11 tests validating all configuration aspects
- **Structure Tests**: 5 tests validating test framework structure
- **E2E Tests**: 27 comprehensive scenarios covering all major workflows
- **Output Location**: `tests/.mcp_cache/agent_scenarios/`

### Development Mode

```bash
# Run tests with UI for development
npx vitest tests/agent_tasks/agent.scenarios.*

# Run specific test with debugging
npx vitest run tests/agent_tasks/agent.scenarios.basic.test.ts --reporter=verbose
```

## Development

```bash
npm run dev    # Development mode with auto-reload
npm test       # Run tests (auto-prepares + auto-cleans transient test artifacts)
npm run build  # Build for production
npm run cleanup:runtime  # Prune runtime artifact dirs (.mcp-backups, .orchestration-plans)
```

### Runtime Artifact Cleanup

The server can accumulate local runtime artifacts over time:
- `.mcp-backups/` from edit/auto-fix backup snapshots
- `.orchestration-plans/` from persisted CLI orchestration plans

Use:

```bash
npm run cleanup:runtime
```

Default pruning behavior:
- Removes `.mcp-backups/tests/` (test-only backup artifacts)
- Removes backup files older than 14 days
- Caps remaining backups to the newest 1000 files
- Removes orchestration plans older than 14 days
- Caps remaining plans to the newest 200 directories
- Removes orphan `*.tmp` files under `.orchestration-plans/`

Optional dry-run:

```bash
node scripts/cleanup-runtime-artifacts.js --dry-run
```

## Architecture

```text
+-----------------------------+
|       VS Code Copilot       |
+--------------+--------------+
               |
               v
      MCP Protocol (stdio)
               |
               v
+-----------------------------+
|     MCP Local LLM Server    |
| - LLM-Enhanced Tools        |
| - Privacy Tools             |
| - Analysis Tools            |
+--------------+--------------+
               |
               v
 Backend Adapters: Ollama | LM Studio | OpenRouter | Generic OpenAI
               |
               v
      Local LLM Backend
    (Ollama, LM Studio, etc.)
```

## License

ISC