npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

devbrain-mcp

v0.7.1

Published

Repository intelligence, trusted execution evidence, deterministic context governance, and read-only Docker inspection MCP server

Readme

DevBrain MCP

Evidence-backed repository intelligence and trusted execution for coding agents.

npm Node.js MCP

DevBrain is a local Model Context Protocol server for coding agents. It turns a repository into bounded, machine-readable evidence: structure, dependencies, symbols, architecture, change impact, execution results, and durable provenance.

It is not an autonomous coding agent. DevBrain supplies facts and controlled capabilities; the agent, reviewer, or developer remains responsible for deciding what to change.

Why DevBrain

DISCOVER  →  RESOLVE  →  AUTHORIZE  →  EXECUTE  →  PARSE  →  EVIDENCE
  • Bounded context — searches, slices, graphs, and context packs have explicit limits.
  • Honest results — unknown, partial, unsupported, and not_run are never disguised as success.
  • Trusted execution — build, test, targeted-test, and lint runs require capability-specific approval.
  • Durable evidence — outputs retain command, working directory, Git, timing, parser, and hash provenance.
  • Local by default — the server communicates over stdio and inspects only its configured workspace.

Quick start

  • Node.js 20 or newer
  • Git for repository identity and provenance
  • The repository's existing package manager or Python tooling for execution capabilities
  • Docker CLI and daemon access only when Docker inspection is requested

From the root of a Git repository, run:

npx -y [email protected] setup --yes
npx -y [email protected] doctor --json

Setup installs a persistent project-scoped runtime under the user DevBrain home, writes only the DevBrain-owned section in the repository's Codex configuration, preserves unrelated settings, performs an MCP handshake, and reports the 26-tool count. Restart Codex after setup so it reconnects. --json returns package, installation, workspace, preflight, handshake, and next-action fields. Use --dry-run to inspect the plan. Global mode is intentionally unsupported because this server binds to one workspace per configuration.

The installed launcher never points at the temporary npx cache. The durable runtime is replaced transactionally and failed activation restores the previous runtime/configuration. devbrain uninstall --yes removes only DevBrain-owned configuration.

Existing installations and dry validation

DevBrain never silently replaces an existing project DevBrain definition. If setup reports UPGRADE_REQUIRED, inspect the target with --dry-run, then explicitly authorize the transactional replacement:

npx -y [email protected] setup --upgrade --yes --json

--upgrade preserves unrelated MCP entries and rolls the exact configuration back if the staged runtime or post-write probe fails. To test a candidate runtime without persisting a runtime or configuration change, use:

npx -y [email protected] setup --validate --yes --json

--upgrade and --validate are mutually exclusive. --validate reports validation evidence only; it is not an installation.

Run the server over stdio with npm start. Set DEVBRAIN_WORKSPACE_ROOT to the directory DevBrain may inspect; it defaults to the process working directory.

{
  "mcpServers": {
    "devbrain": {
      "command": "node",
      "args": ["C:/path/to/devbrain-mcp/dist/index.js"],
      "cwd": "C:/path/to/allowed/workspace",
      "env": { "DEVBRAIN_WORKSPACE_ROOT": "C:/path/to/allowed/workspace" }
    }
  }
}

Capability map

DevBrain exposes 26 deterministic tools across four layers:

| Layer | What it covers | | --- | --- | | Repository intelligence | Maps, health, Git history, dependencies, and TODO markers. | | Trusted execution | Approved build, test, targeted-test, lint, and observational Docker inspection. | | Context governance | Bounded search, symbols, references, slices, diffs, diagnostics, and context packs. | | Architecture intelligence | Dependency graphs, APIs, routes, schemas, migrations, and change impact. |

Static evidence is not runtime proof. A route is not proof of reachability, a schema is not proof of production state, and an impact candidate is not a predicted failure.

Phase 1 — Repository Intelligence

Phase 1 is non-mutating repository inspection:

  • devbrain_repo_map returns a bounded structural map, detected stacks, workspaces, scripts, entry points, and configuration evidence.
  • devbrain_project_health returns Git state, upstream divergence, hygiene observations, dependency-environment state, and red flags.
  • devbrain_git_history returns bounded commit metadata and short statistics without patches.
  • devbrain_dependency_audit inventories direct dependencies and reports update/vulnerability checks with explicit degraded states.
  • devbrain_find_todos returns bounded TODO/FIXME/HACK/XXX locations while respecting Git ignore rules when available.

Phase 2 — Trusted Execution & Evidence

