Repository & Indexing Tools

These four tools manage the lifecycle of a repository in SDL-MCP: registering it, checking its health, understanding its structure, and triggering re-indexing.

Call sdl.repo.status first in every session to confirm the index is current before doing deeper queries.

sdl.repo.register

Registers a new repository (or updates an existing one) for indexing. This is typically the first tool called when connecting a new codebase to SDL-MCP. Creates a repository record in the graph database with the given configuration. Auto-detects package.json, tsconfig.json, and workspace configuration. Validates that the root path exists and is not a path-traversal attempt.

Re-registering an existing repoId updates the configuration without losing indexed data. Registration does not trigger indexing — call sdl.index.refresh afterward.

Parameters

repoId

string

required

Unique identifier for the repository (e.g., "my-app").

rootPath

string

required

Absolute path to the repository root directory.

ignore

string[]

Glob patterns to ignore. Defaults to node_modules, dist, .next, build.

languages

string[]

Language extensions to index. Defaults to all 12 supported languages: ts, tsx, js, jsx, py, go, java, cs, c, cpp, php, rs, kt, sh.

maxFileBytes

number

Maximum file size to index in bytes. Default: 2,000,000.

Response

{
  "ok": true,
  "repoId": "my-app"
}

Example

{
  "repoId": "my-repo",
  "rootPath": "/workspace/my-repo",
  "ignore": ["node_modules", "dist"],
  "languages": ["typescript", "javascript"]
}

sdl.repo.status

Returns the current indexing state and health metrics for a registered repository. Provides a single-call snapshot of everything happening in the repository: file counts, symbol counts, health score, watcher state, prefetch stats, and live editor buffer status.

Parameters

repoId

string

required

Repository identifier.

surfaceMemories

boolean

Include relevant development memories in the response. Default: false.

Response

repoId

string

Repository identifier.

rootPath

string

Absolute path to the repository root.

latestVersionId

string | null

Most recent ledger version, or null if never indexed.

filesIndexed

number

Total files currently tracked.

symbolsIndexed

number

Total symbols in the graph.

lastIndexedAt

string | null

ISO timestamp of the most recent indexing.

healthScore

number

Composite health score from 0–100.

healthComponents

object

Breakdown of health score components.

Show properties

freshness

number

How recently the index was updated (0–1).

coverage

number

Percentage of files successfully indexed (0–1).

errorRate

number

Inverse of parse error rate (0–1).

edgeQuality

number

Quality of dependency edge resolution (0–1).

callResolution

number

Pass-2 call resolution success rate (0–1).

healthAvailable

boolean

Whether health metrics are populated.

watcherHealth

object | null

File watcher state.

Show properties

enabled

boolean

Whether the watcher is enabled.

running

boolean

Whether the watcher is currently running.

filesWatched

number

Number of files being watched.

eventsReceived

number

Total filesystem events received.

eventsProcessed

number

Events successfully processed.

errors

number

Watcher error count.

queueDepth

number

Pending events in queue.

restartCount

number

Number of watcher restarts.

stale

boolean

Whether the watcher appears stale.

lastEventAt

string | null

ISO timestamp of last event.

lastSuccessfulReindexAt

string | null

ISO timestamp of last successful reindex triggered by watcher.

watcherNote

string

Guidance when watcher is inactive.

prefetchStats

object

Predictive prefetch metrics.

Show properties

enabled

boolean

Whether prefetch is enabled.

queueDepth

number

Items queued for prefetch.

running

boolean

Whether prefetch is actively running.

completed

number

Completed prefetch operations.

cancelled

number

Cancelled prefetch operations.

cacheHits

number

Prefetch cache hits.

cacheMisses

number

Prefetch cache misses.

hitRate

number

Prefetch hit rate.

avgLatencyReductionMs

number

Average latency reduction in milliseconds.

lastRunAt

string | null

ISO timestamp of last prefetch run.

liveIndexStatus

object

Live editor buffer state.

Show properties

enabled

boolean

Whether live indexing is active.

pendingBuffers

number

Buffers awaiting processing.

dirtyBuffers

number

Buffers with unsaved changes.

parseQueueDepth

number

Background parse queue size.

checkpointPending

boolean

Whether a checkpoint is queued.

reconcileQueueDepth

number

Pending reconciliation tasks.

memories

array | null

Relevant development memories auto-surfaced for this repo. Only present when surfaceMemories: true.

Example

{ "repoId": "my-repo" }

sdl.repo.overview

Returns a token-efficient summary of the entire codebase structure, tunable from a cheap stats-only view up to a full architectural overview with hotspots, clusters, and process call-chain summaries.

