Scplus MCP

scplus mcp

为特工和操作员准备索引代码情报。

scplus-mcp 是的仓库和npm包 scplus，一个本地代码智能引擎，从经过验证的repo本地索引中提供结构化、精确查询、相关搜索和研究工作流。它运送三个相互连接的表面： scplus-mcp 用于编码代理的MCP服务器，用于自动化的持久本地网桥，以及 scplus-cli 人类泡泡茶操作员控制台。

该项目围绕一个操作合同构建：构建一个准备好的本地索引，一次从一个经过验证的活动生成中读取，当新鲜度或验证被破坏时，会大声失败，而不是从陈旧状态悄悄地回答。

scplus operator console

scplus serving contract

目录

• 主要特点
• 命名和产品表面
• 技术栈
• 先决条件
• 入门指南
• MCP客户端设置
• 模型和嵌入提供者
• 建筑
• 环境变量
• 可用脚本
• MCP资源和工具目录
• 桥梁和自动化表面
• 人机界面
• 基准测试
• 参考文献
• 许可证

主要特点

• 为确定性查找准备了精确的查询工具，例如 symbol, word, outline, deps, status，以及 changes
• 对持久文件、块、标识符、结构、集群和中心工件进行排名相关搜索和广泛研究
• MCP和人类CLI共享一个后端核心，CLI通过持久化连接 bridge-serve JSON线路传输
• Repo本地SQLite机器状态根于 .scplus/，具有主动/待定代推广和明确 fresh, dirty，以及 blocked 新鲜状态
• 无效准备状态的大声失败语义，而不是无声的回退行为
• 根据准备好的完整索引生成的建议中心和语义集群
• 阴影恢复点，用于可逆的人工智能编辑，而不会改变git历史记录
• 下一个单独的Next.js着陆/docs应用程序 landing/，在开发过程中连接到本地包
• 承诺的真实基准工件 docs/benchmarks/

命名和产品表面

此存储库使用了几个在不同上下文中很重要的名称：

重要背景：

• 这 当前源代码 用途 .scplus/ 作为repo本地状态根 src/core/project-layout.ts.
• 当前代码使用的运行时环境前缀为 SCPLUS_.

如果代码和文档不一致，则将代码视为权威代码。

技术栈

• 主要语言：TypeScript（ESM）
• MCP传输: @modelcontextprotocol/sdk 超过stdio
• 准备状态存储：SQLite位于 .scplus/state/index.sqlite
• 解析: web-tree-sitter 和 tree-sitter-wasms
• 检索：词法加嵌入支持的检索持久化到SQLite向量集合中
• 嵌入后端：默认情况下为Ollama，可选择与OpenAI兼容的嵌入
• 人工CLI：Go+奶茶
• Go工具链管理：Pixi(go = 1.24.*)
• 登陆/docs应用程序：Next.js 16、React 19、顺风CSS 4、OpenNext/CCloudflare工具
• 主包管理器：npm

先决条件

在操作存储库之前安装这些：

• Node.js
• npm
• 小精灵
• Git

语义索引通常也需要：

• 奥拉玛，除非您明确选择与OpenAI兼容的嵌入后端

可选：

• 包子，如果你愿意的话 bunx 生成MCP配置时，而不是 npx

笔记：

• 存储库当前未发送已签入的邮件 .env.example.
• 核心包的规范入职路径是安装脚本，而不是从内存中键入的手动npm和pixi命令。

入门指南

规范安装路径

对于主要的开发人员/操作员工作流程，请从安装程序开始：

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

对待 ./install-scplus.sh 作为包和CLI的主要本地设置路径。下面记录了手动构建步骤，以便您了解安装程序正在做什么，但预期的引导流程是通过脚本进行的。

什么 ./install-scplus.sh 做

安装程序：