Phase 2 adds four capability-oriented execution tools and observational Docker inspection:

  • devbrain_run_build: runs an explicitly detected and approved build definition.
  • devbrain_run_tests: runs an explicitly detected and approved full test definition.
  • devbrain_run_targeted_tests: runs one validated repository-contained test target without accepting arbitrary extra arguments.
  • devbrain_run_lint: runs an explicitly detected and approved lint definition.
  • devbrain_inspect_docker: reports bounded Docker version, container status/health/ports, images, sanitized mount metadata, and deterministic Compose labels. It performs no lifecycle operation.

Execution inputs contain a repository path, an optional bounded timeout, and—for targeted tests—a repository-relative target. There is no arbitrary command MCP interface.

Trusted Execution Model

DevBrain Phase 2 does not sandbox repository-controlled code. Trusted build, test, and lint commands execute with the permissions of the DevBrain process. Trust authorization is the primary security boundary; command inspection and deny controls are defense-in-depth.

Trust is capability-specific: approving test does not approve build, targeted_test, or lint. The MCP server can create an approval request but exposes no trust or approval tool, so an MCP client cannot grant itself execution authority.

Repository Identity

Trust binds to the canonical repository location plus identity evidence derived from the repository's initial commit and remote identity. Replacing a repository at a previously trusted path changes its identity and does not inherit approval.

External Trust Registry

Authoritative state is outside inspected repositories under ~/.devbrain/ (or DEVBRAIN_HOME when explicitly configured):

~/.devbrain/
  trust-registry.json
  approvals/
  executions/<repository-id>/<execution-id>/

Do not copy this runtime state into a repository or commit it.

Execution-Definition Pinning

Approval binds to repository identity, capability, invocation, working directory, repository-controlled definition, and its SHA-256 fingerprint. DevBrain rediscovers and fingerprints the definition before every run. A changed script or configuration returns approval_required and does not execute.

Human Approval CLI

Review pending requests and approve only an exact definition you trust:

devbrain approval list
devbrain approval inspect apr_...
devbrain approve apr_...

devbrain trust list
devbrain trust inspect C:/path/to/repo
devbrain trust revoke C:/path/to/repo
devbrain trust revoke C:/path/to/repo test

The CLI is the administrative boundary. Approval is deliberately absent from MCP.

Execution Pipeline

Every run follows separated stages:

DISCOVER → RESOLVE → AUTHORIZE → EXECUTE → PARSE → EVIDENCE

Processes use executable-plus-argument arrays with shell: false and a canonical working directory. DevBrain does not install dependencies, modify configuration, create reporters, fix lint, format source, or run migrations. Approved repository scripts can still have their own side effects.

Evidence Store

Every authorized run receives an immutable executionId. Its external evidence directory contains metadata.json, result.json, stdout.log, and stderr.log. Structured files use atomic writes, and stdout/stderr are stored separately with SHA-256 hashes. MCP responses return redacted tails capped at approximately 8 KiB per stream rather than full logs.

The provenance envelope records the exact executable and arguments, canonical cwd, timestamps, duration, exit code when available, Git SHA/branch/dirty state, platform/architecture, runtime and package-manager versions when available, and durable log paths/hashes.

Dirty Worktree Semantics

git.dirty: false ties the evidence to the recorded commit under the captured environment. git.dirty: true means the run covered that SHA plus uncommitted working-tree state; it does not prove the clean commit passed. DevBrain reports this distinction and leaves acceptance policy to its caller.

Timeout Policy

| Capability | Default | Hard ceiling | | --- | ---: | ---: | | Lint | 60 seconds | 5 minutes | | Build | 5 minutes | 15 minutes | | Targeted tests | 2 minutes | 10 minutes | | Full tests | 10 minutes | 30 minutes |

Timeouts terminate the process tree, including descendant cleanup through taskkill /T /F on Windows. Execution state (completed, timed_out, or execution_error) remains separate from engineering result (passed, failed, partial, unknown, or not_applicable).

Result Parsing / Parse Confidence

DevBrain attempts actual JSON reporter output, then actual JUnit XML, then framework text parsing, and finally exit-code-only or unknown interpretation. json_reporter and junit_xml are reported only when machine-readable content was parsed. Text-derived Vitest, Jest, and pytest counts use text_regex with medium confidence; unrecognized completed output falls back to exit_code_only with low confidence. Parsing never installs tooling or changes repository configuration.

Docker Inspection

