Smart-AI-Bridge
Smart AI Bridge is an enterprise-grade MCP server that provides multi-AI backend orchestration with intelligent routing across 4 specialized backends (coding, analysis, local unlimited tokens, general purpose), featuring automatic failover and health monitoring. It offers enhanced file operations including atomic multi-file writing, intelligent chunking for large files, and advanced batch editing with rollback capabilities. The server includes smart edit prevention through fuzzy matching using Levenshtein distance to reduce "text not found" errors by 80%, supporting strict/lenient/dry_run validation modes. Additional capabilities include direct AI querying to specific models (local, Gemini, DeepSeek, Qwen), comprehensive code review with security and performance analysis, pre-flight validation for changes, system diagnostics with differentiated health checks, backup/restore management, rate limit monitoring, and cross-platform support with automatic service detection for local AI providers.
Enables AI-powered development operations through Google Gemini models as a configurable general-purpose cloud backend with multi-modal capabilities
Integrates with NVIDIA's cloud API platform to access specialized AI models like Qwen for coding tasks and DeepSeek for analysis through intelligent backend routing
Connects to local Ollama model servers for unlimited token processing and private AI operations without API rate limits or usage restrictions
Provides access to OpenAI's GPT models through configurable cloud backends with specialized routing for coding, analysis, and general-purpose AI tasks
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Smart-AI-Bridge review this Python function for security vulnerabilities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Smart AI Bridge v2.15.0
Config-driven multi-AI orchestration for Claude Code. Add any OpenAI-compatible provider, route intelligently, and let multiple AIs collaborate through the council system.
What It Does
Smart AI Bridge is an MCP server that sits between Claude Code and your AI backends. It provides 17 tools for token-saving file operations, multi-AI workflows, code quality checks, and intelligent routing -- all configured through a single JSON file.
Any OpenAI-compatible provider works. Local models (vLLM, LM Studio, Ollama), cloud APIs, or a mix of both. The included presets cover common providers, but adding your own is just a config entry.
Smart routing selects the best backend per task using a 4-tier system: forced selection, learned preferences, rule-based heuristics, and health-based fallback.
Council system queries multiple backends on the same prompt and returns all responses for Claude to synthesize. Configurable strategies (parallel, sequential, debate, fallback) per topic.
Web dashboard for managing backends and council configuration without editing JSON files.
Related MCP server: MCP Enterprise Architecture Practice 01
How It Works
The core idea: Claude never reads the file
Most of Claude's context on a coding task is spent on file contents. Smart AI Bridge hands that work to another model and returns only the conclusions, so the expensive context stays free for reasoning.
sequenceDiagram
accTitle: How Smart AI Bridge saves tokens
accDescr: Claude Code calls analyze_file. Smart AI Bridge reads the file and sends its contents to a backend model. The backend returns a structured analysis, and only that analysis is returned to Claude. The file contents never enter Claude's context.
participant C as Claude Code
participant S as Smart AI Bridge
participant F as Your files
participant B as Backend<br/>(local or cloud)
C->>S: analyze_file({ filePath, question })
S->>F: read the file
S->>B: file contents + question
B-->>S: structured analysis
S-->>C: { summary, findings[], confidence, tokens_saved }
Note over C,S: The file contents never enter Claude's context.<br/>tokens_saved is measured from the real bytes,<br/>not estimated.modify_file works the same way but returns a diff; explore returns matching file:line
evidence; batch_analyze does it across a glob. Every one of these reports a tokens_saved
figure computed from the actual characters read versus the actual response returned.
Choosing a backend: the 4-tier router
Every call that doesn't name a backend goes through the same decision, in order. The first tier that produces a healthy backend wins.
flowchart TD
accTitle: The four-tier backend routing decision
accDescr: A tool call is routed in four ordered tiers. Tier 1 uses an explicitly named backend. Otherwise Tier 2 uses a learned preference above 0.7 confidence if that backend is healthy. Otherwise Tier 3 applies complexity and task-type rules. Otherwise Tier 4 takes the first healthy backend in the fallback chain.
A[Tool call] --> B{"backend named<br/>and not 'auto'?"}
B -- yes --> T1["<b>Tier 1 · Forced</b><br/>use it as given"]
B -- no --> C{"learned preference<br/>above 0.7 confidence<br/><i>and</i> that backend healthy?"}
C -- yes --> T2["<b>Tier 2 · Learned</b><br/>from past outcomes"]
C -- no --> D{"a rule matches on<br/>complexity / task type?"}
D -- yes --> T3["<b>Tier 3 · Rules</b><br/>heuristic match"]
D -- no --> T4["<b>Tier 4 · Fallback</b><br/>first healthy backend<br/>in the chain"]A learned preference that is confident but points at an unhealthy backend falls through to Tier 3 rather than being used. Health failures open a circuit breaker, so a provider that is down is skipped rather than retried into a timeout.
Asking several models at once: the council
council sends one prompt to multiple backends and returns every response for Claude to
synthesize. It does not vote or pick a winner — disagreement between models is the signal,
so it is preserved rather than averaged away.
flowchart LR
accTitle: Council strategies
accDescr: One prompt is dispatched by a configurable strategy. Parallel queries all backends at once. Sequential runs them in order, each seeing the previous answer. Debate has models respond to each other. Fallback tries the next backend only if the previous failed. Every response is returned to Claude to synthesize.
Q[One prompt] --> R{strategy}
R -->|parallel| P[All backends at once]
R -->|sequential| S[One after another,<br/>each sees the last]
R -->|debate| D[Models respond<br/>to each other]
R -->|fallback| F[Next only if<br/>the previous failed]
P & S & D & F --> A[All responses returned<br/>to Claude to synthesize]Strategy is configurable per topic. See docs/COUNCIL.md.
Quick Start
There is no npm package -- install by cloning. Requires Node.js >= 18.
1. Clone and install
git clone https://github.com/Platano78/smart-ai-bridge.git
cd smart-ai-bridge
npm installConfirm the install is sound before wiring it into anything:
npm test # expect: all tests pass, 0 failures2. Configure at least one backend
The server starts and lists all 17 tools with no API keys at all -- you only need a backend when you actually call one. You need one of:
a local OpenAI-compatible server (llama.cpp, vLLM, LM Studio, Ollama) -- auto-discovered on common ports, no key required; or
one cloud API key from any supported provider.
# Set whichever apply -- one is enough
export NVIDIA_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"Backend definitions live in src/config/backends.json; see CONFIGURATION.md
for the full reference. A missing key is never an error -- the startup readiness audit reports
such backends as cannot verify, not as broken.
3. Register with your MCP client
Use an absolute path to src/server.js. Relative paths depend on the client honoring cwd,
which not every client does.
Claude Code -- copy .mcp.json.example to .mcp.json in your project,
or add to your MCP settings:
{
"mcpServers": {
"smart-ai-bridge": {
"command": "node",
"args": ["/absolute/path/to/smart-ai-bridge/src/server.js"],
"env": {
"NVIDIA_API_KEY": "your-key"
}
}
}
}Claude Desktop -- same block, merged into claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Any other MCP client -- it speaks MCP over stdio. Run node /absolute/path/src/server.js and
talk JSON-RPC to it. Diagnostics go to stderr; stdout carries protocol traffic only.
4. Restart the client and verify
All 17 tools appear after a restart. Verify with a call that needs no backend:
@get_analytics({})To check a backend you have actually configured, name it explicitly -- check_backend_health
reports local as critical when no local model is running, which is expected on a cloud-only
setup and does not mean the install failed:
@check_backend_health({ "backend": "auto" })Updating an existing install
cd /path/to/smart-ai-bridge
git pull origin main
npm install # only needed when dependencies changedThen restart your MCP client (in Claude Code, /mcp reconnects without a full restart).
Tools (17)
Token-Saving File Operations
Tool | Description |
| Backend reads and analyzes files, returns structured findings |
| Backend applies natural-language edits, returns diff |
| Analyze multiple files via glob patterns; |
| Apply same instructions across multiple files |
| Generate code from a natural-language spec |
| Answer codebase questions using intelligent search |
All but generate_file return a tokens_saved field measured for that specific call: the
characters of file content the backend read on your behalf, minus the characters of the
response handed back. Both sides are measured from the real data rather than assumed, so
the figure reflects what actually happened on that call -- though the character-to-token
conversion (~4 characters per token) is itself approximate, so treat the result as a good
indicator rather than an exact token count. It varies enormously with file size and
response length: a small file can save nothing at all. We publish no headline percentage
because we have not benchmarked one we could defend.
Multi-AI Workflows
Tool | Description |
| Smart routing with auto or forced backend selection |
| Multi-AI consensus across configurable backends |
| Generate, review, fix loop between two backends |
| TDD workflow with decomposition and quality gates |
| Specialized AI agents (10 roles including TDD) |
Code Quality
Tool | Description |
| Security, performance, and quality review |
| Cross-file refactoring with reference updates |
Infrastructure
Tool | Description |
| Health diagnostics for specific backends |
| Timestamped backup management |
| Atomic multi-file writes with backup |
| Usage analytics and optimization recommendations |
Smart Routing
The router selects backends using a 4-tier priority system:
Forced -- explicit backend selection (
model="my_backend")Learning -- learned preferences from past outcomes (>0.7 confidence)
Rules -- complexity and task-type heuristics
Fallback -- health-based fallback through the priority chain
When a resolved backend fails -- one the router picked, because you passed backend: "auto" or let a routing rule choose -- the request automatically falls to the next healthy backend in the chain.
A backend you named explicitly does not cascade. It gets one attempt, and if that fails you get an error saying so, distinguishing "your lane was tried and failed" from "your lane could not be attempted at all". This is deliberate: the API keys are yours, and silently rerouting a request you pinned to one lane can spend your credit on lanes you never asked for. Pass backend: "auto" when you want the chain.
Circuit breakers protect each backend (5 consecutive failures trigger a 30-second cooldown).
Backend Names
There are two layers of backend naming, and both are intentional:
Friendly names are what you pass to tools (e.g.
backend: "glm"ormodel="groq"). They are stable, provider-neutral aliases.Internal names are the registry/config identifiers used in
src/config/backends.jsonand analytics.
The presets map as follows:
Friendly name | Internal name | Adapter type |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Removed: nvidia_qwen / qwen3. The NVIDIA code-specialist lane once served a Qwen
model. NVIDIA has since retired it, and its catalog now lists no Qwen model of any
kind — so the names were removed outright rather than kept as aliases pointing at a
differently-named lane. nvidia_qwen and qwen3 no longer resolve to anything.
Use nvidia_glm (friendly alias: glm). If you have a saved force_backend: "nvidia_qwen" or a config carrying "type": "nvidia_qwen", change it to nvidia_glm.
This does not affect Qwen models you run locally. The bridge still detects them on your own router and applies Qwen-specific handling (capability inference, FIM tokens, reasoning-suppression) — that has nothing to do with the retired NVIDIA lane.
The OpenAI-compatible backend ships under the internal name openai_chatgpt (adapter
type openai) and is reached through smart routing rather than a friendly alias. For the
ask tool, openai is accepted as a compatibility alias for the configured
OpenAI-compatible backend. Custom backends you add via config use their name field
directly as the internal name.
Backend Drift and Model Retirement
Providers retire models without notice, and the failure is otherwise silent until a request fails. Two things catch that:
A readiness audit at startup. It checks each configured backend's model against the
provider's catalog and prints findings to stderr. It runs only after the MCP handshake
completes and is never awaited, so it cannot delay or abort startup. Disable it with
SAB_DISABLE_READINESS_AUDIT=true.
An on-demand probe that sends every configured backend a real completion:
npm run audit:backends # human-readable table
npm run audit:backends -- --json # machine-readableA real completion is the only trustworthy check — model ids appear in a provider's
/v1/models listing that still return 404 for a given account. Backends are classified
OK, RETIRED, TRANSIENT, ERROR, NO_MODEL, or NO_KEY. It exits non-zero only on
RETIRED, ERROR, or NO_MODEL, so it can gate CI.
A backend with no API key is never reported as broken. You supply your own keys and
most setups configure a single provider, so an unset key reports as
cannot verify — <VAR> not set and does not fail the run. The local backend is
reachability-checked only, never catalog-checked: its configured "model": "dynamic" is
a handle, not a catalog id.
When a model has been retired, the resulting error says so explicitly — naming the backend, the model, the provider's end-of-life text, and live replacement candidates — rather than surfacing as a generic HTTP failure. Retirement is a configuration error, so it opens the circuit breaker immediately instead of being retried; saturation (429/5xx) and auth failures (401) are deliberately not treated as retirement.
Response Reliability (v2.4.0)
All handlers use a unified response pipeline (extractResponseText) that correctly handles every known LLM response shape -- raw strings, OpenAI chat/completion formats, thinking model reasoning_content, array content parts, and Gemini candidates. Repetitive output from local models is automatically collapsed, and analysis findings are deduplicated and capped.
Write Integrity
fs.writeFile resolving does not guarantee the bytes on disk match what was requested -- short or partial writes, ENOSPC, encoding mangling, or a concurrent writer clobbering the file between write and return all leave disk content that diverges from the intended content while the write call itself resolves cleanly.
Every path that writes content you care about reads it back and compares before reporting success:
Path | What is verified |
| modified file, plus the backup it takes first |
| generated file and its generated tests file |
| each written file, plus each backup |
| file grew by exactly the appended length and ends with exactly those bytes |
| each restored file (the backup is only unlinked once the restore is confirmed) |
| modifications (via |
| each generated code file |
| the backup, the pre-restore snapshot, and the restore itself |
A mismatch raises WRITE_VERIFY_MISMATCH -- naming the file, the expected vs actual length, and the first divergent line -- instead of reporting success: true over a corrupted file.
Recovery paths get the same treatment deliberately: a backup that silently failed to land is worse than no backup, because a later rollback would restore corrupt bytes over the original.
Not verified, by design: internal run artifacts and state files that are records rather than deliverables -- parallel_agents' decomposed.json/results.json/quality-*.json/synthesis.json, backup_restore's .meta.json sidecar, the pattern store, and conversation threads.
Council System
The council queries multiple backends on the same prompt and returns all responses for Claude to synthesize. Topics like coding, architecture, and security each map to a set of backends and a strategy (parallel, sequential, debate, or fallback).
See docs/COUNCIL.md for full documentation.
Dashboard
An optional web dashboard provides UI for backend management (enable/disable, priorities, health checks) and council configuration (strategies, topic mapping).
See docs/DASHBOARD.md for setup and API reference.
SmartCrusher (Tool-Result Compression)
Large tool results — long file analyses, council responses, batch outputs — can fill Claude's context window quickly. SmartCrusher trims oversized arrays before serialization using a salience-weighted keep/drop strategy, inserting a sentinel row so Claude knows data was offloaded.
Disabled by default. Enable only after running the fidelity eval against your own local model.
Enable
# One-time env override (no config edit needed)
SAB_COMPRESSION_ENABLED=true node src/server.js
# Or permanently in src/config/backends.json:
# "compression": { "enabled": true }Fidelity Eval (run before enabling)
The eval probes whether crushed responses preserve factual accuracy compared to originals. It requires an OpenAI-compatible local API — use whatever model you normally run:
RUN_CRUSH_EVAL=1 \
CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
CRUSH_EVAL_MODEL=<your-model-id> \
npx vitest run tests/compression/probeFidelity.test.jsCheck the output for original=N/15 vs crushed=M/15 per dimension. If crushed scores drop more than 2 points on any dimension, leave compression disabled — the model grades differently than the reference setup.
Adding a Backend
Via Dashboard (recommended): Start the server with SAB_DASHBOARD=true, then use the web UI at http://localhost:3456 (override with SAB_DASHBOARD_PORT) to add, remove, enable/disable, and re-prioritize backends without editing JSON. The dashboard also lets you set/clear an API key per backend (stored in the gitignored data/backends-secrets.json, mode 0600 — never written to the tracked src/config/backends.json); a stored key takes effect immediately, no restart required, and beats the backend's process.env fallback.
The dashboard binds to 127.0.0.1 only by default — it has no authentication, so it must not be reachable off-box. Override with SAB_DASHBOARD_HOST if you need it reachable elsewhere; a non-loopback host prints a warning on startup naming the risk.
Via Config File: Any OpenAI-compatible provider can be added as a config entry in src/config/backends.json:
{
"name": "my_provider",
"type": "openai",
"endpoint": "https://api.my-provider.com/v1",
"model": "my-model",
"apiKeyEnvVar": "MY_PROVIDER_API_KEY",
"maxTokens": 8192,
"priority": 7,
"enabled": true
}See EXTENDING.md for details on adding custom adapter types.
Documentation
Document | Description |
Install/run contract for AI agents and agentic harnesses, plus repo rules | |
Version history | |
Full configuration reference | |
Adding backends, handlers, and tools | |
Usage examples | |
Dashboard setup and API | |
Council system details |
Requirements
Node.js >= 18.0.0
At least one backend configured (local model or cloud API key)
Claude Code or Claude Desktop for MCP integration
Testing
npm test # Run the unit + integration suite (Vitest)
npm run test:watch # Watch mode
npm run test:bench # Performance benchmarks (25 benchmarks, 6 categories)
npm run audit:backends # Probe every configured backend with a real completion
# SmartCrusher fidelity eval (opt-in, requires a running local model):
RUN_CRUSH_EVAL=1 \
CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
CRUSH_EVAL_MODEL=<your-model-id> \
npx vitest run tests/compression/probeFidelity.test.jsSecurity Notes
Never commit API keys to version control. Use environment variables exclusively.
The Claude Code config examples above use placeholder values -- replace them with your actual keys or reference a
.envfile.Rotate any accidentally leaked keys immediately.
Threat Model
Smart AI Bridge is a trusted-local MCP server. It is designed to run as a stdio subprocess of a single client you control (Claude Code or Claude Desktop) on your own machine, and it assumes that client is trusted.
Within that boundary:
The file tools have full filesystem access by design.
write_files_atomic,modify_file,backup_restore, and the read/analyze tools operate on whatever paths the calling client supplies. They are not sandboxed to a project root.safeReadFileresolves paths and rejects null bytes (defense against path-injection tricks), but it does not confine access to a workspace.Argument validation happens at the tool boundary. Tool calls are validated against each tool's JSON Schema (via Ajv) before dispatch; malformed calls are rejected with a structured error. This protects against malformed input, not against a hostile client.
Tool calls run with the privileges of the server process. Run it as your normal user, not as root.
This posture is appropriate for the intended single-user, local-agent use case. It is not suitable for exposing the server to untrusted or multi-tenant callers over a network. If you need that, put an authenticating proxy in front of it and add workspace-root confinement to the file handlers first -- neither is provided here.
License
Apache-2.0
Available Tools
17 toolsanalyze_fileA
Read ONE file and answer a question about it using a local or cloud LLM — Claude never sees the file contents, only the structured findings the LLM returns, plus a measured tokens_saved figure for that call. Use when you have one specific file and a specific question (security check, bug hunt, architectural concern). For the same question across many files (glob patterns), use batch_analyze. For a natural-language search across the codebase with no specific file in mind, use explore. Pure line-range questions like 'show me lines 437–490' short-circuit the LLM entirely and return the requested lines verbatim at zero token cost. Read-only: reads filePath, optionally reads includeContext files, makes one LLM call. Returns: {success, filePath, fileSize, lineCount, language, analysisType, question, summary, findings:[strings], confidence (0-1), suggestedActions:[strings], backend_used, processing_time, tokens_saved}. Verbatim short-circuit returns the same shape with analysisType:'verbatim', backend_used:'direct_extraction', and the requested lines in summary.
Inputs: filePath (required), question (required), options.
askA
Send one prompt to one AI backend and return the response. model:'auto' lets SAB's router pick the best backend by task complexity + current health; passing a specific model name forces that provider. Use this for direct LLM queries that don't fit a more specialized tool. For multi-backend consensus on the same prompt, use council. For agentic multi-step work with a defined role, use spawn_subagent. For LLM-driven file generation or editing, use generate_file / modify_file so the file content stays out of Claude's context window. Read-only: makes one HTTP call to the chosen backend. Returns: {success, model, requested_backend, actual_backend, prompt (truncated preview), response (the LLM output), backend_used, fallback_chain, response_time, cache_status, thinking_enabled, max_tokens, was_truncated, smart_routing_applied, routing, processing_time}.
Inputs: model (required), prompt (required), thinking, max_tokens, +3 more.
backup_restoreA
Manage the timestamped backup files produced by modify_file and write_files_atomic. Four actions: create (manually snapshot a file before a risky native edit), list (enumerate known backups, optionally filtered to one file), restore (overwrite a file with a specific backup_id), cleanup (delete old backups per the policy in cleanup_options). The cleanup policy applies BOTH thresholds — a backup is deleted only when it exceeds max_age_days OR when its file already has more than max_count_per_file newer backups. Use dry_run to preview before applying. ⚠️ DESTRUCTIVE: restore overwrites the current file (the prior state is auto-snapshotted to <path>.pre_restore_<timestamp>, so the restore itself is reversible); cleanup permanently deletes backup files from disk. create and list are read-only. Returns: { success, action, ...action-specific fields }. create→{backup_id, backup_path, original_path, size}. restore→{backup_id, restored_to, pre_restore_backup}. list→{file_path, backups:[{path, backup_id, size, created, metadata}]}. cleanup→{dry_run, backups_deleted, deleted:[{path, reason:'age'|'count'}]}.
Inputs: action (required), metadata, backup_id, file_path, +1 more.
batch_analyzeA
Run the SAME question against a glob of files, then aggregate the findings into one cross-file summary. Use for codebase-wide audits ('any SQL injection under src/**/handlers/*.js?'), per-feature reviews, or pre-merge sweeps. For ONE file, use analyze_file (cheaper). For NL search without a known file set, use explore. Set aggregateResults:false to get raw per-file results instead of the aggregated summary. Read-only: by default reads every matched file (capped by maxFiles) and makes one LLM call per file (parallel by default). options.grepFilter (string or string[], plain substrings — never regex, case-insensitive) narrows the file set to files whose content contains ANY term; it widens the scan before applying maxFiles, so filtering never just re-filters an already-truncated glob. options.singlePass (default false) makes exactly ONE LLM call across all matched files instead of one call per file — much cheaper, but perFileResults only reports which files contributed evidence, not a real per-file summary/confidence; evidence per file is grep-matched lines (with context) when grepFilter is set, otherwise the file's head, capped to fit the model's context window (reported via evidence_truncated). Returns: shape depends on aggregateResults/singlePass. aggregateResults:true, singlePass:false (default): {success, status:'completed', filesAnalyzed, patterns, question, aggregatedSummary, aggregatedFindings:[strings], aggregatedActions:[strings], overallConfidence, perFileResults:[{filePath, summary, findingCount, confidence}], processing_time, tokens_saved}. singlePass:true: same shape but perFileResults:[{filePath, contributedEvidence}], plus singlePass:true, evidence_truncated (input side — evidence was trimmed before the call, with evidence_dropped_files/evidence_truncation_hint when true), and was_truncated (output side — the aggregated answer itself hit the token limit, with truncation_hint when true). aggregateResults:false: {success, status:'completed', filesAnalyzed, patterns, question, results:[full per-file analysis objects], processing_time}. When grepFilter is set, responses also include grepFilter:{terms, filesScanned, filesMatched}. Empty pattern match: {success, status:'no_files', message, patterns}.
Inputs: question (required), filePatterns (required), options.
batch_modifyA
Apply the SAME natural-language instruction independently to each file in files. Use for sweeping consistent edits — 'add JSDoc to every exported function in lib/', 'replace console.log with logger.info'. transactionMode:'all_or_nothing' (default) rolls every file back if any one fails; 'best_effort' keeps the successful edits and reports failures. This tool does NOT find cross-file references — each file is edited in isolation. For symbol renames that must update callers, use refactor. For one file with custom instructions, use modify_file. ⚠️ DESTRUCTIVE when review:false: writes to every file in the batch (per-file backups at <path>.backup.<timestamp>). The default review:true returns the proposed diffs without writing. Returns: shape depends on review. review:true (default): {success, status:'pending_review', filesProcessed, patterns, instructions, modifications:[{filePath, status:'pending_review'|'error', summary, diff, stats, error?}], successCount, failureCount, approval_instructions, tokens_saved}. review:false (auto-write): {success, status:'completed'|'partial', filesProcessed, modifications:[{filePath, status:'written'|'error', summary, stats, error?}], successCount, failureCount}.
Inputs: files (required), instructions (required), options.
check_backend_healthA
On-demand ping of one specific backend's API endpoint to verify reachability and capture latency. Hits only the named backend, not the whole fleet. Read-only: makes one HTTP request to the backend's health endpoint. Returns: {success, status:'online'|'offline', backend, latency_ms, last_check_iso, error?, total_check_time}.
Inputs: backend (required), force.
councilA
Pose one prompt to several AI backends in parallel and return all of their responses for Claude to synthesize. Backend selection is driven by topic, which maps to a declared capability rather than to any lane name: the usable lanes declaring that capability are preferred, and the remaining usable lanes fill the rest of the seats. An operator-configured roster for a topic overrides that entirely. confidence_needed controls how many backends are queried — high (4), medium (3), low (2). Use for architectural trade-offs, controversial calls, or anywhere dissent surfaced cheaply (~1-2s for 2-3 backends) is more useful than a single answer. For a single backend query, use ask. Read-only: makes N parallel HTTP calls; never writes to disk. Returns: {success, topic, strategy, confidence_needed, backends_queried:[names], backends_responded:[names of those that succeeded], responses:[{backend, success, content, response_time, error?}], processing_time_ms, metrics, synthesis_hint (suggestion to Claude on how to synthesize)}.
Inputs: topic (required), prompt (required), max_tokens, num_backends, +1 more.
dual_iterateA
Code generation with an internal review loop: a generator backend writes code, a reviewer backend scores it against quality_threshold, the generator fixes flagged issues, and the cycle repeats until the threshold is met or max_iterations runs out. The whole loop runs inside SAB; Claude sees only the final accepted code (~1 turn of output instead of 3-5). Use for complex single-file generation where you would otherwise pay the token cost of reviewing iterations in-chat. For multi-agent TDD with parallelism + tests, use parallel_agents. For one-shot generation without iteration, use generate_file. Read-only: returns the generated code to the caller; does NOT write to disk (pass the result to write_files_atomic to persist). Returns: {success, code (final accepted code as a string), mode (the iteration mode used), iterations (number actually run), execution_time_ms, metadata:{task_preview, code_length, timestamp}, history (full per-iteration log, only when include_history:true), final_review:{status, notes}, self_review_applied}.
Inputs: task (required), max_iterations, include_history, quality_threshold.
exploreA
Natural-language search across the codebase: combines grep-style matching with optional LLM summarization to answer 'where is X handled?' or 'what files implement Y?' Returns a summary + the matching file:line list, not raw file contents. Use when you DON'T already know which file to look at. For a deep analysis of ONE known file, use analyze_file. For a structured question across a known set of files (glob patterns), use batch_analyze. depth:'shallow' is fast grep; depth:'deep' adds LLM-generated context per match. Read-only: walks the filesystem and reads matched files but never writes. Returns: {success, summary (LLM- or template-generated answer), files_found:[paths], search_patterns:[strings actually grepped], evidence:[...] (capped at 15), tokens_saved, processing_time_ms, depth, backend_used}. The evidence entry shape depends on depth: shallow returns {file, line, snippet} per matching line; deep returns {file, matches:[{line, context}]}, grouping each file's matches with surrounding context.
Inputs: question (required), options.
generate_fileA
Generate a new file from a natural-language spec. The local LLM writes the code; Claude either reviews the proposed content (review:true, default) or it gets written directly to outputPath (review:false). Use for fresh files you can describe by goal — boilerplate, scaffolding, test fixtures, single-file utilities. For editing an EXISTING file, use modify_file. For writing a known content string to disk with no LLM involved, use write_files_atomic. Optionally pass contextFiles to anchor the generated style on existing code. ⚠️ DESTRUCTIVE when review:false: writes (and creates parent directories of) outputPath. If includeTests:true, also writes a sibling test file. The default (review:true) is non-destructive — returns the generated content for Claude to inspect first. Returns: {success, status:'written'|'written_truncated'|'pending_review', outputPath, summary, linesOfCode, language, testPath (when includeTests), backend_used, processing_time, retry_attempts, was_truncated}. In review mode the response also carries the generated content for Claude to apply via write_files_atomic.
Inputs: spec (required), outputPath (required), options.
get_analyticsA
Inspect SAB's internal telemetry: backend invocation counts, success/failure rates, latency distributions, estimated token spend per provider, and recent routing decisions. Read-only — never calls an LLM, never writes to disk. Use to diagnose 'why did SAB pick backend X', tune routing rules, or understand cost trade-offs across providers. Report types are cumulative: full_report includes everything from the other types. Returns: {success, report_type, data} where data depends on report_type — current: {backends:{[name]:{invocations, success_rate, p50_ms, p95_ms}}, session_uptime, timestamp}. historical: {time_range, series:[{timestamp, backend, calls, errors, latency}]}. cost: {by_backend:{[name]:{tokens_in, tokens_out, estimated_usd}}, total_estimated_usd}. recommendations: {recommendations:[{type, suggestion, confidence}]}. full_report: a merged object with all sections. If analytics hasn't initialized, returns {message, basic_stats:{uptime, memory, timestamp}}.
Inputs: format, time_range, report_type.
modify_fileA
Edit an existing file by describing the change in natural language. The local LLM reads the file, applies the edit using SEARCH/REPLACE blocks (with a size-ratio safety net that refuses writes <50% of the original), and returns a unified diff for Claude to approve (review:true, default) or writes directly (review:false). Use for non-trivial edits where the AI does the work. For a known string→string replacement Claude can do itself, use native Edit. For writing a fully-specified content string to a file, use write_files_atomic. For the same instruction across MANY files, use batch_modify. For symbol renames + cross-file reference updates, use refactor. ⚠️ DESTRUCTIVE when review:false: writes directly to filePath. A backup at <path>.backup.<timestamp> is created unless backup:false is also passed (a warning is logged in that case). dryRun:true produces the diff without writing. Returns: shape depends on mode. review (default): {success, status:'pending_review'|'pending_review_truncated', filePath, diff, modifiedContent, summary, stats, warnings, was_truncated, approval_options, retry_attempts}. dryRun: {success, status:'dry_run', filePath, diff, summary, stats, warnings, backend_used, processing_time}. auto-write: {success, status:'written', filePath, diff, summary, stats, backupCreated, backend_used, processing_time, tokens_saved}.
Inputs: filePath (required), instructions (required), options.
parallel_agentsA
Run a test-first development workflow as a graph of parallel agents: a decomposer splits the task into atomic subtasks, RED-phase agents write failing tests, GREEN-phase agents implement to pass them, then a quality reviewer iterates the cycle until a threshold is met or max_iterations runs out. Use for self-contained features that benefit from test-first discipline and can be parallelized. For a single agent on a single task, use spawn_subagent. For a generate→review→fix loop on one code blob (no test infrastructure), use dual_iterate. ⚠️ DESTRUCTIVE when write_files:true (default): generated tests, implementation, and refactor outputs are written under work_directory in red/, green/, refactor/ subdirectories (defaults to /tmp/parallel-agents-<timestamp>). Returns: {success, task, decomposition (decomposer's plan), execution:{groups_executed, tasks_completed, tasks_failed, max_parallel_used, files_written, write_files_enabled}, router_info:{slots, model, status}, quality:{verdict, score, iterations}, synthesis (combined output), files:[absolute paths written], work_directory, processing_time_ms, metrics}.
Inputs: task (required), write_files, max_parallel, max_iterations, +2 more.
refactorA
Cross-file refactoring with automatic reference tracking. Locates where target is defined and where it's used, then applies the instruction consistently across the matched scope. Use for renames, signature changes, API migrations — any edit where consistency between definition and callers matters. scope bounds how wide the search goes: 'function' / 'class' / 'module' / 'project'. For the same blind edit across files without reference-awareness (cheaper), use batch_modify. For a single-file change, use modify_file. ⚠️ DESTRUCTIVE when review:false: writes to every file touched by the refactor. dryRun:true produces the plan without writing. Returns: shape depends on mode. review:true (default) or dryRun:true: {success, status:'pending_review'|'dry_run', scope, target, instructions, plan:{description, steps:[strings], filesAffected, estimatedChanges}, modifications:[{filePath, status:'pending_review'|'dry_run'|'error', summary, diff, stats, error?}], analysis:{occurrences, references, impact}, backend_used, processing_time, tokens_saved}. Auto-apply (review:false): {success, status:'completed'|'partial', scope, target, instructions, filesModified, filesTotal, modifications:[{filePath, status:'written'|'error', summary, error?}], backend_used, processing_time}.
Inputs: scope (required), target (required), instructions (required), options.
reviewA
Review a code blob you already have in context and return structured findings + a quality score + improvement suggestions. Pass the code itself in content; this tool does not read any file from disk. Use when Claude already has the code in hand. For a review of a file Claude has NOT seen (so the file content stays out of context and a real tokens_saved figure is returned), use analyze_file with analysisType:'security' instead. For multiple AI perspectives on the same code, use council. Read-only: never writes to disk. Returns: {success, file_path, language, review_type, review (full review text from the LLM, includes findings + severity + suggestions), endpoint_used}.
Inputs: content (required), language, file_path, review_type.
spawn_subagentA
Spawn one AI agent with a predefined role + system prompt and run it to completion on a single task. The agent runs once and returns its verdict; there is no memory between calls. Use when the work fits a clear role (security audit on one module, generate tests for one function, write docs for one API). For multi-agent TDD parallelism with quality gates, use parallel_agents. For multi-backend consensus on a question, use council. Pass file paths and acceptance criteria in task — the agent has no other context. ⚠️ DESTRUCTIVE when write_files:true: code blocks the agent emits are saved into work_directory (auto-created if missing, defaults to /tmp/subagent-<role>-<timestamp>). The default write_files:false is non-destructive — code is returned inline in the response. Returns: {success, role, task, backend_used, response (agent's full output), verdict (structured findings, depth controlled by verdict_mode), files_analyzed (paths the agent read), files_written:[paths] (only when write_files), work_directory, suggested_tools:[follow-up tool names], processing_time_ms, metrics}.
Inputs: role (required), task (required), context, write_files, +3 more.
write_files_atomicA
Write a batch of files in a single atomic operation with automatic backup. All files succeed or all roll back on any failure. Use this when several file writes must land together (config changes across modules, multi-file generation output). For natural-language edits to a single file, use modify_file instead. For appending to a log or accumulator file, use the append operation here. Each overwrite produces a <path>.backup.<timestamp> file when create_backup is true (default). ⚠️ DESTRUCTIVE: every operation writes (or appends to) a real file on disk. The rollback path runs only when a LATER operation in the same batch fails — earlier successful writes are reverted from their backups, but if every operation succeeds, the new files stand and the backups remain on disk. Returns: {success, files_written, results:[{path, operation, success, size}], backups_created, backups:[{original, backup}]}. On a mid-batch failure the call throws after restoring earlier files (rollback is not reflected in a success response).
Inputs: file_operations (required), create_backup.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have clearly separated purposes, and the descriptions explicitly cross-reference alternatives to reduce confusion (e.g., analyze_file vs batch_analyze vs explore; generate_file vs dual_iterate). Minor residual ambiguity exists among ask/council/spawn_subagent and review/analyze_file, but the in-description disambiguation is strong.
The file-focused tools follow a recognizable verb_file pattern (analyze_file, generate_file, modify_file) and batch_* is a useful prefix, but the set mixes bare verbs (ask, review, explore, refactor), noun-style names (council, parallel_agents), and compound names (dual_iterate, check_backend_health). No single naming convention is sustained across the full toolset.
At 17 tools, the server is slightly past the typical 3-15 well-scoped range, but it spans codebase analysis, file mutation, backup management, AI orchestration, and backend operations, so most tools earn their place. It is a bit heavy for an agent to choose among, but not bloated.
The surface covers file generation, single and batch editing, refactoring, backup/restore, code analysis/search, and multiple multi-agent orchestration modes, leaving few dead ends. The main gaps are the lack of a delete/remove file operation and any high-level management of backend/routing configuration beyond health checks and analytics.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Related MCP Servers
- AlicenseCqualityDmaintenanceA production-grade MCP server providing an autonomous AI agent swarm, persistent semantic memory, browser automation, multi-model reasoning, and 78+ tools for AI-first testing and development.63MIT
- FlicenseNot gradedqualityDmaintenanceEnterprise MCP server providing a suite of tools including file, database, GitHub, Slack, calendar, email, vector search, and Python execution, with safe defaults and OpenAI integration for automatic tool selection.-
- AlicenseNot gradedqualityCmaintenanceAn enterprise-grade MCP server that enables AI coding assistants to securely connect with external tools, APIs, databases, and cloud services through a unified interface, offering structured engineering workflows and multi-client support.MIT
- AlicenseCqualityCmaintenanceMCP server that provides 160 specialist AI agents as parallel sub-agents and MCP tools for tasks like security auditing, API design, DB schema design, and more. It is local-first with BYOK support and integrates with 12+ IDEs.1611MIT