scplus-mcp

Prepared-index code intelligence for agents and operators.

scplus-mcp is the repository and npm package for scplus, a local code-intelligence engine that serves structural, exact-query, related-search, and research workflows from a validated repo-local index. It ships three connected surfaces: the scplus-mcp MCP server for coding agents, a persistent local bridge for automation, and the scplus-cli Bubble Tea operator console for humans.

The project is built around one operating contract: build a prepared local index, read from one validated active generation at a time, and fail loudly when freshness or validation is broken instead of quietly answering from stale state.

Table of Contents

• Key Features

• Naming And Product Surfaces

• Tech Stack

• Prerequisites

• Getting Started

• MCP Client Setup

• Models And Embedding Providers

• Architecture

• Environment Variables

• Available Scripts

• MCP Resource And Tool Catalog

• Bridge And Automation Surface

• Human CLI Surface

• Benchmarks

• References

• License

Related MCP server: codemap

Key Features

• Prepared exact-query tools for deterministic lookups such as symbol, word, outline, deps, status, and changes

• Ranked related search and broad research over persisted file, chunk, identifier, structure, cluster, and hub artifacts

• One shared backend core for MCP and the human CLI, with the CLI connected over the persistent bridge-serve JSON-line transport

• Repo-local SQLite machine state rooted at .scplus/, with active/pending generation promotion and explicit fresh, dirty, and blocked freshness states

• Loud failure semantics for invalid prepared state instead of silent fallback behavior

• Suggested hubs and semantic clusters generated from the prepared full index

• Shadow restore points for reversible AI-authored edits without mutating git history

• A separate Next.js landing/docs app under landing/, wired to the local package during development

• Committed real benchmark artifacts under docs/benchmarks/

Naming And Product Surfaces

This repository uses a few names that matter in different contexts:

Important context:

• The current source code uses .scplus/ as the repo-local state root via src/core/project-layout.ts.

• The runtime environment prefix used by current code is SCPLUS_.

If code and docs disagree, treat the code as authoritative.

Tech Stack

• Primary language: TypeScript (ESM)

• MCP transport: @modelcontextprotocol/sdk over stdio

• Prepared state store: SQLite at .scplus/state/index.sqlite

• Parsing: web-tree-sitter and tree-sitter-wasms

• Retrieval: lexical plus embedding-backed retrieval persisted into SQLite vector collections

• Embedding backends: Ollama by default, OpenAI-compatible embeddings optionally

• Human CLI: Go + Bubble Tea

• Go toolchain management: Pixi (go = 1.24.*)

• Landing/docs app: Next.js 16, React 19, Tailwind CSS 4, OpenNext/Cloudflare tooling

• Primary package manager: npm

Prerequisites

Install these before working on the repository:

• Node.js

• npm

• Pixi

• Git

Usually also needed for semantic indexing:

• Ollama, unless you explicitly choose an OpenAI-compatible embedding backend

Optional:

• Bun, if you prefer bunx when generating MCP config instead of npx

Notes:

• The repository does not currently ship a checked-in .env.example.

• The canonical onboarding path for the core package is the install script, not manual npm and pixi commands typed from memory.

Getting Started

Canonical install path

For the main developer/operator workflow, start with the installer:

git clone https://github.com/Cesar514/scplus-mcp.git
cd scplus-mcp
./install-scplus.sh

Treat ./install-scplus.sh as the primary local setup path for the package and CLI. Manual build steps are documented below so you understand what the installer is doing, but the intended bootstrap flow is through the script.

What ./install-scplus.sh does

The installer:

1. verifies node

2. verifies npm

3. verifies pixi

4. runs npm install

5. runs npm run build

6. runs npm run build:cli

7. runs npm link

8. verifies that scplus-mcp points at build/index.js

9. verifies that scplus-cli points at build/cli-launcher.js

10. runs a lightweight scplus-mcp tree "$ROOT_DIR" check

11. runs a lightweight scplus-cli doctor --root "$ROOT_DIR" check

If any prerequisite is missing, the script exits fatally instead of guessing.

What you should have after install

After a successful run:

• scplus-mcp should be on your PATH

• scplus-cli should be on your PATH

• the TypeScript build output should exist under build/

• the Bubble Tea launcher should exist under build/scplus-cli

Quick verification:

scplus-mcp doctor .
scplus-cli doctor --root .

Rebuilding after edits

After editing the TypeScript or Go sources, rebuild both shipped entrypoints with:

npm run build:all

This updates the already linked scplus-mcp and scplus-cli commands in place because npm link points them at this checkout’s build output.

