mcpField
V
voyager-repo

voyager-repo

Local
github.com/dir-aiDeveloper Tools0Updated 14w ago
Repository

About voyager-repo

voyager-repo is a read-only repository scout for agents and developers assessing an unfamiliar codebase. It creates an orientation brief covering structure, build commands, Git health and risks, then proposes an ordered exploration plan without running repository code.

Key features

  1. 01Repository structure and language overview
  2. 02Detected build and test commands
  3. 03Git activity and health signals
  4. 04Risk checks for hooks and secrets
  5. 05Optional dependency vetting
  6. 06Ordered approach plan

Use cases

  1. 01Orient an agent in an unfamiliar repository
  2. 02Review project structure before editing
  3. 03Identify install-hook or secret risks
  4. 04Plan repository exploration without executing code

MCP support

Exposes the `scout_repo` tool to MCP clients for safe-by-default repository orientation; invasive options are disabled by default.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "dir-ai-voyager-repo": {
      "command": "npx",
      "args": [
        "-y",
        "@dir-ai/voyager-repo"
      ]
    }
  }
}
Run commandnpx -y @dir-ai/voyager-repo

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@dir-ai/voyager-repo0.7.0

Tools

1

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
pathstringNoLocal repo path (default: cwd). Remote URLs need allowClone.
maxFilesintegerNo
allowExecbooleanNoConsent to execution — only ever in a sandbox.
checkDepsintegerNoVerify up to N direct dependencies via Voyager (0 = skip).
allowClonebooleanNoConsent to cloning a remote git URL.
allowInstallbooleanNoConsent to dependency install (still never runs code on the host).

Details

From the project README

voyager-repo

Voyager's repo-penetration organ — the eyes an AI agent sends ahead before it touches an unknown repository.

Voyager penetrates the web (@dir-ai/voyager), the repo (this), and — next — networks. Repotector is the repo's guardian that receives and controls; Voyager Repo is the agent's counterpart that reaches outward and reports back, safely.

npx @dir-ai/voyager-repo scout .          # orient in the repo you're standing in
npx @dir-ai/voyager-repo scout . --check-deps 10   # + vet 10 deps via Voyager

What it does

Like how Claude or Codex orient themselves in a new codebase — but as a safe, repeatable tool. scout produces an orientation brief:

  • purpose — inferred from the manifest/README, framed as untrusted (owner text is injection-stripped before it reaches your model)
  • structure — languages, key dirs (with role guesses), entrypoints
  • build — the install/build/test/run commands (detected, never run)
  • health — git signals: commit count, bus factor (top-author share), recency, churn hotspots
  • dependencies — composes with Voyager to give each dependency a real OSV-gated verdict (--check-deps N)
  • risks — install hooks (RCE on npm install), committed secrets, missing lockfile, large opaque binaries
  • approach plan — see below

The approach protocol (the point)

A careful newcomer, not a bulldozer:

  1. Handshake with Repotector if the repo carries one (.repotector/) — read its active zones/leases and respect them before editing.
  2. Fail-closed permissions. Everything is read-only by default. Installing dependencies, executing code, or cloning a remote is withheld until you consent (--allow-install / --allow-exec / --allow-clone) — and execution, when allowed, belongs in a sandbox.
  3. An orderly tour — the brief ends with the ordered next steps a well-behaved agent should take, so it explores on purpose instead of poking at random.

Guarantees

  • Nothing in the target is executed on the host. scout reads files and git; it never runs the repo's code. (Execution, when consented, runs in Voyager's hardened container.)
  • Every owner-controlled byte is untrusted — README, description, commit messages, the Repotector ledger — injection-stripped and framed before your model sees it.
  • Exit codes: 0 oriented · 1 oriented + HIGH-risk finding(s) · 2 tool error.

MCP

voyager-repo mcp

Tool: scout_repo — same orientation, safe-by-default (invasive flags off).

Library

import { scout } from '@dir-ai/voyager-repo'
const brief = await scout('/path/to/repo', { checkDeps: 10 })
if (brief.risks.some((r) => r.level === 'high')) { /* caution */ }

Status

0.x — Phase 1 (repo orientation) of the Voyager "senses" line. Roadmap: capability analysis of a package's tarball, PyPI/cargo/go dependency vetting, and the net organ (cloud/infra introspection).

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.