devbrain_inspect_docker may run only observational Docker commands. It cannot start, stop, restart, remove, execute in, build, pull, or push containers/images. Container environment values are not requested or returned, bind-mount sources are sanitized, and all collections are bounded.

devbrain_inspect_docker is observational, but access to the Docker daemon may itself imply significant host privileges depending on platform and configuration.

Phase 3 — Context Intelligence & Governance

Phase 3 adds deterministic, local context retrieval and evidence packaging. DevBrain remains a capability layer: it can locate, bound, measure, redact, and package evidence, but it does not decide what code to change or whether a fix is correct.

  • devbrain_search_text performs bounded literal repository search with optional file globs.
  • devbrain_search_symbols locates TypeScript, JavaScript, and Python definitions with explicit resolution confidence.
  • devbrain_find_references returns bounded textual symbol occurrences labelled as low-confidence textual evidence.
  • devbrain_read_file_slice returns one canonical, line-numbered file range.
  • devbrain_read_symbol returns one definition or an explicit ambiguity/not-found state.
  • devbrain_get_diff returns structured working-tree, staged, commit, or range evidence with complete file statistics and a bounded patch.
  • devbrain_get_execution_evidence retrieves bounded Phase 2 evidence by executionId, never by filesystem path.
  • devbrain_diagnose_log extracts bounded errors, failing-test clues, chained causes, and file/line frames from stored execution logs.
  • devbrain_context_pack persists and returns a deterministic evidence package under requested and hard budgets.

Context Security Model

Repository content is untrusted data. Every returned repository item carries source.type: repository_file and source.trust: untrusted_content; execution-log diagnostics use the same untrusted-content discipline. Text such as “ignore previous instructions” is returned only as quoted repository evidence and is never executed or treated as an instruction by DevBrain.

Phase 3 uses no LLM, embedding model, vector database, remote semantic search, or network service. MCP supplies deterministic capabilities and evidence; Skills and callers retain judgment and sequencing.

Bounded Retrieval and Context Budgets

Searches respect Git ignore rules when available and exclude .git, dependency environments, build output, coverage, caches, binaries, and generated directories. Canonical path checks reject traversal and symlink escape.

Hard ceilings apply even when callers request more:

| Resource | Hard ceiling | | --- | ---: | | Context-pack files | 20 | | Lines | 3,000 | | Bytes | 200,000 | | Search matches | 200 | | References | 200 | | Diff patch | 150,000 bytes |

All bounded tools return explicit counts and truncation state. There is no unlimited or recursive whole-repository response mode.

Symbol and Reference Resolution

Initial TypeScript, JavaScript, and Python symbol discovery uses deterministic language-specific syntax heuristics and reports resolutionMethod: heuristic, confidence: medium. Reference lookup is textual and reports low confidence; it does not claim semantic identity. Multiple definitions produce an ambiguity result rather than a guessed selection.

Diagnostic Compression

Execution evidence retrieval returns normalized state, provenance, parser confidence, log sizes, and hashes without full logs. Diagnostic compression examines bounded stored logs for common Vitest, Jest, pytest, compiler, lint, stack-frame, and chained-exception patterns. Its extracted structure is heuristic and confidence-labelled; Phase 2 logs remain authoritative.

Context Packs

Context packs rank only deterministic signals: explicit seed files/symbols, execution stack frames, working-tree diff files, and exact objective terms. Each included item records a selection reason, file/range, repository-content trust, redaction state, and content hash. Unexplained files are not included.

Every pack receives a contextPackId and stores a content-free manifest at:

~/.devbrain/context-packs/<repository-id>/<context-pack-id>/manifest.json

The manifest records repository SHA/branch/dirty state, budgets, usage, selected ranges and reasons, hashes, exclusions, confidence, and file/line/byte metrics. It does not duplicate repository content. A dirty pack represents the recorded SHA plus working-tree state, not the clean commit alone.

Context metrics report repository, candidate, and included files/lines/bytes plus budget utilization. DevBrain does not claim token savings without model-specific tokenization.

Secret Redaction and Prompt-Injection Boundary

Search results, slices, symbols, diffs, diagnostics, execution evidence, and context packs reuse shared secret redaction. Returned metadata indicates redaction without exposing detected values. Prompt-like repository prose remains visible only as provenance-labelled untrusted evidence so a caller can assess it without DevBrain obeying it.