Bootstrapping prepared state for the repository

Once the commands are installed, create prepared repo-local state:

scplus-mcp index .

Then validate it:

scplus-mcp validate-index .

The strongest success signal is a valid prepared index with:

• one active generation

• no pending generation unless a rebuild is in progress

• serving freshness reported as fresh

Verifying the user-facing surfaces

Run these from the repository root:

scplus-mcp tree .
scplus-mcp status .
scplus-cli snapshot --root .
scplus-cli doctor --root .

What these confirm:

• the MCP entrypoint is runnable

• the exact-query/git-aware surfaces are reachable

• the shared backend can serve the Go operator console

• the linked human CLI works against the same backend state

Working on the landing app

The landing/docs application under landing/ is a separate app with its own dependencies. Only do this if you are editing the site itself:

cd landing
npm install
npm run dev

The landing app serves on http://localhost:6767.

MCP Client Setup

Supported client targets

The init command can generate MCP config for:

• claude

• cursor

• vscode

• windsurf

• opencode

• codex

Generated config paths:

Generate config files automatically

Examples:

scplus-mcp init claude
scplus-mcp init cursor
scplus-mcp init vscode
scplus-mcp init windsurf
scplus-mcp init opencode
scplus-mcp init codex

Runner selection:

• by default, the command prefers bunx when it detects Bun and otherwise falls back to npx

• you can force a runner with --runner=npx or --runner=bunx

Examples:

scplus-mcp init codex --runner=npx
scplus-mcp init claude --runner=bunx

Manual Codex TOML configuration

If you want to configure Codex manually after using the local install script, add this to ~/.codex/config.toml:

[mcp_servers."scplus-mcp"]
command = "scplus-mcp"
args = []

[mcp_servers."scplus-mcp".env]
OLLAMA_EMBED_MODEL = "qwen3-embedding:0.6b-32k"
OLLAMA_CHAT_MODEL = "nemotron-3-nano:4b-128k"
OLLAMA_API_KEY = "YOUR_OLLAMA_API_KEY"
SCPLUS_EMBED_BATCH_SIZE = "8"

If you prefer running through npx or bunx instead of the locally linked command, the generated Codex config follows the same structure but sets:

• command = "npx" with args = ["-y", "scplus-mcp"], or

• command = "bunx" with args = ["scplus-mcp"]

Example JSON-style MCP config

For clients that use JSON config files, the generated config follows this general shape:

{
  "mcpServers": {
    "scplus-mcp": {
      "command": "bunx",
      "args": ["scplus-mcp"],
      "env": {
        "OLLAMA_EMBED_MODEL": "qwen3-embedding:0.6b-32k",
        "OLLAMA_CHAT_MODEL": "nemotron-3-nano:4b-128k",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY",
        "SCPLUS_EMBED_BATCH_SIZE": "8"
      }
    }
  }
}

The exact top-level key differs by client:

• mcpServers for Claude/Cursor/Windsurf-style configs

• servers for VS Code’s .vscode/mcp.json

• mcp for opencode.json

• TOML tables for Codex

Models And Embedding Providers

Important note on the Ollama model names in this repo

The model tags shown in this repository, especially:

• qwen3-embedding:0.6b-32k

• nemotron-3-nano:4b-128k

should be read as local Ollama variants used in the maintainer environment, not as a claim that these are wholly bespoke model families invented by the project.

Per the current maintainer workflow:

• the base models were downloaded from official Ollama sources

• the local setup then modified the context window configuration

So in practice, the README examples are documenting the project’s current local runtime tags and expectations, not asserting that the repository itself distributes new model architectures.

Provider overview

The code supports two embedding-provider modes:

Ollama path

The default code path is Ollama. A typical local setup looks like:

ollama pull qwen3-embedding:0.6b
ollama pull nemotron-3-nano:4b
ollama serve

Then, if your local environment uses extended-context variants or custom local tags, configure the env values that scplus-mcp should actually use:

export OLLAMA_EMBED_MODEL=qwen3-embedding:0.6b-32k
export OLLAMA_CHAT_MODEL=nemotron-3-nano:4b-128k

OpenAI-compatible path

For API-backed embeddings:

export SCPLUS_EMBED_PROVIDER=openai
export SCPLUS_OPENAI_API_KEY=YOUR_API_KEY
export SCPLUS_OPENAI_EMBED_MODEL=text-embedding-3-small

Optional custom base URL:

export SCPLUS_OPENAI_BASE_URL=https://your-proxy.example.com/v1

