### Multi-Agent Setup Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Demonstrates a typical multi-agent setup by starting a shared SDL-MCP server and connecting multiple agents to it.

```bash
# Terminal 1: Start the shared server
sdl-mcp serve --http --port 3000

# Terminal 2: Agent A connects (e.g., Claude Code with HTTP config above)
# Terminal 3: Agent B connects (e.g., Cursor with HTTP config above)
# Terminal 4: Agent C connects (e.g., CI pipeline calling MCP tools via curl)

```

--------------------------------

### 5-Minute Setup for sdl-mcp

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

A quick setup guide that initializes the configuration, automatically indexes the repository, and runs doctor checks. It also starts the MCP server using stdio for coding agents. The `--no-watch` flag can be used to disable watcher mode if needed.

```bash
# Tip: If you are using npx, replace `sdl-mcp` with `npx --yes sdl-mcp@latest`.
# 1) Set config location variable then open a new terminal
setx SDL_CONFIG_HOME "C:\\[your path]"

# 2) One-line non-interactive setup (init + index + doctor)
sdl-mcp init -y --auto-index --config "C:\\[same path as SDL_CONFIG_HOME]"

# 3) Start MCP server (stdio for coding agents)
sdl-mcp serve --stdio

# Optional: disable watcher mode if your environment is unstable
sdl-mcp serve --stdio --no-watch
```

--------------------------------

### Build Example Plugin

Source: https://github.com/glitterkill/sdl-mcp/blob/main/examples/example-plugin/README.md

Build the example plugin locally. Ensure SDL-MCP is installed and built first, or install it as an NPM dependency.

```bash
# From SDL-MCP root directory
npm install
npm run build

# Then build the example plugin
cd examples/example-plugin
npm install
npm run build
```

```bash
npm install sdl-mcp
npm run build
```

--------------------------------

### Get Repository Overview

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/agent-workflows.md

Start with `sdl.repo.overview`, typically using `level: "stats"`. Use `directories` or `full` only when needed.

```javascript
sdl.repo.overview({
  level: "stats"
});
```

--------------------------------

### Local Setup Workflow

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/cli-reference.md

A sequence of commands to initialize, configure, and start the MCP service locally for development.

```bash
sdl-mcp init --client codex
sdl-mcp info
sdl-mcp doctor
sdl-mcp index
sdl-mcp serve --stdio
```

--------------------------------

### Install and Initialize SDL-MCP

Source: https://context7.com/glitterkill/sdl-mcp/llms.txt

Installs SDL-MCP globally and initializes a repository with auto-indexing. Use npx for one-time execution without global installation.

```bash
# Install globally (requires Node.js 24+)
npm install -g sdl-mcp

# One-line setup: init config, auto-detect languages, index repo, run health checks
sdl-mcp init -y --auto-index

# Start MCP server for your coding agent
sdl-mcp serve --stdio

# Or run without installing using npx
npx --yes sdl-mcp@latest init -y --auto-index
npx --yes sdl-mcp@latest serve --stdio
```

--------------------------------

### Multi-Agent Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

An example demonstrating a multi-agent setup using a shared SDL-MCP HTTP server.

```APIDOC
## Multi-Agent Example

Illustrates setting up a shared SDL-MCP HTTP server and connecting multiple agents.

### Setup Steps

1.  **Terminal 1: Start the shared server**
    ```bash
    sdl-mcp serve --http --port 3000
    ```

2.  **Terminal 2: Agent A connects**
    (Configure Agent A using the HTTP transport settings, e.g., Claude Code config)

3.  **Terminal 3: Agent B connects**
    (Configure Agent B using the HTTP transport settings, e.g., Cursor config)

4.  **Terminal 4: Agent C connects**
    (e.g., A CI pipeline using `curl` to interact with the `/mcp` endpoint)

### Workflow
Each agent connects to the same server but operates within its own isolated MCP session. This allows for concurrent, independent workflows, such as Agent A working on authentication modules while Agent B explores the database layer.
```

--------------------------------

### Get Repository Overview (Stats Level)

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/mcp-tools-reference.md

Use `level: "stats"` for the most token-efficient repository overview. This is the recommended starting point before escalating to more detailed levels.

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

--------------------------------

### Install and Build SDL-MCP Plugin

Source: https://github.com/glitterkill/sdl-mcp/blob/main/templates/plugin-template/README.md

