# Setup

> Install and configure the Repo-Native Alignment (RNA) MCP server. Downloads the binary, configures the MCP server, pre-warms the code index, and updates AGENTS.md with tool guidance.

- Skill: `open-horizon-labs/setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add open-horizon-labs/setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/open-horizon-labs/setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: open-horizon-labs (https://skillmd.com/u/open-horizon-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/open-horizon-labs/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

```bash
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):

```bash
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"):
```bash
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`):
```bash
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`):
```bash
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:
```bash
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:
```bash
claude mcp add rna-server --scope project -- repo-native-alignment --repo "$PWD"
```

Otherwise, create or update `.mcp.json` in the project root with:
```json
{
  "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:

```bash
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:

```markdown
<!-- 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.

```bash
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.

```bash
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:

```toml
# .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:

```toml
# .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