# io.github.abhiyoheswaran1/projscan (npm · projscan)

Agent-first MCP. 11 AST adapters, 12 named languages, 51 tools, mission outcomes. Local.

- Trust score: 78/100 (medium)
- Change this week: +27
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `projscan`: 78/100 (this document), [markdown](https://verifymcp.io/servers/abhiyoheswaran1-projscan/projscan.md), [page](https://verifymcp.io/servers/abhiyoheswaran1-projscan/projscan)

## Channel facts

- Registry: `npm`
- Package: `projscan`
- Version: `5.0.3`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 88/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 42 of 42 dependencies flagged as unhealthy (42 deprecated).
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to abhiyoheswaran1/projscan).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 14 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 81/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 9158 tokens (~160/item across 57 items; 51 tools + 6 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 40/100
  - Spec-recency check failed: implements MCP spec 2025-03-26; the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add abhiyoheswaran1-projscan -- npx -y projscan
```

### Codex

```bash
codex mcp add abhiyoheswaran1-projscan -- npx -y projscan
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "abhiyoheswaran1-projscan": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "projscan"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add abhiyoheswaran1-projscan --command npx --arg -y --arg projscan
```

### Hermes

```yaml
mcp_servers:
  abhiyoheswaran1-projscan:
    command: "npx"
    args: ["-y", "projscan"]
```

### Other

```json
{
  "mcpServers": {
    "abhiyoheswaran1-projscan": {
      "command": "npx",
      "args": [
        "-y",
        "projscan"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 78, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 77, +72)

- [security improvement] Provenance: unverified → pass
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [security] The attested source repository moved: abhiyoheswaran1/projscan
- [functional regression] MCP protocol: unverified → fail
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → 0.00
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] Schema quality: unverified → 100
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: MIT

### 2026-08-01 (score 5, −28)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 33, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-27 (score 51)

First indexed and scored.

## MCP tools (51)

### `projscan_analyze` (~69 tokens)

Run a full projscan analysis of the project: languages, frameworks, dependencies, issues, and health score. Use this to understand a codebase before making changes.

Input parameters:

- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.

### `projscan_doctor` (~189 tokens)

Run a health check on the project. Returns a 0-100 score, letter grade, and the list of issues (linting, formatting, tests, security, architecture). Pass `max_cost_tokens` (1.5+) for adaptive shaping: <3000 returns verdict-only (score + counts), <7000 returns a summary (top issues), otherwise full.

Input parameters:

- `max_cost_tokens` (number): 1.5+ — adaptive shape budget. <3000 returns verdict-only (score + grade + per-severity counts); <7000 returns a summary (top-5 issues by severity, no descriptions); otherwise the full issue list. Dif…
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.

### `projscan_hotspots` (~300 tokens)

Rank files by risk using git churn × AST cyclomatic complexity × open issues. Returns the most dangerous files to touch. Each hotspot includes `cyclomaticComplexity` (null for non-AST languages, where line count is used as fallback). Supports cursor-based pagination: pass the `nextCursor` from a previous response back as `cursor` to fetch the next page. Pass `view: "functions"` to flatten results into the top-N riskiest individual functions across all hotspots, ranked by per-function CC.

Input parameters:

- `cursor` (string): Opaque cursor from a previous response. Omit for the first page.
- `limit` (number): Cap on total hotspots ranked (default 100). For paging the returned set, use `page_size` + `cursor` instead.
- `max_tokens` (number): Cap response to roughly this many tokens.
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope hotspots to one package only.
- `page_size` (number): Items per page (default 50, max 500).
- `since` (string): Git history window. Examples: "12 months ago", "2024-01-01". Default: "12 months ago".
- `view` (string): Output shape. "files" (default) returns ranked hotspot files. "functions" returns the top-N individual functions across all hotspots, sorted by per-function CC desc.

### `projscan_file` (~85 tokens)

Drill into a single file: purpose, imports, exports, churn/risk/ownership, related health issues, AST cyclomatic complexity, coupling (fan-in / fan-out), and per-function CC ranked by complexity. Use this after projscan_hotspots when deciding how to approach a specific risky file.

Input parameters:

- `file` (string, required): Path to the file relative to the project root.

### `projscan_structure` (~44 tokens)

Return the project directory tree with file counts.

Input parameters:

- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.

### `projscan_dependencies` (~73 tokens)

Analyze package.json dependencies and return counts and risks (deprecated packages, wildcard versions, etc.). In a monorepo, returns aggregated totals plus a `byWorkspace` breakdown; pass `package` to scope to one workspace.

Input parameters:

- `package` (string): Optional. Workspace package name to scope analysis to one workspace only.

### `projscan_outdated` (~143 tokens)

Compare declared vs installed versions of every package. Reports drift (patch/minor/major). Workspace-aware in monorepos: each package.json is scanned, and each entry is tagged with the workspace it came from. Pass `package` to scope to a single workspace. Offline - does not hit the npm registry. Supports cursor pagination.

Input parameters:

- `cursor` (string): Opaque cursor from a previous response.
- `max_tokens` (number): Cap response size.
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.
- `page_size` (number): Items per page (default 50).

### `projscan_audit` (~126 tokens)

Run `npm audit` and return a normalized summary of vulnerabilities (critical / high / moderate / low / info). Requires package-lock.json. Supports cursor pagination on the findings array. Pass `package` in a monorepo to scope findings to direct deps of one workspace package.

Input parameters:

- `cursor` (string): Opaque cursor from a previous response.
- `max_tokens` (number): Cap response size.
- `package` (string): Optional. Workspace package name to scope audit findings to one workspace only.
- `page_size` (number): Items per page (default 50).

### `projscan_upgrade` (~125 tokens)

Preview the impact of upgrading a package: npm semver drift, breaking-change markers from a local CHANGELOG, Python manifest/lockfile declarations, and files in your repo that import it. Offline by default; pass `check_registry: true` (1.3+) to fetch the actual latest npm version.

Input parameters:

- `check_registry` (boolean): 1.3+ — when true, fetch the latest version from registry.npmjs.org (network-required). Default false: latest is treated as the installed version.
- `package` (string, required): Name of the package to preview.

### `projscan_coverage` (~137 tokens)

Join test coverage with hotspot risk. Returns files ranked by "risk × uncovered fraction" - the scariest untested files. Requires a coverage file at coverage/lcov.info, coverage/coverage-final.json, or coverage/coverage-summary.json.

Input parameters:

- `limit` (number): How many entries to return (default: 30, max: 200).
- `max_tokens` (number): Cap the response size to roughly this many tokens (~4 chars/token). Truncates the entries array to fit.
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.

### `projscan_semantic_graph` (~194 tokens)

The code graph, two ways. With no `query`: returns the stable v3 semantic graph (file/function/package/symbol nodes plus imports, exports, defines, and calls edges). With `query`: answers one cheap, targeted question instead of serializing the whole graph — who imports a file, what a file imports/exports, where a symbol is defined, or which files import a package. (The targeted mode subsumes the former projscan_graph tool, removed in 4.0.)

Input parameters:

- `max_edges` (number): Full-graph mode only. Maximum graph edges to return. Default 25000.
- `max_nodes` (number): Full-graph mode only. Maximum graph nodes to return. Default 10000.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `query` (object): Optional. Ask one targeted question instead of returning the whole graph.

### `projscan_coupling` (~208 tokens)

Per-file coupling metrics (fan-in, fan-out, instability) and circular-import cycles, derived from the AST code graph. Use `direction` to focus the result: "all" returns every file sorted by fan-in; "high_fan_in" / "high_fan_out" sort accordingly; "cycles_only" returns just the files participating in import cycles. Cycles are reported separately as strongly-connected components of size >= 2.

Input parameters:

- `direction` (string): Filter/sort applied to `files`. Default "all".
- `file` (string): Optional. When set, the response includes only this file's coupling row (cycles list still returned in full).
- `limit` (number): Max file rows returned (default 25, max 500).
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope coupling rows to one package only.

### `projscan_workspaces` (~82 tokens)

List monorepo workspace packages (npm/yarn workspaces, pnpm-workspace.yaml, Nx/Turbo/Lerna fallback). Returns one row per package with name, relative path, and version. Use the package `name` as the `package` argument on projscan_hotspots / projscan_coupling to scope those tools to a single package.

### `projscan_pr_diff` (~183 tokens)

Structural (AST) diff between two refs - what changed in exports, imports, call sites, cyclomatic complexity, and fan-in. Not a text diff: this surfaces the symbols and edges that an agent reviewing a PR actually cares about. Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD. Spins up a throwaway git worktree at the base ref to get a clean second graph.

Input parameters:

- `base` (string): Base ref (branch, tag, sha). Default: origin/main, falling back to main/master/HEAD~1.
- `head` (string): Head ref. Default: HEAD.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.

### `projscan_review` (~492 tokens)

One-call PR review. Combines projscan_pr_diff + per-changed-file risk score + new/expanded import cycles + risky function additions + dependency changes, plus a verdict ("ok" | "review" | "block") with a one-line summary. Use when an agent is asked "is this PR safe to merge?" Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD. Pass `max_cost_tokens` (1.5+) to get a budget-shaped response: <3000 returns verdict-only, <7000 returns a summary, otherwise the full review. 1.9+: pass `intent` (a free-text PR description like "refactor auth middleware" or "docs: fix codex setup") to get an intent-grounded review — each finding is labelled expected / unexpected / out-of-scope against the stated intent. Verdict is unchanged; this is an extra narration layer.

Input parameters:

- `base` (string): Base ref (branch, tag, sha). Default: origin/main, falling back to main/master/HEAD~1.
- `head` (string): Head ref. Default: HEAD.
- `intent` (string): 1.9+ — free-text description of what the PR is trying to do. projscan parses this into an action (feature / fix / refactor / perf / test / docs / chore / remove) plus scope tokens, then labels every…
- `max_cost_tokens` (number): 1.5+ — adaptive shape budget. Tool picks a tier based on this value: <3000 verdict-only, <7000 summary, otherwise full. Differs from `max_tokens` (post-hoc truncation): the tool reshapes the response…
- `max_tokens` (number): Cap the response via post-hoc array trimming.
- `package` (string): Optional. Workspace package name to scope all sections of the review to a single package.

### `projscan_fix_suggest` (~202 tokens)

Given an issue id (from projscan_doctor / projscan_analyze) OR a file + rule pair, return a structured action prompt: headline, why it matters, where to change, one-paragraph instruction the agent can execute, optional suggested test. Rule-driven; no LLM inside projscan. Use this to close the diagnose -> fix loop.

Input parameters:

- `file` (string): File path (repo-relative). Required when no `issue_id` is given - combined with `rule` to synthesize a fix request.
- `issue_id` (string): Issue id from a previous projscan_doctor / projscan_analyze response.
- `rule` (string): Rule / issue-id prefix (e.g. "unused-dependency", "cycle-detected"). Required when no `issue_id` is given.
- `severity` (string): Optional. When synthesizing via file+rule, sets the severity for the suggestion. Default: warning.

### `projscan_explain_issue` (~96 tokens)

Deep-dive on a single open issue: severity, surrounding code excerpt, other issues touching the same file, similar fixes from git log (commit messages that mention this rule), and the structured fix-action prompt. Use when an agent needs more context than projscan_doctor gives - typically before applying a fix.

Input parameters:

- `issue_id` (string, required): Issue id from a previous projscan_doctor / projscan_analyze response.

### `projscan_impact` (~280 tokens)

Transitive blast-radius analysis. Given a `file` (repo-relative path), returns every file that transitively imports it, ranked by BFS distance (1 = direct importer). Given a `symbol` (export name), returns the symbol's definition file(s), the files that directly call it, and their transitive importers. Use this BEFORE renaming or deleting to see what breaks. Cycle-safe; depth-bounded by `max_distance` (default 10).

Input parameters:

- `cross_repo` (boolean): 1.6+ — when true, also fold in callers from sibling repos registered via `projscan workspace add`. Each cross-repo file is annotated with its repo name. Symbol-mode only; file-mode cross-repo require…
- `cursor` (string): Opaque cursor from a previous response.
- `file` (string): Repo-relative file path. Mutually exclusive with `symbol`.
- `max_distance` (number): Maximum BFS hops from the target. Default 10. Reports `truncated: true` when exceeded.
- `max_tokens` (number): Cap response to roughly this many tokens.
- `page_size` (number): Items per page (default 50, max 500).
- `symbol` (string): Symbol (export) name. Mutually exclusive with `file`.

### `projscan_search` (~309 tokens)

Ranked search across the project. Lexical (BM25) by default; optional semantic (vector) and hybrid (RRF fusion) modes available when the @xenova/transformers peer dependency is installed. Scope controls what to search: "auto"/"content" (ranked content matches with excerpts), "symbols" (exported names), "files" (path substring).

Input parameters:

- `limit` (number): Max matches returned (default 30).
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `mode` (string): "lexical" (default, BM25) | "semantic" (embeddings, requires peer dep) | "hybrid" (BM25 + semantic via reciprocal rank fusion). Ignored for "symbols" and "files" scopes.
- `package` (string): Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.
- `query` (string, required): Search string. Multi-word queries are treated as OR across BM25 terms; semantic mode embeds the full query.
- `scope` (string): What to search over: "auto" (= content), "symbols", "files", "content".
- `sub_file` (boolean): 0.15.0+: when true, build the semantic index per-function instead of per-file (where the language adapter extracted functions). Hits return a `function` field with name + line range. Ignored in lexic…

### `projscan_session` (~171 tokens)

Inspect the durable cross-invocation session: which files have been touched in this session, by what (tool result / fs watch / explicit), and the event log. Use to coordinate across multi-agent setups without re-querying git.

Input parameters:

- `action` (string): Subaction. Default "current" returns session metadata. "touched" returns the touched-file list. "events" returns the event log. "reset" discards the current session and starts a fresh one.
- `cursor` (string): Opaque cursor for pagination (touched / events lists).
- `page_size` (integer): Page size for paginated lists. Default 50, max 500.
- `source` (string): "touched" only — restrict to files added by this source. Omit for all sources.

### `projscan_memory` (~272 tokens)

Inspect or prune the local Project Memory: which analyzer rules have been surfacing repeatedly without being addressed, and what to do about them. Use when an agent wants to know "what is this project tolerating and could quiet down via .projscanrc?"

Input parameters:

- `action` (string): Subaction. "current" returns aggregate counts. "stable" returns long-running rules with a config-snippet suggestion. "runs" returns every tracked rule. "accepted" (1.5+) returns files Project Memory…
- `file` (string): "forget-hotspot" only — the repo-relative path to drop from hotspot memory.
- `rule` (string): "forget" only — the rule id to drop from memory.

### `projscan_workspace_graph` (~163 tokens)

Cross-repo intelligence over sibling repos registered via `projscan workspace add`. Use to answer "what other repos import this file/symbol?" or "what symbols are shared across the workspace?" Read-only.

Input parameters:

- `action` (string): Subaction. Default "list" returns the registered repos with file counts. "graph" returns every symbol exported by ≥ 2 repos. "file_importers" needs `file` (and optionally `repo`); returns the cross-r…
- `file` (string): "file_importers" only — repo-relative path inside the source repo (e.g. "src/auth.ts").
- `repo` (string): "file_importers" only — registered repo name (defaults to the cwd if registered).

### `projscan_apply_fix` (~179 tokens)

Apply a mechanical fix for an open issue (1.6+). Default is dry-run; pass confirm:true to write. Every applied change records a rollback id usable via action:'rollback'. Mechanical templates only — semantic rewrites and codemods stay agent-driven.

Input parameters:

- `action` (string): Default "apply". Pass "rollback" with `rollback_id` to reverse a previous apply.
- `confirm` (boolean): "apply" only — when true, write to disk. When false (default), return the would-change list without writing (dry-run).
- `issue_id` (string): "apply" only — the issue id to fix (from projscan_doctor / projscan_analyze). Required for action:"apply".
- `rollback_id` (string): "rollback" only — the id from a prior apply's ApplyResult.

### `projscan_taint` (~183 tokens)

Source-to-sink reachability over the per-function call graph (1.6+). Surfaces "this function reads `process.env`/`req.body` and calls `exec`/`eval`/raw SQL" patterns. Defaults cover common JS / Python sources + sinks; project-specific names go in `.projscanrc.json` `taint`.

Input parameters:

- `max_flows` (number): Cap the number of flows returned (most-direct first; same-function flows lead). Default 50.
- `sinks` (array): Additional sink names to merge with the defaults. Useful for project-specific dangerous wrappers like `runRawSql` or `dangerouslyEval`.
- `sources` (array): Additional source names to merge with the defaults. Match is by bare name (rightmost identifier), so `customSecretReader()` adds the literal "customSecretReader".

### `projscan_dataflow` (~193 tokens)

Return v3 dataflow risks over the function graph. Includes legacy direct/propagated taint projections plus bridge-helper risks where a wrapper calls both a source reader and a dangerous sink.

Input parameters:

- `include_broad_file_io` (boolean): Include broad readFile/writeFile-style default risks. Default false.
- `include_generated` (boolean): Include default risks that touch generated/codegen files. Default false.
- `include_tests` (boolean): Include dataflow risks that touch test files. Default false.
- `max_risks` (number): Maximum risks to return. Default 50, max 500.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `sinks` (array): Additional sink names to merge with defaults and .projscanrc taint.sinks.
- `sources` (array): Additional source names to merge with defaults and .projscanrc taint.sources.

### `projscan_cost_summary` (~301 tokens)

Aggregate token-cost analytics from the current session's tool-call history. action:"snapshot" (default) returns total tokens spent, top spenders, per-tool typical/p95 estimates, and a static expected-cost catalog so the agent can budget pre-call. 1.10+: action:"start_stream" / "stop_stream" / "list_streams" turns this into a live cost dashboard — the server polls the session log on an interval and emits notifications/projscan/cost_delta whenever new tool calls have accrued, with the per-tool deltas and the new cumulative totals inline. Pairs with the `_cost` sidecar attached to every tool result. Read-only. Note: the session event log is bounded at 500 entries — for long-running sessions, older calls are dropped from the snapshot.

Input parameters:

- `action` (string): "snapshot" (default) returns the current aggregate. "start_stream" begins a live cost-delta watch. "stop_stream" cancels by stream_id. "list_streams" enumerates active streams.
- `interval_seconds` (number): Stream poll interval in seconds. Default: 10. Min: 2, max: 600. (start_stream only)
- `stream_id` (string): Stream identifier returned by a previous start_stream. (stop_stream only)
- `top` (number): Optional. Number of top spenders to return. Default: 10. (snapshot + start_stream)

### `projscan_review_watch` (~298 tokens)

Long-running PR review. Polls a base+head ref pair on an interval and emits a notifications/projscan/pr_changed notification whenever the review verdict, SHAs, cycle set, dep changes, taint flows, or risky-function set changes. 1.9+: the notification carries a structured `delta` describing exactly which buckets moved (verdict/baseSha/headSha/changedFiles/cycles/risky/taint/deps) and counts of newly-appearing items per bucket, so agents can skip work they do not need. Pairs with projscan_review (one-shot) — use this when an agent wants to react to pushes on a PR without re-asking. Actions: start (returns initial review + watchId) / stop / list.

Input parameters:

- `action` (string): "start" begins polling (returns initial review + watchId). "stop" cancels a watch by id. "list" enumerates active watches.
- `base` (string): Base ref. Default: origin/main → main → origin/master → master → HEAD~1. (start only)
- `head` (string): Head ref. Default: HEAD. (start only)
- `interval_seconds` (number): Poll interval in seconds. Default: 30. Min: 5, max: 600. (start only)
- `watchId` (string): Watch identifier returned by a previous "start". (stop only)

### `projscan_plugin` (~203 tokens)

Discover and validate stable local analyzer and reporter plugins under .projscan-plugins/. Execution is opt-in via the PROJSCAN_PLUGINS_PREVIEW=1 env flag AND each module must be approved with trust-on-first-use; the list reports a per-plugin `trust` status (trusted / untrusted / changed). Approving a plugin is a deliberate human action via the `projscan plugin trust <name>` CLI — it is intentionally not exposed here. Use action:"list" to see what is discoverable and whether it would run, action:"validate" to check a manifest before committing it.

Input parameters:

- `action` (string): "list" enumerates manifests under <root>/.projscan-plugins/ with discovery status. "validate" lints a manifest at the given path against schema v1.
- `manifest_path` (string): "validate" only — repo-relative path under .projscan-plugins/ to a *.projscan-plugin.json file.

### `projscan_preflight` (~118 tokens)

Answer whether an agent can safely proceed before edits, commit, or merge. Returns proceed, caution, or block with evidence and suggested next tool calls.

Input parameters:

- `base_ref` (string): Optional git base ref for before_commit/before_merge checks.
- `head_ref` (string): Optional git head ref for before_merge review checks.
- `max_changed_files` (number): Optional caution threshold for changed-file count. Default: 50.
- `mode` (string): before_edit, before_commit, or before_merge. Default: before_edit.

### `projscan_workplan` (~230 tokens)

Compose preflight, review, session, hotspot, plugin, and supply-chain signals into an ordered agent execution plan with evidence, suggested tools, verification commands, and handoff text.

Input parameters:

- `base_ref` (string): Optional git base ref for commit/merge/release checks.
- `enable_plugins` (boolean): Request local analyzer plugin evidence only when this MCP server process already has PROJSCAN_PLUGINS_PREVIEW=1. This argument never enables plugin execution by itself.
- `head_ref` (string): Optional git head ref for merge/release checks.
- `max_changed_files` (number): Optional caution threshold for changed-file count. Default: 50.
- `max_tasks` (number): Maximum number of workplan tasks to return. Default: 8, max: 20.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `mode` (string): Planning mode. before_edit/before_commit/before_merge mirror preflight gates; refactor, release, bug_hunt, and hardening add mode-specific task recipes. Default: before_edit.

### `projscan_release_train` (~60 tokens)

Plan upcoming product lines with version, scope, readiness, and next-action evidence.

Input parameters:

- `lines` (array): Product lines to include. Default: next six minor lines.
- `max_tokens` (number): Cap the response to roughly this many tokens.

### `projscan_bug_hunt` (~113 tokens)

Run an agent-ready bug hunt. Combines doctor issues, preflight verdict, hotspots, and session coordination into a prioritized action queue with verification commands.

Input parameters:

- `max_findings` (number): Maximum number of action-queue entries to return. Default: 10, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `since` (string): Git history window for hotspot evidence. Examples: "6 months ago", "2024-01-01".

### `projscan_evidence_pack` (~127 tokens)

Assemble one approval packet from product planning, bug-hunt, workplan, and preflight evidence.

Input parameters:

- `lines` (array): Product lines to include. Default: next six minor lines.
- `max_findings` (number): Maximum bug-hunt findings to include. Default: 10, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `pr_comment` (boolean): Include a concise GitHub PR comment markdown artifact in the response.
- `website_prompt` (boolean): Include website-update prompt text in the response.

### `projscan_regression_plan` (~104 tokens)

Build a smoke, focused, or full regression matrix from bug-hunt, preflight, and product risk signals.

Input parameters:

- `level` (string): Regression depth. Default: focused.
- `lines` (array): Product lines to include. Default: next six minor lines.
- `max_targets` (number): Maximum regression targets to include. Default: 8, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.

### `projscan_agent_brief` (~87 tokens)

Create a compact next-agent context packet with prioritized focus items, repo context, guardrails, and suggested next actions.

Input parameters:

- `intent` (string): Brief intent. Default: next_agent.
- `max_items` (number): Maximum focus items to return. Default: 6, max: 20.
- `max_tokens` (number): Cap the response to roughly this many tokens.

### `projscan_quality_scorecard` (~73 tokens)

Summarize quality dimensions, top risks, verification commands, and suggested next actions for agents and reviewers.

Input parameters:

- `max_risks` (number): Maximum top risks to return. Default: 8, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.

### `projscan_assess` (~145 tokens)

Run a proof-first engineering assessment. Returns Proof Cards with local evidence, fix-first guidance, risk delta, verification commands, and ship-readiness wording.

Input parameters:

- `feedback_path` (string): Optional local feedback artifact path to apply as trust memory.
- `goal` (string): Plain-language assessment goal. Example: "make this repo safer to ship".
- `max_cards` (number): Maximum Proof Cards to return. Default: 5, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `mode` (string): Assessment mode: standard, fix-first, or ship-readiness. fix-first returns the shortest action queue.

### `projscan_simulate` (~108 tokens)

Simulate a proposed change plan before editing. Returns likely files, tests, contracts, rollout, proof commands, and projected risk delta from local evidence.

Input parameters:

- `max_files` (number): Maximum likely touched files to return. Default: 5, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `plan` (string, required): Plain-language change plan. Example: "split bugHunt.ts into ranking, evidence, and output modules".

### `projscan_prove` (~289 tokens)

Create, record, or replay a local Proof Contract for a change. Returns allowed files, forbidden files, proof commands, ledger evidence, scope drift, a reviewer-ready Proof Receipt, and verifiedWorkflow status for agent handoff.

Input parameters:

- `base_ref` (string): Optional git base ref for changed-file detection.
- `changed` (boolean): Validate the current working tree against a Proof Contract.
- `contract_path` (string): Optional local proof contract path for changed-mode validation.
- `duration_ms` (number): Duration in milliseconds for record_command.
- `exit_code` (number): Exit code for record_command.
- `feedback_path` (string): Optional local feedback artifact path to apply as trust memory.
- `intent` (string): Plain-language change intent to constrain before editing.
- `ledger_path` (string): Optional local Proof Ledger JSONL path.
- `log_path` (string): Optional redacted proof log path for record_command.
- `max_files` (number): Maximum likely touched files to include. Default: 5, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `record_command` (string): Record this proof command outcome without executing it.
- `save_contract_path` (string): Optional local path to write the generated Proof Contract in intent mode.
- `summary` (string): Safe redacted proof output summary for record_command.

### `projscan_passport` (~264 tokens)

Create a local Agent Change Passport for reviewer handoff. Returns Proof Contract boundary, changed-file scope, proof replay, proof sufficiency, reviewer action, next commands, and optional Baseframe assessment paths without executing proof commands.

Input parameters:

- `base_ref` (string): Optional git base ref for changed-file detection.
- `contract_path` (string): Optional local Proof Contract JSON path for receipt validation.
- `emit_baseframe` (boolean): Write the Baseframe ProjScan assessment artifact for this task.
- `feedback_path` (string): Optional local feedback artifact path to apply as trust memory.
- `intent` (string): Plain-language change intent to contract before or during work.
- `ledger_path` (string): Optional local Proof Ledger JSONL path.
- `max_files` (number): Maximum likely touched files to include. Default: 5, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `output_path` (string): Optional local passport JSON path under .projscan/passport.json or .projscan/passports/.
- `save_contract_path` (string): Optional local path to write the generated Proof Contract in intent mode.
- `task_id` (string): Optional Baseframe task ID when emit_baseframe is true.

### `projscan_proof_broker` (~214 tokens)

Run the local Proof Broker for reviewer handoff. Returns required proof, proof gaps, required reviewers, risky changed files, next commands, and PR Passport Markdown without executing proof commands.

Input parameters:

- `base_ref` (string): Optional git base ref for changed-file detection.
- `contract_path` (string): Optional local Proof Contract JSON path for receipt validation.
- `feedback_path` (string): Optional local feedback artifact path to apply as trust memory.
- `intent` (string): Plain-language change intent to contract before or during work.
- `ledger_path` (string): Optional local Proof Ledger JSONL path.
- `max_files` (number): Maximum likely touched files to include. Default: 5, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `output_passport_path` (string): Optional local passport JSON path under .projscan/passport.json.
- `save_contract_path` (string): Optional local path to write the generated Proof Contract in intent mode.

### `projscan_review_gate` (~247 tokens)

Run the local Review Gate for reviewer readiness. Returns the Review Gate status, allow-review decision, proof debt, recontract guidance, required reviewers, next commands, PR-comment Markdown, and embedded Proof Broker evidence without executing proof commands.

Input parameters:

- `base_ref` (string): Optional git base ref for changed-file detection.
- `contract_path` (string): Optional local Proof Contract JSON path for review-gate validation.
- `feedback_path` (string): Optional local feedback artifact path to apply as trust memory.
- `intent` (string): Plain-language change intent to contract before or during work.
- `ledger_path` (string): Optional local Proof Ledger JSONL path.
- `max_files` (number): Maximum likely touched files to include. Default: 5, max: 25.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `output_passport_path` (string): Optional local passport JSON path under .projscan/passport.json.
- `output_path` (string): Optional local Review Gate JSON path under .projscan/review-gate.json.
- `save_contract_path` (string): Optional local path to write the generated Proof Contract in intent mode.

### `projscan_adoption` (~144 tokens)

Adoption helper for new projscan users and agents. Returns ready-to-paste MCP client configs, workflow recipes, or first-run diagnostics without mutating the repo.

Input parameters:

- `action` (string): What to return. mcp_config returns client snippets, recipes returns agent workflow recipes, first_run checks setup diagnostics. Default: recipes.
- `client` (string): For action=mcp_config or action=mcp_doctor: all, claude-desktop, claude-code, cursor, codex, continue, windsurf, cline, zed, or gemini. Default: all.
- `max_tokens` (number): Cap the response to roughly this many tokens.

### `projscan_start` (~199 tokens)

First-60-seconds repo orientation for agents and developers. Composes setup diagnostics, workplan, quality scorecard, adoption gaps, top risks, and next commands into one read-only workflow recommendation.

Input parameters:

- `include_handoff` (boolean): Include a compact handoff payload for the next agent.
- `intent` (string): Plain-language goal to route into the next best action and proof commands.
- `max_risks` (number): Maximum top risks to return. Default: 5, max: 12.
- `max_tasks` (number): Maximum workplan tasks to inspect. Default: 5, max: 12.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `mission_dir` (string): Optional saved Mission Control bundle directory. When set, start includes proof outcome from proof-logs/summary.json.
- `mode` (string): Workflow mode to orient around. Default: before_edit.

### `projscan_understand` (~100 tokens)

Explain repo map, runtime flows, public contracts, change readiness, and verification proof with cited file/symbol evidence.

Input parameters:

- `intent` (string): Planned change or question for change-readiness output.
- `max_items` (number): Maximum items per section. Default: 8, max: 30.
- `max_tokens` (number): Cap the response to roughly this many tokens.
- `view` (string): Understand view. Default: map.

### `projscan_collision` (~230 tokens)

Detect change collisions across the repo's in-flight git worktrees (parallel agents). Reports same-file edits (two worktrees changed the same file) and dependency overlaps (one worktree changed a file another's change imports, via the import graph) BEFORE the branches merge. Local-first; needs at least two worktrees. Each collision has `kind` (same-file | dependency), `severity` (high | medium), the two worktree paths, and the files at risk. Use this when coordinating multiple agents/sub-agents working the same repo.

Input parameters:

- `base_ref` (string): Base ref each worktree is diffed against to compute its changed files. Default: origin/main → main → master → HEAD~1, then the working tree.
- `max_distance` (number): Max import hops when `transitive` is set. Default 5.
- `transitive` (boolean): Also report multi-hop dependency overlaps (one worktree changed a file another transitively imports), each with a `distance`. Default false — the 1-hop default stays precise; this trades precision fo…

### `projscan_claim` (~277 tokens)

Coordinate parallel agents with advisory claims/leases over files, directories, or symbols, shared across the repo's git worktrees. action:"add" records a claim (optionally a lease with `ttl_seconds`) and returns any `contention` (another agent already holding an overlapping, non-expired claim); "list" returns claims; "release" drops a claim by `id`, by `target`, or all of an `agent`'s; "prune" removes expired-lease claims. Local-first and advisory — claiming an already-claimed target still succeeds, but surfaces contention so the swarm can coordinate.

Input parameters:

- `action` (string): Default "list". "add" records a claim; "release" drops one; "prune" removes expired leases.
- `agent` (string): "add" — who holds the claim. "release" — scope the release to this agent.
- `id` (string): "release" — the claim id to drop.
- `note` (string): "add" — optional human-readable note.
- `target` (string): "add"/"release" — a repo-relative file or directory path, or a symbol name.
- `ttl_seconds` (number): "add" — lease duration in seconds; the claim expires after it. Omit for a permanent claim.

### `projscan_merge_risk` (~127 tokens)

Merge-risk preflight across the repo's in-flight git worktrees (parallel agents). Given each worktree's changes and the collisions between them, returns `integrationOrder` (merge the least-entangled branch first, each with a risk score) and `hotFiles` (files changed by two or more worktrees — where merge conflict risk concentrates). Builds on projscan_collision; local-first; needs at least two worktrees.

Input parameters:

- `base_ref` (string): Base ref each worktree is diffed against. Default: origin/main → main → master → HEAD~1.

### `projscan_route` (~125 tokens)

Find the right projscan tool for a goal. Given `intent` (free text — e.g. "what breaks if I rename X", "coordinate parallel agents", "is it safe to commit"), returns the best-matching tool(s) with the exact call and why to use each. With no `intent`, returns the full capability catalog grouped by category. A discovery entry point over projscan's surface; deterministic keyword routing, no inference.

Input parameters:

- `intent` (string): What you want to do, in plain words. Omit to get the full grouped tool catalog.

### `projscan_coordinate` (~127 tokens)

One-call coordination read across the repo's in-flight git worktrees (parallel agents). Composes collisions, claims, and merge-risk into a `readiness` verdict (clear | caution | conflicted) plus counts (collisions by severity, contended claim targets, merge hotspots) and the recommended integration order. The single entry point for swarm coordination — use it before continuing parallel work. Local-first; needs at least two worktrees.

Input parameters:

- `base_ref` (string): Base ref each worktree is diffed against. Default: origin/main → main → master → HEAD~1.

### `projscan_coordinate_watch` (~229 tokens)

Long-running swarm coordination watch across the repo's in-flight git worktrees. Polls on an interval and emits a `notifications/projscan/coordination_changed` notification whenever the coordination state changes — readiness (clear/caution/conflicted), collision counts, contended claims, or merge hotspots. Pairs with projscan_coordinate (one-shot): use this when an agent wants to react to other agents' changes without re-asking. Local-first. Actions: "start" (returns the initial summary + a watchId), "stop" (by watchId), "list".

Input parameters:

- `action` (string): "start" begins polling (returns initial summary + watchId). "stop" cancels by id. "list" enumerates active watches.
- `base_ref` (string): Base ref each worktree is diffed against. (start only)
- `interval_seconds` (number): Poll interval in seconds. Default 15, min 5, max 600. (start only)
- `watchId` (string): Watch id from a previous "start". (stop only)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/abhiyoheswaran1-projscan/projscan#diagnostics

## Score history

- 2026-08-03: 78
- 2026-08-02: 77
- 2026-08-01: 5
- 2026-07-31: 33
- 2026-07-30: 51
- 2026-07-28: 51
- 2026-07-27: 51

## Links

- npm package: https://www.npmjs.com/package/projscan
- Socket report: https://socket.dev/npm/package/projscan
- Repository: https://github.com/abhiyoheswaran1/projscan
- Changelog RSS feed: https://verifymcp.io/servers/abhiyoheswaran1-projscan/projscan/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/abhiyoheswaran1-projscan/projscan/changelog.json
- HTML version of this page: https://verifymcp.io/servers/abhiyoheswaran1-projscan/projscan