Standard commands to install dependencies and build the plugin. Ensure you have run 'npm install' before building.

```bash
npm install
npm run build
```

--------------------------------

### Install and Generate SCIP for Go

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/scip-integration.md

Installs the SCIP emitter for Go and generates an index.scip file. Ensure Go is installed and configured in your PATH.

```bash
# Install the emitter
go install github.com/sourcegraph/scip-go/cmd/scip-go@latest

# Generate the SCIP index
scip-go --output index.scip
```

--------------------------------

### SDL-MCP Configuration File Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-author-guide.md

An example of the sdlmcp.config.json file, showing repository configuration, graph database path, policy settings, and plugin configuration.

```json
{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": "/path/to/repo"
    }
  ],
  "graphDatabase": { "path": "./data/sdl-mcp-graph.lbug" },
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": true
  },
  "plugins": {
    "paths": ["./my-lang-plugin/dist/index.js"],
    "enabled": true,
    "strictVersioning": true
  }
}
```

--------------------------------

### Create Java Main Class

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/testing.md

Example of creating a simple 'Main.java' file to print a message. This is a basic setup for Java projects.

```java
public class Main {
    public static void main(String[] args) {
        System.out.println("Hello from Java");
    }
}
```

--------------------------------

### Starting the HTTP Server

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Commands to start the SDL-MCP HTTP server with various configurations.

```APIDOC
## Starting the HTTP Server

Commands to start the SDL-MCP HTTP server with various configurations.

### Basic Usage
```bash
sdl-mcp serve --http
```

### Custom Host and Port
```bash
sdl-mcp serve --http --host 0.0.0.0 --port 8080
```

### With Explicit Configuration File
```bash
sdl-mcp serve --http --port 3000 --config "C:\\sdl\\global\\sdlmcp.config.json"
```

### Disable File Watcher
```bash
sdl-mcp serve --http --port 3000 --no-watch
```

**Note:** On startup, the server prints a bearer token to stderr which is required for agent authentication.
```

--------------------------------

### Install and Initialize SDL-MCP

Source: https://github.com/glitterkill/sdl-mcp/blob/main/README.md

Install the SDL-MCP package globally and then initialize it to index your repository. The `--auto-index` flag automatically detects and indexes supported languages.

```bash
npm install -g sdl-mcp
sdl-mcp init -y --auto-index
```

--------------------------------

### Execute Runtime Script Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/runtime-execution.md

An example of how to configure a runtime execution, including repository ID, runtime environment, arguments, output mode, timeout, and query terms for response filtering.

```json
{
  "repoId": "my-repo",
  "runtime": "node",
  "args": ["scripts/check.mjs"],
  "outputMode": "summary",
  "timeoutMs": 30000,
  "queryTerms": ["FAIL", "Error"],
  "maxResponseLines": 100
}
```

--------------------------------

### Install sdl-mcp From Source

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Installs sdl-mcp by cloning the repository, installing dependencies, building the project, and linking it locally. This method is typically used for development or when contributing to the project.

```bash
git clone <repository-url>
cd sdl-mcp
npm install
npm run build
npm link
```

--------------------------------

### Install and Run Workflow Locally with act

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/ci-memory-sync-setup.md

Installs the 'act' tool and demonstrates how to run a GitHub Actions workflow locally for testing purposes.

```bash
# Install act
brew install act  # macOS
# or
choco install act  # Windows

# Run workflow locally
act push -j sync-memory
```

--------------------------------

### Recommended Configuration for Small Projects

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/semantic-embeddings-setup.md

A minimal configuration for small personal projects, enabling semantic search with a default embedding model. This setup is free and requires minimal setup.

```jsonc
{
  "semantic": {
    "enabled": true,
    "model": "jina-embeddings-v2-base-code",
  },
}
```

--------------------------------

### Run Without Installing (npx)

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/cli-reference.md

Demonstrates how to execute SDL-MCP commands without a global installation using npx.

```APIDOC
## Run Without Installing (npx)

If you do not want a global install, run commands through `npx`:

```bash
npx --yes sdl-mcp@latest version
npx --yes sdl-mcp@latest doctor
npx --yes sdl-mcp@latest info
```

In this document, replace `sdl-mcp` with `npx --yes sdl-mcp@latest` if you use `npx`.
```

--------------------------------

### Install Ollama and Pull Models

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Instructions for installing Ollama and pulling various language models. Ollama allows running models locally.