1. 验证 node
2. 验证 npm
3. 验证 pixi
4. 跑 npm install
5. 跑 npm run build
6. 跑 npm run build:cli
7. 跑 npm link
8. 验证 scplus-mcp 指向 build/index.js
9. 验证 scplus-cli 指向 build/cli-launcher.js
10. 运行轻量级 scplus-mcp tree "$ROOT_DIR" 检查
11. 运行轻量级 scplus-cli doctor --root "$ROOT_DIR" 检查

如果缺少任何先决条件，脚本将致命退出，而不是猜测。

安装后您应该拥有什么

成功运行后：

• scplus-mcp 应该在你的 PATH
• scplus-cli 应该在你的 PATH
• TypeScript构建输出应该存在于 build/
• 泡泡茶发射器应该存在于 build/scplus-cli

快速验证：

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

编辑后重建

编辑TypeScript或Go源代码后，用以下代码重建两个已发布的入口点：

npm run build:all

这将更新已链接的 scplus-mcp 和 scplus-cli 命令到位是因为 npm link 将它们指向此签出的构建输出。

存储库的启动准备状态

安装命令后，创建准备好的仓库本地状态：

scplus-mcp index .

然后验证它：

scplus-mcp validate-index .

最强的成功信号是一个有效的准备好的索引，其中：

• 一个活跃的一代
• 除非正在进行重建，否则没有待定的生成
• 食用新鲜度报告为 fresh

验证面向用户的曲面

从存储库根目录运行这些命令：

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

这些证实了什么：

• MCP入口点可运行
• 可以访问精确的查询/git感知曲面
• 共享后端可以为Go操作员控制台提供服务
• 链接的人工CLI针对相同的后端状态工作

正在开发登陆应用程序

着陆/文档应用程序 landing/ 是一个独立的应用程序，有自己的依赖关系。仅当您正在编辑网站本身时才执行此操作：

cd landing
npm install
npm run dev

着陆应用程序在 http://localhost:6767.

MCP客户端设置

支持的客户端目标

这 init 命令可以为以下对象生成MCP配置：

• claude
• cursor
• vscode
• windsurf
• opencode
• codex

生成的配置路径：

自动生成配置文件

示例：

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

跑步者选择：

• 默认情况下，该命令更喜欢 bunx 当它检测到Bun并回落到 npx
• 你可以强迫跑步者 --runner=npx 或 --runner=bunx

示例：

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

手动Codex TOML配置

如果您想在使用本地安装脚本后手动配置Codex，请将其添加到 ~/.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"

如果你喜欢跑步 npx 或 bunx 生成的Codex配置遵循相同的结构，但设置如下，而不是本地链接命令：

• command = "npx" 和 args = ["-y", "scplus-mcp"]，或
• command = "bunx" 和 args = ["scplus-mcp"]

JSON样式MCP配置示例

对于使用JSON配置文件的客户端，生成的配置遵循以下一般形状：

{
  "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"
      }
    }
  }
}

确切的顶级密钥因客户端而异：

• mcpServers 克劳德/光标/风帆风格配置
• servers 对于VS代码 .vscode/mcp.json
• mcp 为了 opencode.json
• 食品法典委员会的TOML表格

模型和嵌入提供者

关于此仓库中Ollama型号名称的重要说明

此存储库中显示的模型标签，特别是：

• qwen3-embedding:0.6b-32k
• nemotron-3-nano:4b-128k

应被解读为 在维护环境中使用的本地Olama变体，而不是声称这些是该项目发明的完全定制的模型系列。

根据当前维护人员的工作流程：

• 基本模型是从Ollama官方来源下载的
• 然后，本地设置修改了上下文窗口配置

因此，在实践中，README示例记录了项目当前的本地运行时标签和期望，而不是断言存储库本身分发新的模型架构。

提供商概述

该代码支持两种嵌入提供程序模式：

奥拉玛之路

默认代码路径为Ollama。典型的本地设置如下：

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

然后，如果您的本地环境使用扩展上下文变量或自定义本地标记，请配置以下env值 scplus-mcp 实际上应该使用：

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

OpenAI兼容路径

对于API支持的嵌入：

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

