majrooo-mcp-devkit — MCP DevKit: Safe Commands + Refactoring Tools

Repository Access: PUBLIC
Version: 0.2.1 · Tests: 354 passing · License: GPL-3.0-or-later

MCP server that provides safe command execution and code refactoring tools for Cline/Claude Desktop.

Tools

run_safe_command

Execute a shell command restricted to the active project root. Dangerous commands and writes outside the active root are automatically blocked. This is the default tool — always use this first.

run_destructive_command

Execute a potentially dangerous command with explicit user confirmation. Only use when run_safe_command blocked the command and the user explicitly agreed after being informed of the specific risk.

read_log_slice

Read a portion of a previously saved log file. Use this instead of re-running a command with higher maxLines. Files are read directly via Node.js (not through the shell), so it also works for truncated logs in os.tmpdir().

list_allowed_roots

Return the registered roots configuration: the primary project (MCP_PROJECT_ROOT), all allowed roots (MCP_EXTRA_ROOTS, including globs), the concrete existing project directories under them (usable as cwd), and whether MCP_BLOCK_CROSS_ROOT_READS is enabled. Projects with a friendly name are returned as { path, name } — in that case you can also use the name as cwd. Call this before working in any non-primary project to discover the exact cwd value to use. Runs no commands — it only reads configuration and lists directories.

No parameters.

resolve_cwd

Verify whether a path (or a friendly project name from MCP_PROJECT_NAMES) is inside the allowed roots and get the exact cwd to use for commands. Pass the path you want to work in (e.g. your workspace folder) instead of guessing.

On success returns { ok: true, cwd, matchedRoot, exists, name? }; on failure { ok: false, error, roots }. exists tells whether the resolved directory actually exists on disk (relative cwd values are resolved against the primary project). Runs no commands — it only validates configuration.

run_command_grep

Execute a command and return only lines matching a pattern (case-insensitive regex). Use instead of run_safe_command when you only care about specific lines (e.g., errors in build output). This is the replacement for Unix grep on Windows — filtering happens in-process, so grep/head/tail are not needed.

universal_find_references

Find all occurrences of a symbol across a workspace. Returns structured output with file, line, column, context, and optional role annotations. Use this before any refactoring session to understand what will break when a symbol is renamed or moved.

Multi-root search (no cwd): every registered root is searched. A root nested inside another root is pruned — the outer root already covers it — and files are deduplicated by resolved real path, so the same match is never listed or counted twice. When more than one root is searched, the report states them and, for each file group, the root its relative path is based on:

Symbol: ColAlign
Total matches: 28
Searched roots (3):
  - D:\W\TS
  - d:\Users Data\jox\My Documents\Python
  - d:\Users Data\jox\My Documents\Rust
Duplicates skipped: 2 (same file reachable through a nested root)