```bash
# 1. Install Ollama from https://ollama.com/download
#    Windows: winget install Ollama.Ollama
#    macOS:   brew install ollama
#    Linux:   curl -fsSL https://ollama.com/install.sh | sh

# 2. Start the Ollama server (runs on port 11434 by default)
ollama serve

# 3. Pull a model — pick one:
ollama pull llama3.2          # 3B params, fast, low RAM (~2 GB)
ollama pull llama3.1          # 8B params, good balance (~5 GB)
ollama pull qwen2.5-coder     # 7B params, code-focused (~4.5 GB)
ollama pull mistral            # 7B params, general-purpose (~4 GB)
ollama pull deepseek-coder-v2  # 16B params, best code quality (~9 GB)
```

--------------------------------

### Start SDL-MCP Service

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-security.md

Initiate the SDL-MCP service. This command starts the main index process for the application.

```bash
sudo -u sdl-mcp sdl-mcp index
```

--------------------------------

### Start SDL-MCP HTTP Server

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Use these commands to start the SDL-MCP HTTP server with various configurations for host, port, and disabling the file watcher.

```bash
# Basic (localhost:3000)
sdl-mcp serve --http

```

```bash
# Custom host and port
sdl-mcp serve --http --host 0.0.0.0 --port 8080

```

```bash
# With explicit config
sdl-mcp serve --http --port 3000 --config "C:\\sdl\\global\\sdlmcp.config.json"

```

```bash
# Disable file watcher (if your environment has issues with it)
sdl-mcp serve --http --port 3000 --no-watch

```

--------------------------------

### Benchmark Console Output Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/benchmark-guardrails.md

Example of console output from the benchmark suite, showing detailed metrics for indexing and quality, along with threshold and regression summaries.

```text
=== Benchmark Metrics ===
Indexing:
  Time per file:      150ms
  Time per symbol:    5ms
Quality:
  Symbols per file:   25.5
  Edges per symbol:   12.3
...

=== Threshold Evaluation ===
Status: ✅ PASSED
Total: 10
Passed: 10
Failed: 0

=== Regression Summary ===
Status: ✅ PASSED
Improved: 2
Degraded: 0
Neutral: 8
```

--------------------------------

### Example SDL-MCP Configuration

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/ci-memory-sync-setup.md

An example JSON configuration for SDL-MCP, detailing repository settings, graph database path, policy constraints, and indexing options. Adjust `maxFileBytes` and ignore patterns as needed.

```json
{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": "/path/to/your/repo",
      "ignore": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
      "maxFileBytes": 2000000
    }
  ],
  "graphDatabase": { "path": "./data/sdl-mcp-graph.lbug" },
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": true
  },
  "indexing": {
    "concurrency": 8,
    "enableFileWatching": false
  }
}
```

--------------------------------

### Setup Project Directory and Build

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/release-test.md

Navigate to the project directory and perform a clean build of all components. This ensures the project is in a buildable state before further testing.

```powershell
cd F:\Claude\projects\sdl-mcp\sdl-mcp

# Clean build
npm run build:all

# Clean graph database (fresh start)
Remove-Item -Force .\data\sdl-mcp-graph.lbug -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .\.sdl-sync -ErrorAction SilentlyContinue
```

--------------------------------

### Install ONNX Dependencies

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/semantic-embeddings-setup.md

Install the necessary ONNX runtime and tokenizers packages for Node.js. Ensure these are installed before proceeding with model setup.

```bash
npm install onnxruntime-node tokenizers
```

--------------------------------

### Test Adapter with Sample File

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-author-guide.md

Create a test file with a '.mylang' extension, run the indexer using 'sdl-mcp index', and check the logs for any errors to verify the adapter's functionality.

```bash
# Create test file
echo 'function test() {}' > test.mylang

# Run indexer
sdl-mcp index

# Check logs for errors
```

--------------------------------

### Retrieve Action Schema and Examples

Source: https://github.com/glitterkill/sdl-mcp/blob/main/SDL.md

Use `sdl.manual` to get the exact schema or examples for a known action. Specify actions or a query.

```javascript
sdl.manual
```

--------------------------------

### Example Test File

Source: https://github.com/glitterkill/sdl-mcp/blob/main/examples/example-plugin/README.md

A sample '.ex' file demonstrating syntax for testing your custom language adapter.

