Internal MCP Tools

WARNING

⚠️ Internal Use Only: This is NOT for end users installing the package via npm.

These tools are designed for maintaining and developing the QuickModel project itself. They automate common development tasks and project health checks.

Available Tools

The following tools are used for internal development.

• Scaffolding: Generate tests (generate_test) and feature skeletons.
• Documentation: Sync docs (update_docs, update_docs_content), check for missing JSDocs (check_jsdocs).
• QA: Check project health (check_project_health), coverage (get_coverage_report), API compatibility, bundle size, and CHANGELOG.
• CI / Dev workflow: Run tests (run_tests), lint (lint_check), typecheck (typecheck), pre-commit simulation (pre_commit_check), staged files (get_staged_files), and full health snapshot (project_status).
• Agent coordination: Prevent file conflicts across parallel agent sessions — cross-process safe (agent_coordinate).
• Performance: Benchmark performance (benchmark_performance).

agent_coordinate

Coordinate parallel agent work and prevent file conflicts. Multiple VS Code windows each run their own Extension Host + MCP server process; without coordination, concurrent writes to the same files can corrupt the registry or overwrite changes.

TIP

Always call check first before starting any task to see what other agents are doing.

How it works

1. Agent calls claim → declares which files it will touch → stored in tmp/agent-registry.json
2. Any other agent calling claim with overlapping files gets conflict: true immediately
3. Before modifying each file, read its current content from disk — context may be stale if another agent edited it after you loaded your context window. Adapt, merge, or skip the edit if the file changed. Never overwrite from stale context.
4. Agent calls release when done → entry deleted from the registry
5. If an agent crashes without releasing, its entry expires automatically after 2 min (TTL)

Safety mechanisms