Start with level: "stats" (~100 tokens). Escalate to "directories" or "full" only when you need deeper structure.

Parameters

repoId

string

required

Repository identifier.

level

'stats' | 'directories' | 'full'

required

Detail level. "stats" is cheapest (~100 tokens). "directories" adds per-directory summaries. "full" adds hotspots and architecture.

includeHotspots

boolean

Force hotspot inclusion at any level. Auto-enabled at "full".

directories

string[]

Filter to specific directory paths.

maxDirectories

number

Limit the number of directories returned. Range: 1–200.

maxExportsPerDirectory

number

Limit exports listed per directory. Range: 1–50.

Response

stats

object

Aggregate codebase statistics.

Show properties

fileCount

number

Total files indexed.

symbolCount

number

Total symbols in the graph.

edgeCount

number

Total edges in the graph.

exportedSymbolCount

number

Total exported symbols.

byKind

object

Symbol counts by kind: function, class, interface, type, method, variable, module, constructor.

byEdgeType

object

Edge counts by type: call, import, config.

avgSymbolsPerFile

number

Average symbols per file.

avgEdgesPerSymbol

number

Average edges per symbol.

directories

array

Per-directory summaries. Present when level is "directories" or "full".

Show properties

path

string

Directory path.

fileCount

number

Files in this directory.

symbolCount

number

Symbols in this directory.

exportedCount

number

Exported symbols.

byKind

object

Symbol counts by kind.

exports

array

Top exported symbols.

topByFanIn

array

Symbols with highest fan-in in this directory.

topByChurn

array

Symbols with highest 30-day churn.

subdirectories

string[]

Child directory paths.

estimatedFullTokens

number

Estimated tokens if all cards were fetched.

summaryTokens

number

Tokens used by this summary entry.

hotspots

object

Codebase hotspot analysis. Present at "full" level or when includeHotspots: true.

Show properties

mostDepended

array

Symbols with highest fan-in (most dependents).

mostChanged

array

Symbols with highest 30-day churn.

largestFiles

array

Files with most lines.

mostConnected

array

Files with the most edges.

clusters

object

Community detection summary.

Show properties

totalClusters

number

Total detected clusters.

averageClusterSize

number

Average symbols per cluster.

largestClusters

array

Array of {clusterId, label, size}.

processes

object

Call-chain process summary.

Show properties

totalProcesses

number

Total detected call-chain processes.

averageDepth

number

Average process depth.

entryPoints

array

Process entry point symbols.

longestProcesses

array

Array of {processId, label, depth}.

tokenMetrics

object

Token compression metrics.

Show properties

fullCardsEstimate

number

Estimated tokens if all cards were fetched.

overviewTokens

number

Tokens used by this overview response.

compressionRatio

number

Ratio of overview tokens to full cards estimate.

Examples

{ "repoId": "my-repo", "level": "stats" }

sdl.index.refresh

Triggers re-indexing of a repository in either full or incremental mode. Scans for changed files, parses them, extracts symbols and edges, runs pass-2 call resolution, and writes results to the graph database. Creates a new ledger version and clears slice and card caches. Supports MCP progress notifications.

Incremental mode compares file content hashes to detect changes — only changed files are re-parsed. After indexing, all slice caches and card caches are invalidated.

Parameters

repoId

string

required

Repository identifier.

mode

'full' | 'incremental'

required

"full" re-indexes everything; "incremental" only processes files changed since the last index.

reason

string

Optional reason for the refresh (logged for audit purposes).

Response

boolean

Success flag.

repoId

string

Repository identifier.

versionId

string

The new ledger version ID created by this indexing run.

changedFiles

number

Number of files processed during this run.

Example

{ "repoId": "my-repo", "mode": "incremental", "reason": "post-edit refresh" }

CLI

MCP Tools

Configuration

Repository & Indexing Tools

sdl.repo.register

Parameters

Response

Example

sdl.repo.status

Parameters

Response

Example

sdl.repo.overview

Parameters

Response

Examples

sdl.index.refresh

Parameters

Response

Example

Build docs developers (and LLMs) love

CLI

MCP Tools

Configuration

​sdl.repo.register

​Parameters

​Response

​Example

​sdl.repo.status

​Parameters

​Response

​Example

​sdl.repo.overview

​Parameters

​Response

​Examples

​sdl.index.refresh

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

sdl.repo.register

Parameters

Response

Example

sdl.repo.status

Parameters

Response

Example

sdl.repo.overview

Parameters

Response

Examples

sdl.index.refresh

Parameters

Response

Example