```ex
// example.ex
import "stdlib"

class MyClass:
  fn myMethod():
    print("Hello, world!")
```

--------------------------------

### Create and Configure VM for Sandboxing

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-security.md

Set up a virtual machine using virt-install for maximum security sandboxing. This involves defining resources like RAM and disk.

```bash
# Create VM
virt-install --name sdl-mcp-worker \
  --ram 1024 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/sdl-mcp-worker.qcow2,size=10 \
  --network none
```

--------------------------------

### Get Full Action Schema with Examples

Source: https://github.com/glitterkill/sdl-mcp/blob/main/SDL.md

Retrieve the full schema for a specific action, including examples, by using `sdl.manual` with the `includeExamples` option set to true.

```javascript
sdl.manual({ actions: ["<name>"], includeExamples: true })
```

--------------------------------

### Create and Build a Plugin

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-quick-reference.md

Use these bash commands to copy the plugin template, navigate into the directory, install dependencies, and build the plugin.

```bash
cp -r templates/plugin-template my-lang-plugin
cd my-lang-plugin

npm install
npm run build
```

--------------------------------

### Build and Run Adapter Harness Directly

Source: https://github.com/glitterkill/sdl-mcp/blob/main/tests/harness/README.md

Build the project first, then run the adapter harness entrypoint script directly using Node.js.

```bash
npm run build
node dist/tests/harness/adapter-runner.js
```

--------------------------------

### Get Context

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/agent-workflows.md

Use `sdl.context` when Code Mode is enabled for context retrieval. If Code Mode is disabled, follow the manual ladder starting with `repo.overview`.

```javascript
sdl.context({
  taskText: "Explain this code snippet.",
  code: "function greet() { return 'Hello'; }"
});
```

--------------------------------

### Nomic Model Verification Output

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/semantic-embeddings-setup.md

Example output from the 'doctor' command indicating a successful setup of the Nomic embedding model, including version and file status.

```text
Semantic embedding models .................. PASS
  onnxruntime-node: 1.24.x
  tokenizers: available
  model: nomic-embed-text-v1.5 (768d, files present)
```

--------------------------------

### Copy Plugin to VM and Run

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-security.md

Transfer the plugin to the virtual machine using scp and execute it using the sdl-mcp command.

```bash
# Copy and run
scp my-plugin.qcow2 root@vm:/opt/sdl-mcp/plugins/
ssh root@vm "sdl-mcp index"
```

--------------------------------

### Escalate Context Retrieval

Source: https://github.com/glitterkill/sdl-mcp/blob/main/SDL.md

When `sdl.context` returns insufficient results, use these methods to escalate. Start by narrowing down to a specific symbol, then get its card, build a bounded slice, or retrieve skeleton/hot path code.

```json
// 1. Narrow to a symbol
sdl.symbol.search({ "repoId": "<repoId>", "query": "handleRequest", "kinds": ["function"], "limit": 10 })
```

```json
// 2. Get the card (ETag-aware)
sdl.symbol.getCard({ "repoId": "<repoId>", "symbolRef": { "name": "handleRequest", "file": "src/server.ts" }, "ifNoneMatch": "<prevEtag>" })
```

```json
// 3. Build a bounded slice
sdl.slice.build({
  "repoId": "<repoId>",
  "entrySymbols": ["<symbolId>"],
  "taskText": "trace auth failure",
  "budget": { "maxCards": 30, "maxEstimatedTokens": 4000 },
  "minConfidence": 0.5,
  "wireFormat": "compact",
  "cardDetail": "signature",
  "knownCardEtags": { "<symId>": "<etag>" }
})
```

```json
// 4. If still need code
sdl.code.getSkeleton({ "repoId": "<repoId>", "symbolId": "<id>", "maxLines": 120, "maxTokens": 900 })
```

```json
sdl.code.getHotPath({ "repoId": "<repoId>", "symbolId": "<id>", "identifiersToFind": ["validate","throw"], "contextLines": 2 })
```

```json
// 5. Last resort — must cite reason + identifiers
sdl.code.needWindow({ "repoId": "<repoId>", "symbolId": "<id>", "reason": "confirm branch ordering", "expectedLines": 60, "identifiersToFind": ["validate"] })
```

--------------------------------

### Install sdl-mcp Globally

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Installs the sdl-mcp package globally using npm. After installation, you can run the `sdl-mcp version` command to verify the installation.

```bash
npm install -g sdl-mcp
sdl-mcp version
```

