Quickstart

Get
Started

Install, configure, and run your first analysis in under five minutes.

Step 01

Clone and Build

Clone the repository and build the MCP server locally. Conducks runs as a local process, no cloud, no account.

$ git clone https://github.com/conducks/conducks
$ cd conducks
$ npm run bootstrap && npm run build

Step 02

Configure MCP Client

Add the following to your MCP host config (Claude Desktop, Cursor, or any MCP-compatible client):

{
  "mcpServers": {
    "conducks": {
      "command": "node",
      "args": ["/absolute/path/to/conducks/build/src/interfaces/cli/index.js", "mcp"]
    }
  }
}

Use the absolute path. The MCP protocol requires it to anchor the server correctly to your filesystem.

Step 03

Run your first analysis

Navigate to any project and run the analysis. Conducks builds the graph, scores it, and persists everything to a local DuckDB vault under .conducks/.

$ cd your-project
$ conducks analyze
# builds the structural graph into .conducks/

$ conducks status
# hotspots, entry points, god objects, staleness

$ conducks mirror
# real-time force-directed graph at localhost:3333

13 MCP Tools

All agent interactions go through these tools. Tool descriptions load live, so updating your docs updates what the agent understands without a server restart.

conducks_querySearch the graph for symbols by name or pattern. Fuzzy and template modes.

conducks_statusStructural health: hotspots, entry points, and layer distribution.

conducks_explain6-signal risk breakdown: gravity, complexity, entropy, churn, fan-out, debt.

conducks_impactBlast radius upstream/downstream with hop distance and risk per path.

conducks_traceTrace execution or data flow from a symbol; pathfind between two.

conducks_auditCircular dependencies, god objects, orphans, and custom rule checks.

conducks_contextCollect structural context around a symbol within a graph radius.

conducks_flowsList execution flows, each a named entry point and the symbols it calls.

conducks_pruneFind dead code: orphaned symbols, unused exports, and stale imports.

conducks_diffStructural diff against previous graph states.

conducks_renameGraph-verified rename across all structural references.

conducks_graph_queryRun a raw SELECT against the DuckDB graph store.

conducks_guideArchitectural guidance: engineering standards and rules.

CLI Reference

33 commands across 9 domains. Run conducks help for the full reference, grouped by domain.

Analysis

conducks analyze

conducks status

conducks watch

conducks context

Discovery

conducks query

conducks list

conducks entry

Tracing

conducks trace

conducks impact

conducks flows

Metrics

conducks explain

conducks entropy

conducks cohesion

Governance

conducks audit

conducks fallback

conducks advise

conducks guard

Evolution

conducks rename

conducks prune

conducks diff

conducks drift

Intelligence

conducks resonance

conducks blueprint

Visual

conducks mirror

conducks visualize

conducks context-gen

System

conducks mcp

conducks link

conducks setup

conducks bootstrap-docs

conducks clean

conducks record

conducks doctor

conducks help

← Back to Overview