4.2 KiB
CLI and MCP usage
Tool behavior
scout_search accepts a natural-language query, top_k from 1 to 50, and max_chars from 100 to 100,000. It returns ranked snippets and up to three graph neighbors within the shared source-character budget. Overlapping source lines are not repeated. Scores are not probabilities.
With a model, the default mode is dense, selected from the complete validation results. lexical uses BM25, which is useful for exact identifiers, and hybrid combines the two rankings. Without a model the CLI and MCP server default to lexical. The CLI exposes the same choice as --mode.
Markdown is excluded from search by default; set include_docs=true to include it. An optional language filter narrows candidates before rank fusion, for example to python or typescript. CLI equivalents are --include-docs and --language python.
Each snippet includes an opaque symbol ID, repository-relative path, line range, source text, file SHA-256, and verification/truncation flags. The response also identifies the index snapshot and model fingerprint. Truncation occurs at line boundaries.
scout_read takes an ID returned by the current index. It checks the source hash again before returning a larger range. It accepts no arbitrary filesystem path.
scout_status describes the loaded index. scout_feedback is available only with an explicit trace path; it accepts IDs actually returned by one of the last 1,000 searches in the current process. Feedback is stored locally and never updates serving weights.
Example MCP host configuration
Use the executable in the environment where the package was installed. Replace all paths:
{
"mcpServers": {
"micro-scout": {
"command": "/absolute/path/to/micro-scout/.venv/bin/micro-scout",
"args": [
"serve",
"--index", "/absolute/path/to/project/.micro-scout/index.sqlite",
"--model", "/absolute/path/to/micro-scout/runs/minilm-v1/best",
"--device", "cpu",
"--trace", "/absolute/path/to/micro-scout/runs/session.jsonl"
],
"env": {"OPENBLAS_NUM_THREADS": "1"}
}
}
}
The server uses the official MCP Python SDK v1 maintenance line, pinned below v2. It speaks stdio and does not open a network listener. The weights and index stay resident for the server's lifetime. A compatible host can call these tools; this alone does not establish downstream model quality.
Files and index updates
Indexing honors Git's ignored-file rules when available and skips hidden directories, common dependency/build directories, symlinks, unsupported extensions, and files above 1 MB. Python symbols use AST boundaries. Other supported text/code formats use 60-line chunks. Incomplete Python falls back to chunks.
Python functions longer than 48 lines also get 32-line search fragments with an 8-line overlap. The full symbol remains available through each fragment's parent_id. This gives the retriever access to code beyond the beginning of a long function. Neural input is still capped at 256 tokens per candidate; very long individual lines can exceed that representation budget. BM25 searches the complete candidate text.
An index is one SQLite file, atomically replaced after a successful build. A model fingerprint prevents combining incompatible query and code embeddings. Reindexing with unchanged weights reuses embeddings for unchanged normalized code.
Returned files are checked against their indexed content hashes. Modified or missing files are excluded with warnings; reads of stale IDs fail. New files require reindexing. This is a snapshot workflow, not a filesystem watcher. Restart the server after rebuilding an index so it loads the new snapshot.
Trace contents
With --trace, the local JSONL trace records queries, returned IDs, snapshot, latency, and feedback. Source snippets are not copied into search trace records. Without this option, query traces are not written. The repository's default runs/ directory is excluded from Git.
The tool never executes indexed code. Source text is untrusted input for the consuming model and should be treated as data, including any instruction-like comments it contains.