pixel-blaster-engine/engine_bevy/src/lib.rs  (relative to d:\Users Data\jox\My Documents\Rust)
  Line 72:12 [usage] — pub use ui_panel::{

A path like project/src/lib.rs therefore always belongs to exactly one root — it is never a second copy of src/lib.rs. With an explicit cwd only that root is searched and the report keeps its compact form (path/file.rs:).

extract_code_block

Read the full text of a function, struct, class, or method from a file. Returns precise line range + content. Includes leading annotations (#[derive], @decorator, /// doc comments). String/comment-aware bracket matching prevents false depth counts from braces inside strings or comments.

split_file_by_declarations

Split a large file into multiple smaller files based on top-level declarations. Optionally generates a combining file (mod.rs / index.ts / __init__.py). Use dryRun: true (default) to preview the layout before writing.

batch_apply_edits

Apply multiple file edits with partial rollback on failure. Validates all edits first — if any search string is not found or matches multiple times (without replaceAll), NO files are modified. On failure during application, only files modified by the failed edit and subsequent edits are reverted; earlier successful edits are preserved. Same-file chain failures revert the entire file. Relative paths without cwd are resolved against the primary root; if the file doesn't exist there, all other registered roots are searched automatically (unique match → use it; multiple matches → error with instructions to specify cwd).

Response (explicit outcome)

The result text starts with a one-line message followed by the JSON payload:

{
  "dryRun": false,
  "totalEdits": 3,
  "validated": 3,
  "appliedEdits": 2,
  "written": ["D:\\proj\\a.rs", "D:\\proj\\b.rs"],
  "message": "Applied 2 of 2 edit(s) to 2 file(s) — all changes are on disk.",
  "preview": [{ "file": "D:\\proj\\a.rs", "action": "edit", "matchCount": 1, "applied": true }]
}

Key fields:

On failure the response also carries error, failedAt, reason (validation_failed | write_failed), reverted (files rolled back) and nothingWritten (true = this run left no change on disk at all — either nothing was ever written, or everything written was rolled back). Validation failure example:

VALIDATION FAILED on edit #2 of 3 — NO edits were written to disk (validation-first: nothing is written until every edit validates). Reason: search string not found in D:\proj\b.rs

Edits that were never evaluated get an explicit action: "error" preview entry (not evaluated — batch stopped at edit #N), so preview always maps 1:1 to the edits array. When validation fails on a file that already had a successfully applied edit in the same run (chained edits), the response switches to partial rollback: N edit(s) kept in … ; M file(s) reverted […]. If every write from the run was rolled back (e.g. all edits chained on one file), nothingWritten stays true and the message says NO net changes were left on disk: N edit(s) had been written and M file(s) were rolled back […] — an honest distinction between "never wrote" and "wrote, then undid".

generate_module_skeleton

Generate a new module file with extracted symbols from a source file. Returns error with unknownSymbols list if any symbols are not found.

verify_refactor_safety

Semantic diff between old and new code. Catches accidental deletions before compilation. Checks: function count, signatures, export count, imports, comment ratio. Intentionally conservative — renames appear as errors requiring explicit confirmation.

report_tool_feedback

Report a bug, improvement, or feature request about a tool of this server (see list_tools). Writes structured feedback to .mcp/FEEDBACK.md (project-specific, gitignored). Entries are idempotent — duplicate reports are skipped.

The tool name is validated against this server's tool registry: an unknown name is rejected (nothing is written) with a "did you mean …?" suggestion, so feedback about another client's built-in tool no longer lands in this log. For a missing-capability report about the server as a whole, pass allowUnknownTool: true.

list_feedback

List feedback entries from .mcp/FEEDBACK.md. Optionally filter by type, tool name, or status. Use this to check existing feedback before creating new entries.

close_feedback

Close an existing feedback entry by ID — sets status to "closed" and optionally adds resolution text. Use this to mark feedback items as resolved after fixing them.

Closing also moves every closed entry out of the active log into .mcp/FEEDBACK_ARCHIVE.md, so FEEDBACK.md keeps holding only open items and stays small. The move is append-first (archived before removed) and idempotent, and it self-heals: entries closed before this behaviour existed are migrated along with the next close. Read them back with list_feedback + archived: true.

Closed entries are stored in two files:

list_tools

List all available MCP tools with descriptions. Use this to discover tools before starting a task. Filterable by category.

help_tool

Get detailed help for a specific MCP tool — parameters, types, defaults, and description.

Related MCP server: MCP Workspace Server

Supported Languages

The refactoring tools support four languages for declaration parsing, symbol extraction, and role detection:

Tools without a language parameter (batch_apply_edits, extract_code_block) are language-agnostic — they operate on plain text and work with any language.

Note: Rust has been tested in production refactoring scenarios. Other languages are structurally supported but have not been tested against real-world codebases yet.

Configuration

The server supports one instance, many projects. Projects are selected per command via the cwd parameter; the active project also acts as the "lockbox" for write/read checks.

Entry forms supported in both variables:

• Plain path D:\W\TS\majrooo-mcp-devkit → prefix: the directory itself and everything below it are allowed. Registering D:\W covers all projects under it.

• Glob D:\W\TS\* (*, **, ?) → any path matching the pattern (and its subtree) is allowed.

Example — one instance, many projects, with friendly names:

{
  "mcpServers": {
    "majrooo-mcp-devkit": {
      "command": "node",
      "args": ["D:\\W\\TS\\majrooo-mcp-devkit\\build\\index.js"],
      "env": {
        "MCP_PROJECT_ROOT": "D:\\W\\TS\\majrooo-mcp-devkit",
        "MCP_EXTRA_ROOTS": "D:\\W;D:\\python",
        "MCP_PROJECT_NAMES": "D:\\W\\TS\\cb=ZbaľSa;D:\\W\\TS\\nase-zasoby=Naše zásoby"
      }
    }
  }
}

MCP_PROJECT_NAMES maps a real project path to a readable name. This is useful when the folder name had to be shortened (e.g. Gradle path-length limits) or the project was renamed. The name can be used directly as cwd (e.g. "cwd": "ZbaľSa"), and list_allowed_roots will show such projects as { "path": "D:\\W\\TS\\cb", "name": "ZbaľSa" }.

Switching projects is done via the cwd parameter, never via cd in the command. cd .., cd ~, cd C:\..., and Windows cd /d D:\... are always rejected.

Running tests / long commands (the anti-freeze workflow)

Never run test suites (jest/npm test), typecheck or builds through the Cline built-in terminal — it has no timeout and can freeze the whole window. Use the MCP tools instead:

1. Always pass the project's cwd (or friendly name, e.g. "cwd": "ZbaľSa").

2. To filter output (e.g. jest summary), use run_command_grep — filtering happens in-process, so cmd /c "... | findstr ... & echo DONE" is not needed and discouraged:

{
  "tool": "run_command_grep",
  "cwd": "ZbaľSa",
  "command": "npx jest src/app/__tests__/catalog.test.tsx 2>&1",
  "pattern": "Tests:|Test Suites:|FAIL|PASS|✕",
  "timeoutMs": 180000
}

3. For full output use run_safe_command with a small maxLines — the full output is saved to a temp log for read_log_slice:

{
  "tool": "run_safe_command",
  "cwd": "ZbaľSa",
  "command": "npm run typecheck 2>&1",
  "maxLines": 100,
  "timeoutMs": 180000
}

4. If a run exceeds 10 minutes, run it in the background, redirect to a log file, and poll the log via run_command_grep — do not watch live terminal output.

Typical workflow

1. Call list_allowed_roots to see the primary root, the allowed roots (including globs), and the concrete projects under them.

2. If you need to confirm a specific path, call resolve_cwd with your workspace folder — it returns the exact cwd to use and the matched root.

3. If the task targets a project other than the primary one, pass the resolved path as cwd on every command (run_safe_command, run_destructive_command, run_command_grep).

4. Otherwise, omit cwd — commands run in the primary root.

Relative paths: File-based refactoring tools (batch_apply_edits, extract_code_block, split_file_by_declarations, generate_module_skeleton) resolve relative paths against the primary root when cwd is omitted. If the file doesn't exist in the primary root (or in the cwd root when cwd is provided), all other registered roots are searched automatically — a unique match is used directly, while multiple matches produce an error with instructions to specify cwd.

Safety Mechanisms

Limitations

The dangerous-pattern blacklist and the write/read target checks are best-effort layers, not security guarantees. Shell features (variables, command substitution, encoding) can bypass them. For production isolation use Docker/VM sandboxing.

Windows Notes

• Commands run through cmd.exe. Unix-only tools (grep, head, tail, ...) do not exist — the server returns a friendly error with alternatives instead of a raw "not recognized" blob.

• Use run_command_grep instead of grep, and read_log_slice or PowerShell (Get-Content out.log -TotalCount 30) instead of head.

• Long-running processes (dev server, watch mode) exceed the 60s timeout — use the built-in terminal for those.

Output normalization

On Windows the server automatically prefixes commands with chcp 65001 > NUL && so the child process emits UTF-8 instead of the legacy OEM codepage (which would otherwise decode into U+FFFD replacement characters, e.g. around thousands separators in dir output). ANSI color codes from tools like vitest/jest are stripped as a fallback (NO_COLOR=1 / FORCE_COLOR=0 are also injected into the environment), and read_log_slice cleans ANSI codes defensively when reading older logs.

Redirected output reporting

When a command redirects its output into a file (npm test > test.log 2>&1, >> out.log, 2> err.log, ...), the response reports where the output went and shows the tail of the written file instead of an empty response or a bare Command failed: .... On failure the response also includes the exit code (or timeout/signal) and the captured stdout/stderr. Discard targets (NUL, /dev/null), wildcard patterns and fd-duplication tokens (2>&1, >&-) are skipped; very large files are read only from the end.

Agent Behavior Rules

The .clinerules file in the project root defines how AI agents should use these tools:

1. Always try run_safe_command first — never start with run_destructive_command.

2. run_destructive_command only after explicit user confirmation in the current conversation — general consent ("do what you need") is not sufficient.

3. Never bypass directory_escape rejections — no chaining, absolute paths, or cwd tricks. Use the cwd parameter to pick a registered project.

4. Prefer run_command_grep / read_log_slice over increasing maxLines for long output, and instead of Unix grep/head/tail.

5. Use the built-in terminal only for quick interactive checks (e.g., git status). Large-output commands (npm install, build, tests) must go through run_safe_command.

6. Run tests before reporting task as complete.

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

Development

npm run build    # Compile TypeScript
npm test         # Run unit tests
npm run test:watch  # Watch mode

The server communicates over STDIO using the Model Context Protocol.