可选自定义基URL：

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

建筑

目录结构

.
├── 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

运行时曲面

存储库公开了三个不同但相互连接的运行时表面：

重要约束：

• Go CLI是 不 第二索引引擎
• 它是MCP服务器使用的相同后端核心的客户端

请求的生命周期

对于代理/MCP请求：

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

对于人工操作员请求：

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

服务和发电合同

由当前代码和架构文档记录的准备好的州合同是：

• 一个活跃的一代是真理的源泉
• 重建和维修可以先写入待定的一代
• 只有在验证成功后，才会提升待定代
• 服务新鲜度是明确的，可以 fresh, dirty，或 blocked
• 无效或阻塞的准备状态应该大声失败，而不是默默降级

简短的权威架构概述 architecture.md.

查询模型

代码库实现了一个双通道查询模型：

• 精确车道: symbol, word, outline, deps, status, changes
• 分级车道: search 和 intent="related"
• 宽阔的报告通道: research

产品契约是，精确查找仍然是最便宜的确定性路径，更广泛的检索只有在精确查找不足时才会运行。

项目状态布局

当前代码使用此仓库本地状态根：

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

在索引后的当前结账中观察到：

• .scplus/state/index.sqlite
• .scplus/hubs/suggested/
• .scplus/locks/

当前源代码使用 .scplus/.

核心组件图

src/core/

• project-layout.ts 定义 .scplus/ 布局
• embeddings.ts 管理提供程序支持的嵌入、SQLite向量命名空间、运行时选项和生成感知缓存无效
• tree-sitter.ts 和 parser.ts 提供结构解析
• runtime-locks.ts 协调跨流程所有权
• process-lifecycle.ts 管理空闲关机、父级监控和清理

src/tools/

• index-codebase.ts, index-stages.ts，以及 index-reliability.ts 驱动器索引、验证和修复
• exact-query.ts 实现快速精确查询底层
• query-intent.ts, unified-ranking.ts, semantic-search.ts，以及 semantic-identifiers.ts 实施排名搜索
• research.ts 构建更大的有界子系统报告
• feature-hub.ts, hub-suggestions.ts，以及 cluster-artifacts.ts 实现中心和集群视图
• static-analysis.ts 和 blast-radius.ts 提供诊断和使用情况跟踪
• propose-commit.ts 和 write-freshness.ts 实现保护写入和同步新鲜度修复

cli/

• cli/cmd/scplus-cli/main.go 是Go入口点吗
• cli/internal/backend/ 是网桥客户端层
• cli/internal/ui/ 呈现操作员控制台
• cli/internal/hubs/ 支持手动创建中心

操作员控制台行为

附带的人工CLI不仅仅是一个薄薄的包装。之前的README的高价值描述仍然足够准确，可以保持较高的水平：

• 它有一个导航窗格、概述/内容窗格、详细信息窗格和作业/日志区域
• 它公开了操作员健康状况、服务状态、队列状态、历史记录和可观察性
• 它支持命令面板、过滤、导出和导航历史记录
• 它通过持久化流式传输后端事件 bridge-serve 运输

提交的普通快照位于 cli-snapshot.txt.

监视器和调度器语义

后端，而不是Go前端，拥有观察者行为：

• 默认情况下不使用本机递归文件系统监视器
• 有界后端扫描程序覆盖预算目录和文件标记中的存储库
• 对突发路径更改进行重复数据消除
• 调度程序可以排队或取代过时的待处理工作
• 普通编辑可以变成刷新作业
• 依赖关系/配置更改可能升级为完整索引作业
• 作业、监视和日志事件被流式传输 bridge-serve
• 诊断报告扫描程序状态、本机监视计数、扫描程序队列大小和上次完全覆盖时间

环境变量

存储库没有签入 .env.example，所以来源就是权威。下表反映了在 src/core/embeddings.ts, src/index.ts，以及生成的配置助手。

供应商选择和型号配置

索引、分块和刷新行为

高级Ollama运行时选项

