Setup

Setup Repo-Native Alignment MCP

Install the RNA MCP server for aim-conditioned code intelligence.

Execute these steps in order. Do not stop between steps or ask for confirmation -- run the full sequence automatically.

Step 1: Check if already installed

which repo-native-alignment 2>/dev/null

If found, skip to Step 3. If not found, proceed to Step 2.

Step 2: Download the binary

Detect the platform and chip, then download to ~/.cargo/bin/ (already on PATH for Rust users):

OS=$(uname -s)
ARCH=$(uname -m)
CHIP=$(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo "")
mkdir -p ~/.cargo/bin

If macOS ARM M2+ (Darwin + arm64 + brand_string contains "M2", "M3", or "M4"):

curl -L https://github.com/open-horizon-labs/repo-native-alignment/releases/latest/download/repo-native-alignment-darwin-arm64-fast.tar.gz | tar xz -C ~/.cargo/bin

If macOS ARM (M1) (Darwin + arm64):

curl -L https://github.com/open-horizon-labs/repo-native-alignment/releases/latest/download/repo-native-alignment-darwin-arm64.tar.gz | tar xz -C ~/.cargo/bin

If Linux x86_64 (Linux + x86_64):

curl -L https://github.com/open-horizon-labs/repo-native-alignment/releases/latest/download/repo-native-alignment-linux-x86_64.tar.gz | tar xz -C ~/.cargo/bin

If none of the above match: Tell the user their platform is not yet supported by the published release artifacts. They may build from source for development/testing, but source builds are not a substitute for release verification from successful CI/release artifacts:

cargo install --locked --git https://github.com/open-horizon-labs/repo-native-alignment

If ~/.cargo/bin is not on PATH (no Rust toolchain installed), tell the user to add it: export PATH="$HOME/.cargo/bin:$PATH"

Release artifacts are intentionally built without local embedding/reranking support. They support extraction, graph traversal, lexical search, LSP call/reference enrichment, repo maps, and MCP delivery. Semantic search and cross-encoder reranking require a development/source build with embedding features (Apple Silicon Metal: cargo install --locked --path . --features metal from a checked-out repo); source builds are not a substitute for release verification from successful CI/release artifacts.

Step 3: Configure the MCP server

