CodeScope

CodeScope is a local, read-only Model Context Protocol (MCP) bridge for inspecting explicitly configured repositories. It gives an agent bounded filesystem and Git reads without accepting arbitrary paths, repository roots, or write operations from the conversation.

Read this in Spanish · User guide · Guía de usuario

What it does

• maps short repository aliases to local absolute roots;

• reads UTF-8 files and bounded directory listings through an allowlist;

• reads Git status, history, references, and bounded diffs with helper execution disabled;

• keeps repository selection and session access explicit when that mode is enabled;

• exposes versioned advisory design guidance;

• can add Codebase Memory or Context Mode only when a repository-specific, read-only binding has been configured and validated;

• runs over local stdio by default. A tunnel is an optional deployment layer.

The bridge does not provide a general filesystem server, a Git write API, an arbitrary MCP proxy, or a public HTTP listener by default.

Related MCP server: fsguard-mcp

Requirements

• Node.js 24.19 or newer;

• Git available as git or configured with an absolute executable path;

• a local configuration file containing one or more read-only repository entries.

Quick start

From the project directory:

npm ci
Copy-Item config.example.json config.json

Edit config.json and replace the example root with an absolute path on the local machine. Every repository must keep read_only set to true:

{
  "git_binary": "git",
  "default_repository": "main",
  "repositories": {
    "main": {
      "root": "C:/path/to/repository",
      "read_only": true
    }
  },
  "optional_backends": {
    "auto_discover": false,
    "bindings": {}
  }
}

Start the local stdio server:

$env:CODESCOPE_CONFIG = (Resolve-Path .\config.json).Path
node .\src\server.mjs

The process reads requests from stdio and writes protocol responses to stdout. Operational logs go to stderr. The bridge does not start a tunnel unless a separate launcher is explicitly used.

npm command

The package includes a small Node CLI. From a checkout, or after installing the package in a local application directory:

npm install .
npx codescope init
npx codescope serve --config .\\config.json

init only creates a local template and refuses to replace an existing file unless --force is supplied. serve starts the same stdio bridge as node src/server.mjs; it does not start a tunnel.

The npm package deliberately excludes deps/, managed profiles, caches, test evidence, and real repository content. The optional Windows tunnel client is an external installation. Set CODESCOPE_TUNNEL_CLIENT_PATH to its absolute executable path, CODESCOPE_TUNNEL_CLIENT_ROOT to the separately verified release metadata directory, and optionally CODESCOPE_TUNNEL_RUN_DIR and CODESCOPE_TUNNEL_SAMPLE_CONFIG for writable runtime state and a sample profile. Credentials remain in the process environment or the tunnel client’s secret store.

Repository and session access

Repository paths never come from an MCP call. The call supplies an alias such as main; the configuration resolves that alias to the approved root. When session_access.mode is session_select, the client must first show the available aliases with bridge_access_status and then explicitly select the alias with bridge_access_select. A session can release one alias or reset all selections.

The model-facing instructions in chatgpt/ are written in English so they are portable between hosts. They explicitly require the agent to keep the user-facing conversation in the user’s language.

Available tools

The base catalog contains read-only filesystem and Git tools plus design_guidance. The exact catalog is returned by MCP tools/list for the active configuration. Optional tools are advertised only after their repository binding has passed validation.

All results are bounded by byte, entry, line, match, depth, timeout, and concurrency limits. Large reads and diffs use signed continuation cursors. Unknown tools, hidden write tools, resources, prompts, sampling, and elicitation are rejected.

Optional integrations

Codebase Memory and Context Mode are optional. Autodiscovery only checks known local installation paths; it does not start a process, index a repository, read credentials, or create a binding. To expose an optional backend, configure it for a specific repository alias, set it to read-only, and restrict its project, root, corpus, and storage paths to that repository. If the binding is not ready, the optional tool stays unavailable while the base filesystem and Git tools continue to work.

Ponytail instructions are also optional and are advertised only after the local installation passes its marker checks. Design guidance remains available without Ponytail.

Security boundary

• repository roots are absolute, configured locally, and checked again before access;

• traversal, alternate root syntaxes, symlinks, reparse points, hard-linked files, and protected paths are rejected;

• .git, environment files, credentials, private keys, certificates, and matching secret content are denied or redacted;

• Git runs without a shell, terminal prompts, external diff helpers, or text converters, and scopes safe.directory to the selected canonical root;

• no repository write operation is exposed;

• tunnel credentials, if a deployment uses a tunnel, must come from the process environment or the tunnel client’s secret store rather than MCP arguments or repository files.

These controls are enforced by the bridge. MCP annotations such as readOnlyHint are descriptive metadata and are not used as an authorization mechanism.

Checks

npm run check
npm run doctor

npm run check creates and removes disposable test data and verifies filesystem, Git, cursor, limit, secret, and MCP-surface invariants. npm run doctor checks the configured repositories without starting a tunnel. Tests that exercise a separately launched bridge require BRIDGE_COMMAND and BRIDGE_ARGS_JSON; an unset harness is reported as blocked rather than silently passing.

Windows launcher and TUI

The PowerShell TUI and launcher are optional Windows tooling. They use paths relative to the project or paths resolved from the current user’s environment; they do not require a particular Windows account name. Review the English user guide or the Spanish user guide before enabling a tunnel.

Project status

The repository is in preproduction. The public npm surface now has an explicit file allowlist and excludes local profiles, historical evidence, caches, vendored runtimes, tests, and repository content. Before publishing, choose the project license and run the authenticated tunnel end-to-end canary with an external tunnel client.