可用脚本

根包脚本

登陆应用程序脚本

运行这些从 landing/:

scplus-mcp 本地命令界面

当你奔跑时 scplus-mcp 作为shell命令 ./install-scplus.sh，它支持CLI风格的本地命令和MCP stdio服务器模式。

当前在中实现的shell条目别名 src/cli/commands.ts 是：

• validate-index 和 validate_index
• repair-index 和 repair_index
• restore-points 和 restore_points
• hubs 和 find-hub

MCP资源和工具目录

公共MCP资源

MCP服务器公开了一个资源：

完整的公共MCP工具列表

当前注册的公共MCP工具 src/index.ts:

索引和导航工具

精确查询工具

搜索和研究工具

分析、写入和恢复工具

桥梁和自动化表面

存储库有两个非MCP本地自动化界面：

• bridge 一次性JSON输出
• bridge-serve 用于持久JSON行会话 scplus-cli 以及本地工具

bridge 子指令

一枪 bridge wrapper公开了这些子命令：

持久 bridge-serve 协议

bridge-serve 使用以下框架形状运行一个长期JSON行会话：

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

持久共享命令执行器支持上面列出的所有内容以及这些后端控制命令：

桥接层的别名注释：

• find-hub 和 hubs 标准化到相同的实现上
• 下划线形式在适用的情况下被标准化为连字符形式
• validate-index 和 repair-index 是规范的网桥名称

仅持久化命令参数

人机界面

Go操作员控制台显示为 scplus-cli.

支持直接 scplus-cli 子指令

scplus-cli 只有上面列出的直接shell子命令。更大的面向操作员的命令集位于交互式UI内，并通过持久化路由 bridge-serve 后端会话。

人工CLI功能

基于当前的UI实现和之前的README仍然有用的上下文：

• 动画/运营商品牌的顶部外壳
• 在概述、树、中心、还原点、集群、依赖关系、搜索、研究、lint、爆炸半径、检查点、状态和更改之间键入导航
• 所选项目和导出就绪内容的详细视图
• 由后端事件提供的作业和日志窗格
• 命令面板、筛选、历史记录和导出操作
• 共享后端会话结束 bridge-serve
• 后端拥有的观察者/调度器状态在操作员体验中浮出水面

内部暴露的交互式操作员命令 scplus-cli

Bubble Tea UI公开了比直接shell子命令更广泛的动作目录。这些命令可以从命令面板和侧边栏操作列表（如适用）中获得。

人类CLI键绑定

当前的UI连接直接在Go操作员控制台中公开了这些交互模式：

• : 或 Ctrl+P 打开命令面板。
• / 从部分过滤开始。
• b 和 f 在导航历史中前后移动。
• e 将当前窗格或详细信息内容导出到 .scplus/exports/.
• ? 打开帮助覆盖。
• Tab 和 Shift+Tab 在窗格和覆盖层之间移动焦点。
• 箭头键+ j / k 浏览列表和表格。
• Enter 打开所选行或确认活动提示操作。
• Esc 退出覆盖、提示或聚焦模式。
• 在侧边栏、内容、详细信息、作业和日志窗格中支持鼠标滚轮和指针焦点。

基准测试

已提交的基准工件是由以下实际评估工具生成的 docs/benchmarks/.

• 人类可读摘要： 最新.md
• 机器可读报告： latest.json

scplus benchmark overview

已检入基准汇总中的当前承诺数字：

当前提交的运行还记录了：

• 22 黄金操作员问题
• 0/4 写入失败后过时
• 0/2 恢复失败
• 251 树保姆解析
• 247 解析器重用

这很重要，因为基准测试套件不仅在执行索引延迟，还在执行验证质量、重命名/写入新鲜度和断开状态行为。

参考文献

• zilliztech/claude上下文：影响产品方向的代码库上下文工作流、存储库导航模式和面向代理的上下文工具的现有技术。

许可证

该项目根据MIT许可证获得许可。看 许可证 全文。