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

Repository Access: PUBLIC
Version: 0.1.0 · Tests: 269 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.

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 atomically with rollback on failure. Validates all edits first — if any search string is not found or matches multiple times (without replaceAll), NO files are modified.

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 any MCP tool. Writes structured feedback to .mcp/FEEDBACK.md (project-specific, gitignored). Entries are idempotent — duplicate reports are skipped.

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.

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.

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.

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.