MCP SERVER
Workspace context management — the first call in every session and the only source of truth for paths.
| Tool | Purpose | Returns |
|---|---|---|
| activate | Set the active context for the session — required before any other tool works | Context metadata, cwd path |
| resolve | Convert a hint string to full workspace metadata without changing active context | Path, branch, type, personal flag |
| info | Consolidated snapshot — metadata, git state, dirty files, recent commits in one call | Context + git state object |
| list_contexts | Enumerate all repos, worktrees, and compound contexts in the workspace | Array of workspace entries |
| create | Create worktree(s) for shared repos with auto-generated branch from description | Branch name, worktree paths |
| remove | Tear down a worktree or compound context with safety checks | Removal confirmation |
| read | Read file(s) from a context — single path or array for batch. Supports offset/limit/tail | File content, size, metadata |
| write | Write a file to a context — creates parent dirs, rejects identical content | Write confirmation, byte size |
| edit | Find-and-replace within a file — single edit or batch array. Fails on ambiguous matches | Edit result, replacement count |
| delete | Delete a file from a context | Deletion confirmation |
| move | Move or rename a file within a context | New path confirmation |
| copy | Copy a file within or across contexts via dest_hint | Copy confirmation |
| list_files | List directory contents, optionally filtered by glob pattern | Array of entries |
| glob | Find files by glob pattern — uses ripgrep, falls back to Bun.Glob. Respects .gitignore | Paths sorted by mtime (newest first) |
| grep | Search file contents by regex via ripgrep — returns file, line number, and match content | Matches sorted by file mtime |
| cat | Concatenate multiple files into one text stream with headers — lower token cost than batch read | Single text block with ── path ── separators |
| read_image | Read image files (PNG, JPG, SVG, etc.) and return MCP image content for visual analysis | Base64 image or SVG text |
| push | Push current branch to remote — auto-commits dirty personal repos, creates GitLab project if needed | SHA, webUrl, commit count |
| push_all | Commit and push all dirty personal repos in the workspace in one sweep | Per-repo status summary |
| refresh | Invalidate workspace caches and re-scan from disk after topology changes | Fresh workspace state |
Every tool in the ecosystem needs to know where code lives. Scout solves this once through hint resolution — a short string like "subs" or "billing" becomes a fully resolved context with path, branch, type, and ownership classification. No tool constructs paths manually. No tool calls pwd or ls. The hint is the universal entry point.
A hint resolves to one of three types. A repo is a standalone git repository. A worktree is a branch checkout linked to a parent repo — used for shared repos where you can't commit to main. A directory is a non-git folder. The type determines which operations are valid and which workflow applies.
Scout classifies every repo by ownership. Personal repos (your GitLab namespace) commit directly to main and push. Shared repos require worktrees — scout_create generates a branch, sets up the worktree, and auto-activates it. This classification is the fork in every git workflow: push vs MR, direct commit vs branch isolation.
When work spans multiple repos, scout creates a compound context — a single slug that resolves to multiple worktrees. Activate once, operate across repos. The compound tracks which repos are involved and provides per-repo context when tools need individual paths.
Pass an array of paths instead of a single string. Scout resolves the hint once and reads all files in a single call. Returns structured JSON per file with content, size, and modification time. Eliminates redundant context resolution when exploring multiple files.
Pass an edits array — each entry specifies path, oldString, and newString. One hint resolution, multiple file edits. Returns per-edit results with replacement counts. Critical for refactoring across files without N separate tool calls.
Concatenate multiple files into a single text stream with ── path ── headers. No JSON envelopes, no per-file metadata overhead. Lower token cost than batch read when you need to review related files together rather than process them individually.
git-helpers — shared git primitives (branch detection, remote URL parsing, GitLab username resolution). mcp-helpers — MCP server registration and tool wiring. Scout has no runtime dependencies on other MCP servers. It is the foundation layer — everything depends on it, it depends on nothing in the MCP ecosystem.
git-ops takes the cwd path from scout_resolve to run commits, pushes, and rebases. Every MCP server that reads or writes files uses scout as its file system layer. The workspace AGENTS.md enforces this as a hard rule — "all paths come from scout." Scout also exports library modules (client, workspace, state, errors, files) consumed by other servers at build time.
The server that knows where everything is — so nothing else has to.