--------------------------------

### Prepare External Repositories for Benchmarking

Source: https://github.com/glitterkill/sdl-mcp/blob/main/benchmarks/real-world/CLAIMS.md

Execute this command to set up external repositories required for the benchmarking process.

```bash
npm run benchmark:setup-external
```

--------------------------------

### Install and Generate SCIP for TypeScript/JavaScript

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/scip-integration.md

Installs the SCIP emitter for TypeScript/JavaScript and generates an index.scip file. Ensure Node.js and npm are installed.

```bash
# Install the emitter
npm install -D @sourcegraph/scip-typescript

# Generate the SCIP index
npx scip-typescript index --output index.scip
```

--------------------------------

### Configuration with Normalized Paths

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/cross-platform-validation.md

This JSON configuration example demonstrates how to specify repository paths and ignore patterns. Ensure that `rootPath` is an absolute path for clarity and consistency.

```json
{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": "/absolute/path/to/repo",
      "ignore": ["**/node_modules/**", "**/dist/**"]
    }
  ],
  "graphDatabase": { "path": "./data/sdl-mcp-graph.lbug" },
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": true
  }
}
```

--------------------------------

### Run sdl-mcp Without Global Installation

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

Executes the latest version of sdl-mcp without requiring a global installation. This is useful for trying out the tool or running it in environments where global installations are not permitted.

```bash
npx --yes sdl-mcp@latest version
```

--------------------------------

### Command: sdl-mcp init

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/cli-reference.md

Initializes configuration and optional client templates for SDL-MCP.

```APIDOC
## `sdl-mcp init`

Initialize configuration and optional client template.

```bash
sdl-mcp init --client codex --repo-path . --languages ts,py,go
sdl-mcp init -y --auto-index
sdl-mcp init -y --dry-run
```

Key options:

- `--client <claude-code|codex|gemini|opencode>`
- `--repo-path <PATH>` (default: current directory)
- `--languages <comma-separated>` (default: all supported languages)
- `-f, --force`
- `-y, --yes` (non-interactive mode with repo/language auto-detection)
- `--auto-index` (run inline incremental index and doctor checks)
- `--dry-run` (print generated config without writing files)
- `--enforce-agent-tools` (generate SDL-first enforcement assets for the chosen client: enables runtime, exclusive Code Mode, and writes client-specific instruction/hook files)
```

--------------------------------

### Unit Test Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-quick-reference.md

Example of a unit test for an adapter, verifying symbol extraction functionality.

```typescript
describe("My Adapter", () => {
  it("should extract functions", () => {
    const symbols = adapter.extractSymbols(tree, content, filePath);
    assert.ok(symbols.some((s) => s.name === "myFunction"));
  });
});
```

--------------------------------

### Quick Config: CI/Testing (No Dependencies)

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/semantic-engine.md

Configuration for CI or testing environments where no external dependencies are required, using a mock provider for semantic features.

```json
{
  "semantic": {
    "enabled": true,
    "provider": "mock",
    "generateSummaries": false
  }
}
```

--------------------------------

### Install @sdl-mcp/ladybug

Source: https://github.com/glitterkill/sdl-mcp/blob/main/packages/kuzu-split/out/ladybug/README.md

Install the main package using npm. It automatically selects the correct platform package via optionalDependencies.

```bash
npm install @sdl-mcp/ladybug
```

--------------------------------

### API Examples

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/search-edit-tool.md

Provides examples of API requests for renaming identifiers, rewriting symbol home files, and appending headers.

```APIDOC
## Examples

### Rename an identifier across `src/`

```json
{
  "mode": "preview",
  "repoId": "myrepo",
  "targeting": "text",
  "query": { "literal": "legacyAuth", "replacement": "authV2", "global": true },
  "editMode": "replacePattern",
  "filters": { "include": ["src/**/*.ts"] }
}
```

Apply with the returned `planHandle`.

### Rewrite a symbol's home file

```json
{
  "mode": "preview",
  "repoId": "myrepo",
  "targeting": "symbol",
  "query": {
    "symbolRef": { "name": "handleAuth", "file": "src/server.ts" },
    "literal": "handleAuth",
    "replacement": "handleAuthV2",
    "global": true
  },
  "editMode": "replacePattern"
}
```

### Append a header to every config file

```json
{
  "mode": "preview",
  "repoId": "myrepo",
  "targeting": "text",
  "query": { "regex": "^#", "append": "\n# audited 2026-04-20" },
  "editMode": "append",
  "filters": { "extensions": [".yaml", ".yml"] }
}
```
```