Phase 3 Known Limitations

  • Symbol resolution is heuristic rather than AST/type-checker semantic analysis.
  • Reference matches are textual and can include false positives.
  • Diagnostic parsers cover common formats but cannot reconstruct every custom runner output.
  • Context packs deliberately stop at deterministic evidence; they do not summarize, recommend edits, calculate change impact, or perform architecture analysis.
  • Context-pack manifest persistence is DevBrain-owned external state, so that tool is non-idempotent even though it does not mutate the repository.

Phase 4 — Architecture, Dependency & Change Intelligence

Phase 4 adds seven deterministic, read-only capabilities:

  • devbrain_dependency_graph returns bounded file, symbol, package, module, and external-dependency relationships.
  • devbrain_architecture_map groups evidence-backed applications, packages, entry points, API, service, persistence, test, module, and external-dependency components.
  • devbrain_api_inventory inventories declared HTTP APIs and public package exports.
  • devbrain_route_inventory maps declared routes to handlers, middleware, and statically imported downstream files.
  • devbrain_database_schema normalizes repository-defined ORM schema and SQL DDL evidence.
  • devbrain_migration_status checks repository migration ordering and parseable schema operations.
  • devbrain_change_impact ranks bounded potential impacts from file, symbol, or Git diff seeds.

All seven inspect repository evidence only. They do not execute application code, connect to databases, apply migrations, refactor code, approve releases, or call an LLM.

Relationship Model

Every relationship records a source ID, target ID, bounded relationship type, source file/line evidence, classification, resolution method, and confidence. The vocabulary includes imports, exports, references, inheritance, routes, services, tables, tests, packages, modules, and migration operations. New arbitrary relationship strings are not generated.

Graphs are capped at 500 nodes, 1,500 edges, depth 5, and 300 analysed source files. Smaller caller limits are honoured; larger requests are rejected. Responses report returned and known counts, reached depth, and truncation. Iterative visited-node traversal terminates cycles.

Observed vs Inferred vs Potential

  • observed means a deterministic repository construct was parsed, such as an import, manifest dependency, route declaration, schema declaration, or migration identifier.
  • inferred means deterministic evidence supports a relationship that is not literally declared, such as a directory-based layer, mounted route prefix, cross-package module relationship, or test import.
  • potential is reserved for change-impact candidates. It never means a target will fail or change at runtime.

Confidence Semantics

high is used for direct, unambiguous parsed evidence; medium for deterministic heuristics or composed evidence; low for textual or naming-convention evidence; and unknown when no supported conclusion is available. Confidence never upgrades static evidence into runtime proof.

Dependency Graph

devbrain_dependency_graph accepts repository, workspace/package, file, or symbol scope. TypeScript/JavaScript and Python imports resolve to repository files or declared/undeclared external packages where possible. File-qualified symbol IDs prevent same-named definitions in different packages from merging; ambiguous textual references are attached only when an import resolves to the matching definition.

Architecture Map

devbrain_architecture_map groups files using manifest entry points, route/schema/table evidence, imports, test naming, and bounded path conventions. Observable route or schema evidence remains observed; service/layer classification from paths is inferred. If no supported layer evidence exists, layering is undetermined rather than invented.

API/Route Inventory

Framework adapters cover Express, Next.js, FastAPI, Flask, and Django when dependency evidence identifies that framework. Static routes include method, path, handler, middleware, framework, evidence, and resolution state. Dynamic/unresolvable construction is returned as partial low-confidence evidence without fabricating the final runtime route. Route downstream entries are static handler-file imports, not runtime call traces.

Repository Schema Intelligence

devbrain_database_schema recognizes Prisma, TypeORM, Sequelize, SQLAlchemy, Django ORM, and parseable SQL DDL. It distinguishes declared schema, migration-derived schema, and inferred model mapping, and returns normalized tables, columns, indexes, foreign keys, source locations, classification, and confidence. Datasource configuration is redacted and may report a provider; credentials are never returned.

Migration Intelligence

devbrain_migration_status recognizes Prisma, Alembic, Django, numbered SQL, Knex, TypeORM, and Sequelize-style repository chains where deterministic evidence exists. It reports order, latest identifier, duplicates, obvious gaps, missing dependencies, multiple heads, cycles, and parseable create/alter/drop operations. “Repository migration chain appears consistent” does not mean any database has applied it.

Change Impact

devbrain_change_impact accepts file, symbol, and Git diff seeds. It resolves changed files/symbols, follows bounded reverse imports, correlates routes, repository schema/table references, tests, and observable configuration, then ranks direct, interface, persistence, test, transitive, and configuration candidates. Every candidate is potential and explains why through a relationship path and evidence.

