MCP本地模型助手

mcpLocalHelper

Experimental MCP developer tooling for local-model assistance, code analysis and task delegation.

Status: engineering prototype and portfolio case study. Not production-ready. This repository preserves a working design and its development/testing material. It has not been certified for production security, reliability or compatibility with every current model and MCP client. Start with a disposable workspace and non-sensitive examples.

The problem I was exploring

Developer agents can spend substantial context on tool descriptions and raw repository output. Local models can take on some analysis, but integrating them means dealing with workspace boundaries, model capabilities, failures and the hand-off back to the calling agent.

I built this project to explore that integration: expose useful analysis through MCP, let an IDE agent delegate bounded work, and make local and optional external backends configurable. The value of this repository is the implementation and the decisions it makes visible, rather than a claim that MCP or hybrid inference was invented here.

What the code demonstrates

• Protocol and model integration: MCP tool registration and adapters for local model servers, with optional external backends
• Code-analysis tooling: duplicate-file, similar-function and duplicate-code analysis, evolved from earlier Python utilities
• Context management: a small initial tool surface with discovery and progressive expansion instead of presenting every tool at once
• Operational concerns: workspace configuration, input limits, backend timeouts, concurrency controls and failure reporting
• Evaluation practice: deterministic tests alongside prompt-based evaluation material, with model output treated as something to review

These are inspectable engineering choices. They are not evidence of customer adoption, measured business impact or an enterprise deployment.

Project history

The project started as private MCP experiments in August 2025 and evolved across earlier repositories before this cleaned public release.

This chronology describes development history, not an earlier public release. The public history starts with the initial release on 10 February 2026. Its short commit history is a publication snapshot rather than the full development history. The earlier working repositories remain private.

Scope and safety limits

• Local execution is a configuration choice, not an end-to-end privacy guarantee. External adapters can send data off-device. An MCP client may also forward tool results to its own cloud model, even when this server used a local backend
• Redaction and path restrictions are safeguards with limitations. They do not establish complete secret detection, a hardened execution sandbox or regulatory compliance
• Model-generated findings, edits and plans require review. Optional execution tools should only be evaluated with restricted permissions and disposable data
• Client configuration examples below reflect the development period. Check the current client's MCP schema, supported tools and trust settings before using them
• Test commands and historical evaluation material are retained for reproducibility. This documentation update does not constitute a fresh execution of those suites

Reviewed positioning: 30 September 2026. The ecosystem has developed since this work began. Use this as a case study in building and assessing integrations; evaluate maintained alternatives against your present requirements before adopting it.

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?

Choosing a focused tool surface

The design aims to complement an IDE's existing file and terminal tools. Client behavior varies; duplicate-tool suppression is not a compatibility guarantee. The project explored:

1. Local-model assistance: Model-assisted analysis alongside deterministic tools
2. Configurable processing: Local analysis where selected, with external paths requiring separate data-sharing review
3. Redaction safeguards: Pattern-based filtering of some sensitive data, with incomplete coverage
4. Symbol Awareness: Understands code structure, not just text
5. Security Scanning: Built-in vulnerability detection

Tools delegated to the client

Some overlapping tools were removed from the default exposed surface or retained only as hidden aliases. Where appropriate, use your client's supported 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

• Backend selection: inspect the active configuration and the MCP client's own data flow; local adapters do not make the entire session offline
• Content redaction: filters known patterns but can miss secrets, proprietary content and contextual identifiers
• Path restrictions: configured allowlists narrow intended access; they are not a substitute for OS isolation
• Size limits: bound some inputs; verify effective limits for the selected workflow

Use only data you are permitted to share with every participating service. Review execution tools and external-provider settings before enabling them.

Agent Scenarios Testing

The project includes agent-scenario tests for selected workflows and external MCP integrations. Passing them in one setup does not validate every backend, client, security property or deployment.

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        |
| - Data filtering            |
| - Analysis Tools            |
+--------------+--------------+
               |
               v
 Backend Adapters: Ollama | LM Studio | OpenRouter | Generic OpenAI
               |
               v
      Selected model backend
    (local or explicitly external)

License

ISC