--------------------------------

### Golden File Test Example

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-quick-reference.md

Example of a golden file test comparing extracted symbols against a predefined JSON file.

```typescript
const symbols = adapter.extractSymbols(tree, content, filePath);
const golden = JSON.parse(readFileSync("expected-symbols.json"));
assert.deepStrictEqual(symbols, golden);
```

--------------------------------

### Distribute Plugin via Git Repository

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-author-guide.md

Steps to initialize a Git repository, push your plugin, and allow users to install it directly via npm or run it using npx.

```bash
# 1. Create Git repository
git init
git add .
git commit -m "Initial plugin"
git remote add origin https://github.com/user/my-lang-plugin.git
git push

# 2. Users can install via Git
npm install https://github.com/user/my-lang-plugin.git

# 3. Or run SDL-MCP without installing (npx)
npx --yes sdl-mcp@latest serve --stdio -c ./config/sdlmcp.config.json
```

--------------------------------

### Initialize Plugin Project (Bash)

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-author-guide.md

Basic commands to create a new directory for your plugin and initialize an npm project within it.

```bash
mkdir my-lang-plugin
cd my-lang-plugin
npm init -y
```

--------------------------------

### HTTP Server Startup Output

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/getting-started.md

The server prints its listening address and a bearer token to stderr on startup. This token is required for agent authentication.

```text
[sdl-mcp] HTTP server listening on http://localhost:3000
[sdl-mcp] HTTP auth token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

```

--------------------------------

### Install ONNX Dependencies

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/feature-deep-dives/semantic-embeddings-setup.md

Installs the required ONNX runtime and tokenizers packages using npm. This is the first step to set up the environment for SDL-MCP.

```bash
cd sdl-mcp
npm install onnxruntime-node tokenizers
```

--------------------------------

### Configuring Multiple Plugins

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-author-guide.md

Example of the 'plugins.paths' configuration, specifying an array of file paths for multiple plugins to be loaded by SDL-MCP.

```json
{
  "plugins": {
    "paths": [
      "./plugins/plugin1/dist/index.js",
      "./plugins/plugin2/dist/index.js",
      "./plugins/plugin3/dist/index.js"
    ],
    "enabled": true
  }
}
```

--------------------------------

### Example Test Harness Output

Source: https://github.com/glitterkill/sdl-mcp/blob/main/tests/harness/README-ADAPTER-HARNESS.md

An example of the output generated by the adapter test harness for a specific language, showing test status and duration.

```text
Testing Language: rust
==================================================
⚠️  Symbol extraction: tests/fixtures/rust/symbols.rs (no expected file)
⚠️  Import extraction: tests/fixtures/rust/imports.rs (no expected file)
⚠️  Call extraction: tests/fixtures/rust/calls.rs (no expected file)

--- Summary for rust ---
Passed: 3
Failed: 0
Duration: 17ms
```

--------------------------------

### Example Request for Help

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/benchmark-failure-guide.md

A markdown template for requesting help with benchmark regressions, including context, failure details, changes made, investigation steps, and specific questions.

```markdown
@tech-lead Need help with benchmark regression

**Context:**
Working on improved error handling in slice building.

**Failure:**
```
sliceBuildTimeMs: Increased by 25% (threshold: 25%)
Baseline: 430ms
Current: 537ms
```

**Changes:**
- Added try/catch around slice operations
- Added error logging on failures
- See: src/graph/slice.ts:245-260

**Investigation:**
- Profiled the code - overhead from error logging
- Tried disabling logging - drops to 460ms (still above threshold)
- Suspected: additional try/catch blocks adding overhead

**Question:**
Is this overhead acceptable for improved error handling?
Should we adjust the threshold or optimize further?

```

--------------------------------

### Local Distribution of SDL-MCP Plugin

Source: https://github.com/glitterkill/sdl-mcp/blob/main/docs/plugin-sdk-author-guide.md

Commands for creating a local tarball of the plugin using 'npm pack' and installing it, or installing directly from a local directory.

```bash
# Create tarball
npm pack

# Install from local tarball
npm install sdl-mcp-my-lang-plugin-1.0.0.tgz

# Or install from directory
npm install ./my-lang-plugin
```