RNA is a per-project MCP server (it indexes the repo it's pointed at). MCP stdio launchers often do not source shell profiles, and some harnesses crash or mis-handle wrapper commands. Keep command as the direct repo-native-alignment binary path. Never launch through mise, asdf, brew, another tool-manager command, or a shell wrapper script.

Check if .mcp.json exists in the project root and already contains an rna-server entry. If it does, verify it uses a direct RNA binary command; rewrite wrapper-based entries to the direct-binary pattern below.

If the agent supports claude mcp add (Claude Code), use a direct RNA command:

claude mcp add rna-server --scope project -- repo-native-alignment --repo "$PWD"

Otherwise, create or update .mcp.json in the project root with:

{
  "mcpServers": {
    "rna-server": {
      "type": "stdio",
      "command": "/Users/me/.cargo/bin/repo-native-alignment",
      "args": ["--repo", "/absolute/path/to/project"]
    }
  }
}

If .mcp.json already exists with other servers, merge the rna-server entry into the existing mcpServers object -- do not overwrite the file.

Conditional C#/.NET LSP enrichment

Do not probe for dotnet, csharp-ls, DOTNET_ROOT, or .NET tool-manager installs by default. Only do so when at least one of these is true:

• the target repository contains C#/.NET markers such as .cs, .csproj, or .sln files;
• repo-native-alignment setup reports the optional C# toolchain need; or
• the user explicitly requests C# call/reference enrichment.

For those C#/.NET repositories, install csharp-ls with dotnet tool install -g csharp-ls and ensure ~/.dotnet/tools is on PATH. If the MCP launcher does not inherit shell setup, add the resolved .NET root as DOTNET_ROOT (and DOTNET_ROOT_ARM64 on Apple Silicon), and prepend that root plus ~/.dotnet/tools to the server env PATH. Use the setup command's reported root for mise, asdf, Homebrew, or official .NET installs. Keep command as the direct RNA binary; never make it mise, asdf, brew, or a wrapper script.

Step 4: Pre-warm the code index

Run a full scan to build the code index before the MCP server starts. This avoids cold-start latency on the first tool call:

repo-native-alignment scan --repo . --full

This builds the release-binary pipeline (scan, extract, LSP enrich, graph) and caches results in .oh/.cache/lance/. Builds compiled with --features embeddings or --features metal also run embedding enrichment. The MCP server reuses this cache on startup -- if no files changed, graph loads in seconds with zero re-extraction. Subsequent scans are incremental.

Without this step, the MCP server pre-warms the graph automatically at startup, but the first tool call may need to wait for that to complete. Pre-building ensures instant readiness.

Step 5: Update AGENTS.md with tool guidance

If AGENTS.md exists in the project root, check if it already contains <!-- RNA MCP tool guidance -->. If it already has this marker, skip this step.

If AGENTS.md exists but lacks the marker, append this block:

<!-- RNA MCP tool guidance -->
## Code Exploration (RNA MCP)

| Instead of... | Use this RNA MCP tool |
|---|---|
| `Grep` for symbol names | `search(query, kind, language, file)` |
| `Read` to trace function calls | `search(node, mode: "neighbors")` |
| `Grep` for "who calls X" | `search(node, mode: "impact")` |
| `Read` to find .oh/ artifacts | `search(query, include_artifacts=true)` |
| `Bash` with `grep -rn` | `search(query)` — searches code, artifacts, and markdown |
| Codebase orientation | `repo_map(top_n)` |
| Recording learnings/signals | Write to `.oh/metis/`, `.oh/signals/`, `.oh/guardrails/` (YAML frontmatter + markdown) |
| Searching git history | `search(query)` — returns commits; use `git show <hash>` via Bash for diffs |
<!-- end RNA MCP tool guidance -->

If AGENTS.md does not exist, create it with the tool guidance block as the initial content.

Step 5b: Check for framework boundary patterns

Check whether the project uses messaging frameworks, event buses, or libraries with hook patterns that RNA should know about. Capture the result so the setup pipeline can branch on it explicitly — do not rely on grep exit codes, which return non-zero on no-match and would halt chained automated setup.

FRAMEWORK_PATTERN='pubsub|kafka|celery|pika|redis|rabbitmq|sqlalchemy|django|flask|opentelemetry|otel'
DETECTED_FRAMEWORKS=$(repo-native-alignment search --repo . "" --kind import --compact 2>/dev/null \
  | grep -iEo "$FRAMEWORK_PATTERN" | sort -u || true)

if [ -z "$DETECTED_FRAMEWORKS" ]; then
  echo "No framework boundaries detected; skipping extractor coverage check."
else
  echo "Detected frameworks: $DETECTED_FRAMEWORKS"
fi

If frameworks were detected, assert real coverage in .oh/extractors/ by searching extractor file contents (not just listing filenames). The check below sets EXTRACTOR_COVERAGE to the list of frameworks already covered, then computes the gap; both branches exit zero so chained pipelines do not abort.

if [ -n "$DETECTED_FRAMEWORKS" ]; then
  if [ -d .oh/extractors ]; then
    EXTRACTOR_COVERAGE=$(grep -RhoiE "$FRAMEWORK_PATTERN" .oh/extractors/ 2>/dev/null \
      | sort -u || true)
  else
    # Treat missing dir as zero coverage so the gap output names every detected
    # framework. Do not exit non-zero — chained automated setup must continue.
    EXTRACTOR_COVERAGE=""
  fi
  GAP=$(comm -23 <(echo "$DETECTED_FRAMEWORKS") <(echo "$EXTRACTOR_COVERAGE"))
  if [ -z "$GAP" ]; then
    echo "All detected frameworks have extractor coverage."
  else
    echo "Detected frameworks missing extractor coverage:"
    echo "$GAP"
  fi
fi

If the project uses a messaging framework without coverage, create a config file. Example for Google Pub/Sub:

# .oh/extractors/google-pubsub.toml
[meta]
name = "google-pubsub"
applies_when = { language = "python", imports_contain = "google.cloud.pubsub" }

[[boundaries]]
function_pattern = "publisher.publish"
arg_position = 0
edge_kind = "Produces"

[[boundaries]]
function_pattern = "subscribe"
arg_position = 0
edge_kind = "Consumes"

If the project uses frameworks with method-override hooks (SQLAlchemy, Django, OTEL), create a hooks config:

# .oh/extractors/sqlalchemy-hooks.toml
[meta]
name = "sqlalchemy-hooks"
applies_when = { language = "python", imports_contain = "sqlalchemy" }

[[hooks]]
class_contains = "TypeDecorator"
method_names = ["process_bind_param", "process_result_value"]

The [[boundaries]] section detects Produces/Consumes edges for message brokers. The [[hooks]] section marks method overrides on library base classes as framework hooks (so dead-code analysis skips them).

For more details, see docs/extractors.md in the RNA repo, or use /gen-extractor to generate configs from a natural-language description.

Step 6: Inform the user

Tell the user:

1. Setup is complete
2. They may need to restart their agent/IDE for the MCP server to load
3. After restart, RNA MCP tools will be available:
   • search - Symbol search, graph traversal (neighbors/impact/reachable/tests_for/cycles/path), artifact/commit/markdown search. Use compact: true to save tokens. Use mode + node for graph walks.
   • repo_map - Codebase orientation: top symbols by importance, hotspot files, entry points, subsystem breakdown
   • outcome_progress - Business outcome tracking against code changes
   • list_roots - Workspace root management