Diff-Seeded Impact

Diff seeds reuse the Phase 3 Git argument builder for working-tree, staged, commit, and range modes. Responses preserve SHA, branch, dirty state, changed paths, and hunk-intersecting symbols. Deleted paths remain Git evidence even when content no longer exists; rename paths follow Git’s selected diff mode.

Phase 3 Integration

devbrain_context_pack accepts optional architectureRelevance: true. It adds at most ten deterministic impact candidates, ranked between Git-diff and exact-text signals. Phase 3’s file, line, and byte budgets, redaction, content hashes, selection reasons, manifests, and untrusted_content provenance remain unchanged; discovering a large graph cannot grow a pack.

Static-vs-Runtime Limitations

A declared route is not proof it is reachable. A repository schema is not production database state. A static reference is not proof of runtime execution. A test import is not behavioral coverage. Phase 4 exposes these boundaries as boundary: { evidence: "static_repository_analysis", runtime: "not_observed" } and uses partial/unsupported results where deterministic evidence ends.

Monorepo Semantics

Repositories, packages/workspaces, modules, files, and symbols remain distinct nodes. Package identity is preserved on nodes and component IDs; cross-package imports produce explicit package relationships instead of flattening all definitions into one namespace.

Phase 4 Known Limitations

  • Parsing is deterministic and bounded but heuristic; it is not a compiler, type checker, framework runtime, or SQL engine.
  • Dynamic imports, metaprogrammed routes, generated ORM models, and custom migration frameworks may be partial or unsupported.
  • Impact candidates are ranked static possibilities, not predicted failures.
  • The in-process graph cache is keyed by repository SHA and dirty worktree state; no persistent architecture index or daemon is created.

Security Model and Limitations

  • Canonical paths must remain under DEVBRAIN_WORKSPACE_ROOT; symlink escapes and invalid targeted-test paths are rejected.
  • Command inspection blocks representative dangerous definitions but is not a sandbox.
  • Secrets are redacted from returned content; full external logs remain sensitive local evidence and inherit host filesystem protections.
  • Structured parsing depends on output the repository already produces. Otherwise DevBrain degrades honestly to text or exit-code evidence.
  • Package-manager and runtime availability can make a capability unsupported or leave version provenance unknown.
  • Docker results are a point-in-time observation, not proof of future health or isolation.

Verification receipts

devbrain_get_execution_evidence keeps raw execution evidence available by execution ID. Its additive view: "receipt" returns a compact, sanitized result for one recorded test, targeted test, lint, or build execution. view: "summary" combines supplied execution IDs and marks each verification category as passed, failed, timed out, cancelled, unknown, or not verified. Missing or truncated evidence remains explicit; a receipt never turns absent evidence into a pass.

Context budget advisor and session handoff

devbrain_context_pack accepts an optional token budget and returns deterministic token estimates, largest contributors, exclusions, and advice. Estimates are byte-based guidance, not measured model-token usage. With view: "handoff", the same bounded context workflow adds a sanitized session handoff: repository identity, change state, relevant verification evidence, and omissions when its size budget is reached.

Change risk score

devbrain_change_impact adds a deterministic riskAssessment to its static impact report. The score is a bounded heuristic based on observed repository evidence, known dependency reach, related test evidence, and explicit unknowns. It is not a prediction of production failure or release approval.

Phase 5 — Distribution and environment hardening

Phase 5 adds lifecycle administration outside the MCP tool surface:

  • devbrain setup discovers the Git root, validates Node/server/workspace paths, completes an MCP preflight, and installs repository-local configuration transactionally.
  • devbrain doctor performs read-only DB001–DB011 environment and configuration checks; --json returns the stable machine-readable report.
  • devbrain doctor --repair proposes evidence-backed paired path repairs, requires --yes for mutation, backs up first, validates afterward, and rolls back failure.
  • devbrain uninstall removes only DevBrain-owned MCP sections and preserves other Codex configuration.

All mutation commands support --dry-run. A newly generated required = true definition is blocked unless preflight succeeds. See the lifecycle administration guide for configuration discovery, exit codes, Windows behavior, recovery, and security boundaries.

Development

npm test
npm run lint
npm run build
npx @modelcontextprotocol/inspector node dist/index.js

See VERIFICATION.md for executed quality and acceptance evidence.

Documentation

Status

Current stable package line: 0.7.1.

Review the verification record and security boundaries before enabling trusted execution in a new environment.