diff --git a/plugins/nikolai-vysotskyi/trace-mcp/LICENSE b/plugins/nikolai-vysotskyi/trace-mcp/LICENSE new file mode 100644 index 00000000..7604c9ed --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Nikolai Vysotskyi + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/nikolai-vysotskyi/trace-mcp/README.md b/plugins/nikolai-vysotskyi/trace-mcp/README.md new file mode 100644 index 00000000..9da714dd --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/README.md @@ -0,0 +1,36 @@ +# trace-mcp + +Code intelligence for MiniMax Code: one MCP tool call returns callers, callees, and framework edges across the repo, so the agent stops reading files one by one to answer "what uses this". + +Upstream source: https://github.com/nikolai-vysotskyi/trace-mcp + +## Try it + +```text +Find every caller of `validateHostedPluginDirectory` in this repo and tell me what breaks if I change its signature. +``` + +Expected result: the agent calls the trace-mcp search and impact tools and answers with the call sites plus the blast radius, without opening each file. On an unindexed project the agent runs `trace init` once first, then answers the same way. + +## Requirements + +- Node.js 22 or newer on `PATH`. +- The `trace-mcp` executable on `PATH` (`npm install -g trace-mcp`). `mcp.json` starts it as a stdio server with no arguments. +- macOS, Linux, or Windows. +- No account, no paid service, no API key. + +## Data and network + +- The code index is built and kept on the user's machine. Source code never leaves it. +- At most one anonymous usage ping per day (version, OS, MCP client, aggregate counts; no code, no paths, no per-install identifier beyond a locally generated UUID). Turn it off with `TRACE_MCP_TELEMETRY=off`, or with `"telemetry": { "usage_ping": false }` in `~/.trace/.config.json`. +- No other network access. No credentials in the package. + +## Skills and MCP + +Skills (each directory matches its frontmatter `name`): `trace-mcp` (routing: call trace-mcp instead of reading files when exploring a codebase), `trace-mcp-refactoring` (risk assessment and cross-file renames), `trace-mcp-codemod` (bulk mechanical edits), `trace-mcp-pre-commit` (security, quality-gate, and antipattern checks before committing). + +MCP: one stdio server, `trace-mcp`. Upstream counts: 182 tools, 81 languages, 88 framework integrations. + +## License + +MIT. See [LICENSE](LICENSE). diff --git a/plugins/nikolai-vysotskyi/trace-mcp/mcp.json b/plugins/nikolai-vysotskyi/trace-mcp/mcp.json new file mode 100644 index 00000000..5bf3f43a --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/mcp.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "trace-mcp": { + "type": "stdio", + "command": "trace-mcp" + } + } +} diff --git a/plugins/nikolai-vysotskyi/trace-mcp/plugin.json b/plugins/nikolai-vysotskyi/trace-mcp/plugin.json new file mode 100644 index 00000000..2ad02a81 --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/plugin.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "trace-mcp", + "version": "3.28.0", + "description": "Framework-aware code intelligence MCP server — 88 framework integrations, 81 languages, 72.7% fewer input tokens to review a pull request, comprehension at parity", + "author": { + "name": "Nikolai Vysotskyi", + "url": "https://github.com/nikolai-vysotskyi" + }, + "license": "MIT", + "repository": "https://github.com/nikolai-vysotskyi/trace-mcp", + "homepage": "https://trace-mcp.com", + "keywords": [ + "mcp", + "code-intelligence", + "static-analysis", + "refactoring", + "semantic-search", + "code-graph", + "framework-aware" + ] +} diff --git a/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-codemod/SKILL.md b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-codemod/SKILL.md new file mode 100644 index 00000000..d3c47475 --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-codemod/SKILL.md @@ -0,0 +1,96 @@ +--- +name: trace-mcp-codemod +description: Use trace-mcp apply_codemod for any bulk mechanical change instead of repeated Edit calls. Activate whenever the same edit pattern would be applied 2+ times, across one file or many. +--- + +# trace-mcp — Codemod Workflow + +`apply_codemod` is the correct tool for any repeated mechanical change. Using `Edit` for the same pattern twice or more is a waste of tokens and is error-prone. + +## When to Use — HARD RULE + +If you are about to make the **same kind of change 2 or more times** — whether in one file or across many — stop and use `apply_codemod`. This includes: + +- Adding `async`/`await` to a set of functions +- Updating a function signature everywhere it is called +- Fixing import paths after a move +- Adding or removing keywords/decorators +- Wrapping calls in a logger, try/catch, or feature flag +- Replacing a deprecated API usage +- Any regex-replaceable refactor + +No exceptions. "It's just three edits" is still a violation — use `apply_codemod`. + +## Standard Workflow + +### 1. Preview with dry run (default) + +``` +apply_codemod({ + pattern: "oldFunction\\(", + replacement: "newFunction(", + file_pattern: "src/**/*.ts", + dry_run: true // default +}) +``` + +Review the preview: matched files, context lines, and replacement correctness. Look for false positives. + +### 2. Narrow scope when needed + +Use `filter_content` to only touch files that also contain a second marker: + +``` +apply_codemod({ + pattern: "extractNodes\\(", + replacement: "extractNodes(ctx, ", + file_pattern: "src/**/*.ts", + filter_content: "import.*extractNodes", + dry_run: true +}) +``` + +For patterns that cross line boundaries, enable multiline mode: + +``` +apply_codemod({ + pattern: "function\\s+foo\\([^)]*\\)\\s*\\{", + replacement: "async function foo() {", + multiline: true, + dry_run: true +}) +``` + +### 3. Apply the change + +``` +apply_codemod({ ..., dry_run: false }) +``` + +If more than 20 files are affected, add `confirm_large: true`. + +### 4. Reindex and verify + +- `register_edit` is not needed for codemods — `apply_codemod` handles reindexing internally. +- Run the test suite or `check_quality_gates` with `scope: "changed"`. + +## Planning Larger Changes + +For changes that span packages or require version awareness (e.g. upgrading a dependency), use `plan_batch_change` first: + +``` +plan_batch_change({ + package: "lodash", + from_version: "4.17.0", + to_version: "5.0.0" +}) +``` + +This returns an impact report with all affected files and import references. Combine it with `apply_codemod` for the actual rewrite. + +## Anti-Patterns to Avoid + +- Using `Edit` with `replace_all` for renames — use `apply_rename` (see `trace-mcp-refactoring`). +- Chaining 3–10 `Edit` calls with the same `old_string` pattern shape — use `apply_codemod`. +- Skipping the dry-run preview — always review matches first. +- Forgetting `confirm_large: true` on changes >20 files. diff --git a/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-pre-commit/SKILL.md b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-pre-commit/SKILL.md new file mode 100644 index 00000000..f615b10a --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-pre-commit/SKILL.md @@ -0,0 +1,79 @@ +--- +name: trace-mcp-pre-commit +description: Run trace-mcp security, quality-gate, and antipattern checks before committing or opening a PR. Activate when the agent is about to create a commit or pull request in a project indexed by trace-mcp. +--- + +# trace-mcp — Pre-Commit & Pre-PR Checks + +Before creating a commit or opening a pull request, run the trace-mcp validation suite. Fix any critical or high findings before committing. + +## When to Use + +- The user asks to commit, stage, or push changes +- The user asks to open a PR +- The agent has finished implementing a feature or fix and is about to hand off + +## Checklist + +### 1. Security scan + +``` +scan_security({ rules: ["all"] }) +``` + +OWASP Top-10 vulnerability scan across the changed scope. If the change touches untrusted data flows, add: + +``` +taint_analysis({}) +``` + +Trace untrusted sources to sensitive sinks (SQL, shell, file system, HTTP). + +### 2. Quality gates on the changed scope + +``` +check_quality_gates({ scope: "changed" }) +``` + +Validates complexity, coverage, duplication, and any project-configured gates on only the files you changed. + +### 3. Antipattern scan + +``` +detect_antipatterns({}) +``` + +Flags N+1 queries, eager loading, inefficient iteration, and language-specific performance footguns. + +### 4. Symbol-level diff for the PR description + +``` +compare_branches({ branch: "current" }) +``` + +Produces a symbol-level diff (functions added/removed/modified, signatures changed, exports changed). Use this as the basis for an accurate PR description instead of a raw line diff. + +### 5. Bug prediction (optional, for risky changes) + +``` +predict_bugs({}) +get_risk_hotspots({}) +``` + +Flags files where the combination of high complexity and high churn makes regressions likely. If your change touches a hotspot, add extra tests. + +## Fix or Escalate + +- **Critical / High findings:** fix before committing. Do not suppress without discussion. +- **Medium findings:** fix if cheap, otherwise note in the PR description. +- **Low / Info findings:** note in the PR description. + +## After Commit + +If the commit is part of a larger series, consider: + +``` +get_changed_symbols({ since: "" }) +``` + +to generate an accurate changelog entry grounded in the symbol graph rather than commit messages. diff --git a/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-refactoring/SKILL.md b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-refactoring/SKILL.md new file mode 100644 index 00000000..650d5344 --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp-refactoring/SKILL.md @@ -0,0 +1,86 @@ +--- +name: trace-mcp-refactoring +description: Safe refactoring workflow using trace-mcp — assess risk, find candidates, check impact, and rename symbols across all files without missing import sites or cross-file references. +--- + +# trace-mcp — Refactoring Workflow + +Use this skill whenever you are about to rename, restructure, extract, or otherwise refactor code in a project indexed by trace-mcp. The goal is to never break cross-file references and never guess at what is affected. + +## When to Use + +- Renaming a class, function, method, variable, or file +- Extracting a function or method +- Restructuring a module or splitting a file +- Changing a function signature +- Any change that touches more than one call site + +## Refactoring Workflow + +### 1. Assess before touching anything + +``` +assess_change_risk({ file_path: "src/foo.ts" }) +# or +assess_change_risk({ symbol_id: "" }) +``` + +This returns the risk level of the target change based on churn, complexity, fan-in/fan-out, and test coverage. Use it to decide whether to proceed, add tests first, or split the change. + +### 2. Find what actually needs refactoring + +``` +get_refactor_candidates() +``` + +Do not guess. This surfaces high-complexity, high-churn, and anti-pattern-laden symbols that are the real refactor targets. + +### 3. Know what will break + +``` +get_change_impact({ symbol_id: "" }) +``` + +Returns the reverse-dependency graph: every file, symbol, and test that depends on the target. Review this list before editing. + +### 4. Quantify complexity + +``` +get_complexity_report({ file_path: "src/foo.ts" }) +``` + +Gives you a baseline so you can verify the refactor actually reduced complexity. + +## Renaming a Symbol — MANDATORY Flow + +**Never** rename with `Edit` and `replace_all`. It silently misses import sites, re-exports, type references, and cross-file usages. + +``` +# 1. Collision detection first +check_rename({ symbol_id: "", target_name: "newName" }) + +# 2. Apply rename across ALL files (definition + every reference) +apply_rename({ symbol_id: "", new_name: "newName" }) +``` + +`apply_rename` updates the definition, imports, re-exports, call sites, JSX usages, and tests in one atomic operation. + +## Extracting a Function + +``` +extract_function({ + file_path: "src/foo.ts", + start_line: 42, + end_line: 67, + new_name: "computeTotals" +}) +``` + +Let trace-mcp handle the variable capture analysis — manual extraction routinely misses closure variables. + +## After the Refactor + +1. `register_edit` on each edited file to reindex +2. `get_complexity_report` again to confirm the reduction +3. `get_tests_for` the changed symbols — run them +4. `check_quality_gates` with `scope: "changed"` to verify no regressions diff --git a/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp/SKILL.md b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp/SKILL.md new file mode 100644 index 00000000..9c1f5860 --- /dev/null +++ b/plugins/nikolai-vysotskyi/trace-mcp/skills/trace-mcp/SKILL.md @@ -0,0 +1,88 @@ +--- +name: trace-mcp +description: Use trace-mcp tools for code navigation, impact analysis, and framework-aware queries instead of Read/Grep/Glob/Bash. Activate whenever the agent needs to explore, understand, or modify a codebase that has trace-mcp indexed. +--- + +# trace-mcp — Code Intelligence Routing + +trace-mcp is a framework-aware code intelligence MCP server. It exposes 182 tools that return semantic, structured results over a cross-language dependency graph. When trace-mcp is available, it is almost always cheaper and more accurate than native file tools. + +## When to Use + +Activate this skill whenever you need to: +- Find a function, class, method, route, component, or any symbol +- Understand a file, module, or feature before editing +- Determine what breaks if you change something +- Trace a request flow, call graph, or data flow +- Audit architecture, dead code, tests, or security + +**Do not use** `Read`, `Grep`, `Glob`, or shell `ls`/`find`/`cat`/`head`/`tail` for exploring source code (`.ts`, `.js`, `.py`, `.php`, `.go`, `.rb`, `.java`, etc.). Use trace-mcp tools instead. Native tools stay allowed only for non-code files (`.md`, `.json`, `.yaml`, configs) or immediately before an `Edit` on a known file. + +## Start-of-Session Checklist + +1. `get_project_map` with `summary_only=true` — orient yourself to the project structure +2. `get_task_context` with `task: ""` — gather all relevant code in a single call instead of chaining `search` → `get_symbol` → `Read` + +## Decision Matrix + +| Task | trace-mcp tool | Instead of | +|---|---|---| +| Find a symbol by name | `search` | Grep | +| Understand a file before editing | `get_outline` | Read (full file) | +| Read one symbol's source | `get_symbol` | Read (full file) | +| Multiple symbols + shared imports | `get_context_bundle` | chained `get_symbol` | +| What breaks if I change X | `get_change_impact` | guessing | +| Who calls this / what does it call | `get_call_graph` | Grep | +| All usages of a symbol | `find_usages` | Grep | +| Implementations of an interface | `get_implementations` | Grep / ls | +| Classes implementing X | `search` with `implements` filter | Grep | +| Tests for a symbol or file | `get_tests_for` | Glob + Grep | +| Project overview | `get_project_map` (summary_only) | Bash ls/find | +| Context for a task | `get_task_context` / `get_feature_context` | reading many files | +| HTTP request flow | `get_request_flow` | reading route + controller files | +| DB model relationships | `get_model_context` | reading model + migrations | +| Component tree | `get_component_tree` | reading component files | +| Circular dependencies | `get_circular_imports` | manual tracing | +| Dead code / dead exports | `get_dead_code` (`mode: "exports_only"`) | Grep for unused | +| Project health / coverage gaps | `self_audit` | manual inspection | +| Complexity / hotspots | `get_complexity_report` / `get_risk_hotspots` | guessing | + +## Token-Efficiency Rules + +1. **Batch independent queries.** Use `batch` when you need 2+ independent tool calls: + ``` + batch({ calls: [ + { tool: "get_outline", args: { path: "src/foo.ts" } }, + { tool: "get_outline", args: { path: "src/bar.ts" } }, + { tool: "search", args: { query: "handleRequest", kind: "function" } } + ]}) + ``` +2. **Never read the same file twice.** Use `get_outline` once, then `get_symbol` for specific pieces. +3. **Prefer `get_context_bundle`** over chained `get_symbol` calls — it deduplicates shared imports. +4. **Read-before-Edit optimization.** When you must `Read` a file to edit it: + - Call `get_outline` first to find the line range of the target symbol. + - Read only that range with `offset` + `limit`. Never read a 500-line file to edit 5 lines. +5. **Do not delegate code exploration to subagents.** Agent subprocesses carry ~50k tokens of overhead before doing anything. Use trace-mcp tools in the main conversation instead. + +## After Editing a File + +- Call `register_edit` with the edited `file_path` to reindex just that file and invalidate caches. This is much lighter than a full `reindex` and keeps subsequent queries accurate. +- If the response includes `_duplication_warnings`, review the referenced symbols — you may be duplicating existing logic. +- Do **not** re-read the file to "verify" the edit. The `Edit` tool already confirmed success. + +## Before Creating New Symbols + +- Call `check_duplication` with `{ name, kind }` to verify no similar symbol exists. Prevents reinventing existing logic. + +## Health Checks (Once Per Session) + +- `audit_config` — stale references in CLAUDE.md / settings +- `self_audit` — dead exports, untested code, hotspots +- `get_tech_debt` — per-module tech-debt grades +- `get_optimization_report` — detects repeated reads, Bash grep usage, missed trace-mcp opportunities + +## Related Skills + +- `trace-mcp-refactoring` — safe refactoring workflow (risk assessment → rename → impact check) +- `trace-mcp-codemod` — bulk mechanical changes via `apply_codemod` +- `trace-mcp-pre-commit` — security, quality-gate, and antipattern checks before commit