• Glob-aware conflict detection — src/** conflicts with src/core/qm.ts; docs/en/** does NOT conflict with docs/es/**
• Implicit heartbeat — any check call with agentId automatically renews the TTL (no need to call update while actively working)
• Cross-process file lock — atomic open('wx') ensures only one of N concurrent processes writes at a time; stale locks (process crashed) auto-removed after 5 s
• force override — if a conflicting agent's updatedAt is older than ~30 s, force: true overrides its lock (assumed crashed)

Actions

Action	When to use
check	Always first. Lists all active agents and their files.
claim	Registers your task + files. Returns conflict: true if blocked.
release	Frees your claim when done or aborted.
update	Manual heartbeat for very long tasks (call every ~15 min).
purge	Force-clears a stuck claim without waiting for TTL.

Schema

{
	"action": {
		"description": "Operation: claim | check | release | update | purge"
	},
	"agentId": {
		"description": "Unique agent identifier, e.g. \"copilot-session-1\". Required for claim, release, update.",
		"optional": true
	},
	"task": {
		"description": "Short task title, e.g. \"add email transformer\". Required for claim.",
		"optional": true
	},
	"files": {
		"description": "File paths or glob patterns to lock, e.g. [\"docs-vitepress/en/**\", \"src/core/**\"]. Glob-aware overlap detection.",
		"optional": true
	},
	"ttlMs": {
		"description": "Custom TTL in milliseconds for this claim. Defaults to 120000 (2 minutes). Any check() call with agentId acts as an implicit heartbeat.",
		"optional": true
	},
	"force": {
		"description": "If true, overrides a conflicting claim whose updatedAt is older than ~30 s (likely crashed). Does NOT override a fresh active claim.",
		"optional": true
	}
}

Files on disk

tmp/
  agent-registry.json        ← active claims (JSON)
  agent-registry.json.lock   ← atomic write sentinel (cross-process mutex)
  agent-status.md            ← human-readable status table, refreshed on every operation

See also: AGENT-COORDINATE.md — full internal design document covering the ticker, lock mechanics, and test coverage map.

benchmark_performance

Run performance benchmarks for QuickModel transformations.

{
	"iterations": {
		"description": "Number of iterations for each test case",
		"optional": true
	}
}

check_api_compatibility

Check for breaking changes in the public API.

{
	"baselineFile": {
		"description": "Path to the API baseline JSON file. Defaults to api-baseline.json.",
		"optional": true
	}
}

check_bundle_size

Build the project and report the size of all generated dist/ files. Returns { status, files: [{file, bytes}][], total_bytes, summary }.

{}

check_changelog

Verify that CHANGELOG.md contains an entry for the current package.json version. Returns { found, version, excerpt, status, message? }.

{
	"projectDir": {
		"description": "Project root directory containing package.json and CHANGELOG.md. Defaults to process.cwd().",
		"optional": true
	}
}

check_jsdocs

Scan the source code for exported members that are missing JSDoc documentation.

{}

check_project_health

Run a comprehensive health check: Lint, Typecheck, and Run Tests.

{}

check_project_rules

Enforce internal project rules: use @Quick over @QType in tests, and no console.log.

{
	"targetDir": {
		"description": "Directory to scan (defaults to project root)",
		"optional": true
	}
}

check_security

Run the security test suite to verify protection against vulnerabilities (XSS, Injection, Path Traversal, etc.).

{}

generate_test

Internal tool to generate a starter test file for a source component.

{
	"sourceFile": {
		"description": "Absolute path to the source file (e.g., src/core/user.ts)"
	}
}

get_coverage_report

Run tests with coverage and report the summary.

{}

get_staged_files

List the files currently staged for commit (git diff --cached --name-only). Use this to discover which files need lint/typecheck validation before committing. Returns { passed, files[], total, summary }.

{}

lint_check

Run ESLint on a directory or specific files. Returns { passed, errors, warnings, total_errors, total_warnings, summary }.

{
	"targetDir": {
		"description": "Directory to lint (e.g. \"src/mcp/tools\"). Defaults to \"src\" if neither targetDir nor targetFiles is provided.",
		"optional": true
	},
	"targetFiles": {
		"description": "Array of specific file paths to lint (e.g. [\"src/mcp/tools/public/my-tool.ts\"]).",
		"optional": true
	}
}

list_todos

Scan source files for TODO, FIXME, HACK, and XXX comments. Returns a structured list: { file, line, type, text }[] so the agent can prioritize technical debt and outstanding work items. Defaults to scanning src/ in the project root; respects targetDir override.

{
	"targetDir": {
		"description": "Directory to scan. Defaults to src/ in the project root.",
		"optional": true
	},
	"extensions": {
		"description": "File extensions to include (default: [\".ts\", \".js\"]). E.g. [\".ts\", \".tsx\", \".js\"]",
		"optional": true
	}
}

pre_commit_check

Simulate the Husky pre-commit hook: run ESLint (--fix) and Prettier (--write) on the given files or src/. Returns { passed, eslint_errors, eslint_warnings, prettier_changed, issues, summary }. Run before committing to guarantee the hook will not reject the commit.

{
	"files": {
		"description": "List of file paths to check. Defaults to all TypeScript/JavaScript files in src/.",
		"optional": true
	}
}

project_status

Run all project health checks simultaneously: tests, lint and typecheck. Returns a consolidated snapshot with pass/fail status for each layer and a human-readable summary. Returns { passed, tests, lint, typecheck, summary }.

{}

run_tests

Run the Bun test suite (optionally filtered by a path/pattern). Parses pass/fail counts and returns structured failure details. Returns { passed, total_pass, total_fail, errors[], summary }.

{
	"pattern": {
		"description": "Optional file path or pattern to narrow test execution (e.g. \"tests/mcp/unit/internal\"). Runs the full suite when omitted.",
		"optional": true
	}
}

scaffold_feature

Generate boilerplate code for new features (transformers, tools).

{
	"type": {
		"description": "Type of feature to scaffold"
	},
	"name": {
		"description": "Name of the feature (e.g., \"email\", \"validate-user\")"
	},
	"location": {
		"description": "Target directory (relative to project root). Defaults to standard locations.",
		"optional": true
	}
}

typecheck

Run TypeScript type checking (tsc --noEmit) on src/. Returns { passed, errors, total, summary }.

{}

update_docs

Internal tool to run documentation build scripts.

{
	"action": {
		"description": "The action to perform"
	}
}

update_docs_content

Auto-generate documentation files for Tools and Transformers based on current code.

{}