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

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

# Stop the server
stop.bat

Manual Installation

# 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):

$env:MCP_LOCAL_LLM_PATH = "C:\path\to\mcpLocalLLM"
[Environment]::SetEnvironmentVariable("MCP_LOCAL_LLM_PATH", "C:\path\to\mcpLocalLLM", "User")

macOS/Linux:

# Add to ~/.bashrc or ~/.zshrc
export MCP_LOCAL_LLM_PATH="/path/to/mcpLocalLLM"

Step 2: Create .vscode/mcp.json in any project:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

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

Windsurf

Create .windsurf/mcp.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

{
  "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

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

Zed

{
  "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)

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:

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/)

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

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

# 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):

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)

# 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)

# 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

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

# 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

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:

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:

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

Architecture

+-----------------------------+
|       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