Architecture

Directory Structure

.
├── src/                     # TypeScript MCP server, backend core, indexing, retrieval, and tool implementations
│   ├── cli/                 # Shared backend core, bridge commands, doctor/report formatting
│   ├── core/                # Project layout, embeddings, parser runtime, locks, lifecycle helpers
│   ├── git/                 # Shadow restore-point logic
│   └── tools/               # Public indexing, query, lint, research, hub, and recovery tools
├── cli/                     # Go Bubble Tea operator console
│   ├── cmd/scplus-cli/      # Go CLI entrypoint
│   └── internal/            # Backend client, hubs flow, watcher integration, UI rendering
├── landing/                 # Separate Next.js marketing/docs application
├── docs/                    # Architecture notes, benchmark artifacts, snapshots, and images
├── test/                    # TypeScript tests, demos, and fixtures
├── .scplus/                 # Generated repo-local prepared state
├── package.json             # Root package metadata and Node build/test scripts
├── pixi.toml                # Project-local Go toolchain and CLI tasks
└── install-scplus.sh        # Canonical local install script

Runtime Surfaces

The repository exposes three distinct but connected runtime surfaces:

Important constraint:

• the Go CLI is not a second indexing engine

• it is a client of the same backend core used by the MCP server

Request Lifecycle

For agent/MCP requests:

Agent or MCP client
  -> scplus-mcp (src/index.ts)
  -> shared backend core / tool implementation
  -> prepared index in .scplus/state/index.sqlite
  -> formatted MCP response

For human operator requests:

scplus-cli
  -> Go backend client
  -> persistent bridge-serve session
  -> shared backend core
  -> prepared index in .scplus/state/index.sqlite
  -> operator UI panes / plain-text output

Serving And Generation Contract

The prepared-state contract documented by current code and architecture docs is:

• one active generation is the serving source of truth

• rebuilds and repairs can write a pending generation first

• pending generations are promoted only after validation succeeds

• serving freshness is explicit and can be fresh, dirty, or blocked

• invalid or blocked prepared state is supposed to fail loudly rather than degrade silently

The short authoritative architecture summary lives in architecture.md.

Query Model

The codebase implements a two-lane query model:

• Exact lane: symbol, word, outline, deps, status, changes

• Ranked lane: search with intent="related"

• Broad report lane: research

The product contract is that exact lookups remain the cheapest deterministic path and broader retrieval only runs when exact lookup is insufficient.

Project State Layout

Current code uses this repo-local state root:

.scplus/
├── state/
│   └── index.sqlite
├── hubs/
│   └── suggested/
└── locks/

Observed in the current checkout after indexing:

• .scplus/state/index.sqlite

• .scplus/hubs/suggested/

• .scplus/locks/

Current source code uses .scplus/.

Core Component Map

src/core/

• project-layout.ts defines the .scplus/ layout

• embeddings.ts manages provider-backed embeddings, SQLite vector namespaces, runtime options, and generation-aware cache invalidation

• tree-sitter.ts and parser.ts provide structural parsing

• runtime-locks.ts coordinates cross-process ownership

• process-lifecycle.ts manages idle shutdown, parent monitoring, and cleanup

src/tools/

• index-codebase.ts, index-stages.ts, and index-reliability.ts drive indexing, validation, and repair

• exact-query.ts implements the fast exact-query substrate

• query-intent.ts, unified-ranking.ts, semantic-search.ts, and semantic-identifiers.ts implement ranked search

• research.ts builds larger bounded subsystem reports

• feature-hub.ts, hub-suggestions.ts, and cluster-artifacts.ts implement hub and cluster views

• static-analysis.ts and blast-radius.ts provide diagnostics and usage tracing

• propose-commit.ts and write-freshness.ts implement guarded writes and synchronous freshness repair

cli/

• cli/cmd/scplus-cli/main.go is the Go entrypoint

• cli/internal/backend/ is the bridge client layer

• cli/internal/ui/ renders the operator console

• cli/internal/hubs/ powers manual hub creation

Operator Console Behavior

The shipped human CLI is more than a thin wrapper. The previous README’s high-value description is still accurate enough to preserve at a high level:

• it has a navigation pane, overview/content pane, detail pane, and jobs/logs area

• it exposes operator health, serving state, queue state, history, and observability

• it supports a command palette, filtering, export, and navigation history

• it streams backend events over the persistent bridge-serve transport

The committed plain snapshot is in cli-snapshot.txt.

Watcher And Scheduler Semantics

The backend, not the Go frontend, owns watcher behavior:

• native recursive filesystem watchers are not used by default

• a bounded backend scanner covers repositories in budgeted directory and file ticks

• bursty path changes are deduped

• the scheduler can queue or supersede stale pending work

• ordinary edits can become refresh jobs

• dependency/config changes can escalate to full index jobs

• job, watch, and log events are streamed over bridge-serve

• diagnostics report scanner status, native watch count, scanner queue sizes, and last full coverage time

Environment Variables

The repository does not have a checked-in .env.example, so the source is the authority. The table below reflects variables verified in src/core/embeddings.ts, src/index.ts, and the generated config helpers.

Provider selection and model configuration

Indexing, chunking, and refresh behavior

Advanced Ollama runtime options

Available Scripts

Root package scripts

Landing app scripts

Run these from landing/:

scplus-mcp local command surface

When you run scplus-mcp as a shell command after ./install-scplus.sh, it supports both CLI-style local commands and the MCP stdio server mode.

The shell-entry aliases currently implemented in src/cli/commands.ts are:

• validate-index and validate_index

• repair-index and repair_index

• restore-points and restore_points

• hubs and find-hub

MCP Resource And Tool Catalog

Public MCP resource

The MCP server exposes one resource:

Full public MCP tool list

Current public MCP tools registered in src/index.ts:

Index and navigation tools

Exact-query tools

Search and research tools

Analysis, write, and recovery tools

Bridge And Automation Surface

The repository has two non-MCP local automation surfaces:

• bridge <subcommand> for one-shot JSON output

• bridge-serve for a persistent JSON-line session used by scplus-cli and local tooling

bridge subcommands

The one-shot bridge wrapper exposes these subcommands:

Persistent bridge-serve protocol

bridge-serve runs a long-lived JSON-line session with these frame shapes:

{"type":"request","id":1,"command":"doctor","args":{"root":"."}}
{"type":"response","id":1,"ok":true,"result":{...}}
{"type":"event","kind":"log","message":"..."}

The persistent shared command executor supports everything listed above plus these backend-control commands:

Alias notes for the bridge layer:

• find-hub and hubs normalize onto the same implementation

• underscore forms are normalized to hyphen forms where applicable

• validate-index and repair-index are the canonical bridge names

Persistent-only command arguments

Human CLI Surface

The Go operator console is exposed as scplus-cli.

Supported direct scplus-cli subcommands

scplus-cli only has the direct shell subcommands listed above. The much larger operator-facing command set lives inside the interactive UI and is routed over the persistent bridge-serve backend session.

Human CLI capabilities

Based on the current UI implementation and the previous README’s still-useful context:

• animated/operator-branded top shell

• typed navigation across overview, tree, hubs, restore points, clusters, dependencies, search, research, lint, blast-radius, checkpoint, status, and changes

• detail views for selected items and export-ready content

• jobs and log panes fed by backend events

• command palette, filtering, history, and export actions

• shared backend session over bridge-serve

• backend-owned watcher/scheduler state surfaced in the operator experience

Interactive operator commands exposed inside scplus-cli

The Bubble Tea UI exposes a broader action catalog than the direct shell subcommands. These commands are available from the command palette and, where applicable, from the sidebar action list.

Human CLI keybindings

The current UI wiring exposes these interaction patterns directly in the Go operator console:

• : or Ctrl+P opens the command palette.

• / starts in-section filtering.

• b and f move backward and forward through navigation history.

• e exports the current pane or detail content into .scplus/exports/.

• ? opens the help overlay.

• Tab and Shift+Tab move focus across panes and overlays.

• Arrow keys plus j / k move through lists and tables.

• Enter opens the selected row or confirms the active prompt action.

• Esc exits overlays, prompts, or focus modes.

• Mouse wheel and pointer focus are supported across sidebar, content, detail, jobs, and logs panes.

Benchmarks

The committed benchmark artifacts are produced by the real evaluation harness under docs/benchmarks/.

• Human-readable summary: latest.md

• Machine-readable report: latest.json

Current committed numbers from the checked-in benchmark summary:

The current committed run also records:

• 22 golden operator questions

• 0/4 stale-after-write failures

• 0/2 restore failures

• 251 Tree-sitter parses

• 247 parser reuses

This matters because the benchmark suite is exercising not just indexing latency, but also validation quality, rename/write freshness, and broken-state behavior.

References

• zilliztech/claude-context: prior art for codebase-context workflows, repository navigation patterns, and agent-facing context tooling that influenced the product direction.

License

This project is licensed under the MIT License. See LICENSE for the full text.