abcop MCP server
Commit Nov 5, 2026Gates AI-written code by inspecting function and module ABC complexity to ensure maintainability and context window compatibility.
Also known as adrianov/abcop
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.23.0
- Last commit
- Nov 5, 2026
- License
- GPL-3.0
What is abcop MCP?
abcop gates AI-written code by inspecting function and module ABC complexity to ensure maintainability and context window compatibility.
Summary generated from the project's README
About abcop MCP server
abcop serves as a quality gate for code generated by AI agents, ensuring that new functions and modules remain maintainable. It uses the ABC metric, which calculates complexity based on assignments, branches, and conditions, rather than simple line counts. This approach ensures that every code unit fits within a human's cognitive capacity and an LLM's context window. The tool is a single, high-speed Rust binary that works across a wide range of languages including Ruby, Python, Rust, Go, Java, C#, TypeScript, and more without requiring language-specific runtimes or plugins.
Developers can run it locally via CLI or connect it to AI clients using the MCP server mode with the abcop_inspection tool. When used as an MCP server, an agent receives immediate feedback on complexity offenses or dead locals during the editing process. This allows the model to perform automated refactoring, such as extracting methods or splitting modules, in the same turn it writes the code. The server provides structured JSON or JSONL diagnostics to facilitate these automated fixes.
What you can do with it
- 1Prevent AI complexity growthAn AI agent can use the tool to ensure new code does not exceed the default function ABC ceiling of 17.
- 2Automated code refactoringDevelopers can feed JSON diagnostics into scripts to automatically split oversized modules or extract methods.
- 3Real-time agent feedbackConnect the server to an LLM via MCP so the model can fix complexity issues immediately after writing code.
- 4Identify dead codeUse the tool to find local variables that are written once and never read within a function.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableadrianov/abcop is public and reachablegithub.com/adrianov/abcop ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-05github.com/adrianov/abcop ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubabcop
A must-have gate for AI-written code. Agents ship faster than humans can re-read; abcop keeps that code understandable by gating function and module ABC complexity so every unit fits a human head and an LLM context window. Diagnostics are also a hook for automated refactoring — extract a method, split a module — so CI rejects bad growth and points agents at concrete maintainability fixes.
One self-contained binary across Ruby, Rust, Python, Go, PHP, Java, C#, Dart, JavaScript, TypeScript, C, C++, Objective-C, Swift, Solidity, Zig and Haskell — no runtimes, no plugins, no per-language installs. Written in Rust for speed: one parse per file, one walk per metric, grammars compiled in; whole trees in milliseconds.
Install
brew install adrianov/abcop/abcop
cargo install abcop
macOS (.tar.gz from GitHub Releases; binary + man):
# Apple Silicon — use the *-x86_64-apple-darwin.tar.gz asset on Intel Macs
curl -LO https://github.com/adrianov/abcop/releases/download/v0.23.0/abcop-0.23.0-aarch64-apple-darwin.tar.gz
tar -xzf abcop-0.23.0-aarch64-apple-darwin.tar.gz
sudo cp abcop-0.23.0-aarch64-apple-darwin/abcop /usr/local/bin/
sudo mkdir -p /usr/local/share/man/man1
sudo cp abcop-0.23.0-aarch64-apple-darwin/abcop.1 /usr/local/share/man/man1/
Ubuntu / Debian (.deb from GitHub Releases; amd64, Ubuntu 22.04+ / Debian bookworm+):
# example for v0.23.0 — use the asset name from the release page
curl -LO https://github.com/adrianov/abcop/releases/download/v0.23.0/abcop_0.23.0-1_amd64.deb
sudo dpkg -i abcop_0.23.0-1_amd64.deb
man abcop
Example run
lib/sinatra/base.rb:1254:0: C: Metrics/AbcSize: Assignment Branch Condition size for `error_block!` is too high. [<7, 14, 9> 18.06/17]
src/main.rs: W: Metrics/ModuleAbcSize: Assignment Branch Condition size for module is too high. [<80, 200, 60> 228.04/120] -- extract a coherent subunit
132 files analysed in 0.09s, 7 abc offenses, 0 used-once offenses, 0 never-used warnings, 14 module-abc warnings
Why ABC, not line counts
Line counts lie. The ABC metric
(Jerry Fitzpatrick, C++ Report, June 1997) counts what does work —
assignments (A), branches (B), conditions (C) — as sqrt(A² + B² + C²).
Fitzpatrick defined both method and module scope; abcop gates both:
| Rule | Severity | Meaning |
|---|---|---|
Metrics/AbcSize |
C | function ABC above --max-abc (default 17). A normal scan reports a rise vs HEAD; --full and --everything report every function over the ceiling |
Metrics/ModuleAbcSize |
W | module ABC above --max-module-abc (default 120). A normal scan reports a rise vs HEAD; --full and --everything report every production module over the ceiling |
UsedOnce |
W | local written once and read once, inside a function the edit changed. --full and --everything report every such local |
NeverUsed |
W | local written and never read, inside a function the edit changed. Same whole-tree switch as UsedOnce |
A sparse wrapper and a dense god-object can share a line count; ABC separates them. Complexity is the gate — never a line budget. UsedOnce / NeverUsed are secondary.
Built for AI workflows
- Understandable by construction. AbcSize 17 and ModuleAbcSize 120 keep every new unit inside a human head and an LLM context window. An existing unit may stay over that ceiling when the edit does not raise its score. Models edit small units reliably; when something breaks, the blast radius is tiny.
- Refactoring hook. Exit code
1plus stable JSON/JSONL diagnostics (rule,score,vector,message) feed agents and scripts: split oversized modules, extract hot methods. Each finding is an actionable maintainability step, not a style nit. - Fast enough for every push. Sub-second whole-tree scans — including code an agent will never re-read tomorrow.
- Signal only. No formatting or style cops. Vendored, generated and
test trees are skipped by default. Knobs:
--max-abcand--max-module-abc.--fulland--everythingreport every hit, not only the current edit. - Prefer MCP with LLMs.
abcop --mcpis the best way to use abcop from an agent: the model gets offenses as soon as it writes, so it can fix complexity and dead locals in the same turn and ship effective code right away — not after a later CLI/CI pass. Official RustrmcpSDK; toolabcop_inspection. Listed on the MCP Registry asio.github.adrianov/abcop(crates.io package + each GitHubv*tag).
Inspired by RuboCop (Ruby AbcSize
parity and # rubocop:disable directives) and
lizard (one tool, many languages).
Ruby method counting matches RuboCop 1.89 byte-for-byte
(scripts/compare_parity.py). A block outside a method (match do,
before do, a class-level each) is its own unit; each / map /
select still roll into the block that contains them.
Advantages
- ~850k–940k LOC/s per core (Apple M1 Pro). RuboCop's lib tree
(943 files, 110k LOC): 0.13 s — ~39× faster than
rubocop --only Metrics/AbcSize(cache off), ~140× a full rubocop run. - One binary, zero deps — grammars and an embedded result cache
(
cache.redb) compiled in; works on clean CI images with no language toolchains. - Deterministic — same findings every run; text / JSON / JSONL stream
as files finish;
--sort-by-scorebuffers for worst-first emit.
Usage
abcop [OPTIONS] PATH...
| Option | Default | Meaning |
|---|---|---|
[PATH]... |
auto | targets; omitted → scope selection |
--max-abc N |
17 |
function ABC ceiling |
--max-module-abc N |
120 |
module ABC ceiling |
--only abc|used-once|never-used |
all | single check |
--full |
off | whole production tree, and every function over the ceiling plus every local (default skips stay on) |
--everything |
off | no gitignore / hidden / vendored pruning (ignore in the user config still applies); same full report as --full |
--format text|json|jsonl |
text |
CI-friendly output |
--sort-by-score |
off | highest ABC first |
--mr |
off | MR scope (uncommitted + branch vs base) |
--uncommitted |
off | working-tree + index + untracked vs HEAD only |
--no-cache |
off | skip on-disk cache |
--mcp |
off | MCP server on stdio (for AI clients) |
--dump-tree FILE |
— | debug syntax tree |
Exit codes: 0 clean, 1 findings, 2 usage error.
abcop app lib # two trees; rises and edited functions only
abcop --format jsonl lib > abcop.jsonl # streaming CI / agent input
abcop --only used-once src # inline candidates in edited functions
abcop --max-abc 12 --only abc lib # stricter function budget
abcop --full lib # every function over the ceiling, every local
abcop --everything lib # same report, with no default pruning
abcop --max-module-abc 80 lib # stricter module budget
abcop --sort-by-score --only abc lib # worst first
abcop --uncommitted # pre-commit; rises and edited functions only
abcop --mr --only abc # branch files; still only ABC rises vs HEAD
abcop --mcp # MCP server on stdio (for AI clients)
JSON diagnostics include file, line, column, severity, rule,
message, plus score / vector for ABC rules:
{"rule":"Metrics/AbcSize","score":10.0,"vector":"<6, 8, 0>"}
{"rule":"Metrics/ModuleAbcSize","score":120.5,"vector":"<40, 100, 40>"}
Scope selection
Named paths — those targets only. Findings still follow the edit filter below.
Omitted — narrowest useful scope, announced on stderr:
- uncommitted work vs
HEADif the tree is dirty - else current MR (
--mrforces this) - else the tree (outside a repo)
Default walks prune test/fixture trees, vendored/build output
(vendor/, node_modules/, target/, …), db/migrate/, route tables
(config/routes.rb, config/routes/*.rb), and generated names
(*.min.js, *_pb.go, …). Name a path explicitly to scan it anyway.
Rails schema dumps (db/schema.rb, db/*_schema.rb, db/schema_*.rb)
are never scanned, even when named.
Third-party, route-table, and fixture paths are never scoped review
surface — a diff through vendor/ or tests/fixtures/ does not make
that material owned code.
On a dirty tree the bare default is uncommitted-only; --mr takes the
full branch union. Commits straight to main use a 36-hour window when no
branch base applies. --uncommitted fails outside a repository instead
of silently widening.
What a normal scan reports
Every scan except --full and --everything compares the working tree
to HEAD:
- AbcSize reports a method over
--max-abconly when its score is strictly higher than the same method inHEAD(same name, source order). A score that stayed the same or fell stays quiet, including a legacy method that was already over the ceiling. A method that exists only in the working tree counts as an increase. The message asks to return to the previous score when that score was already over the ceiling (rose from 20 to 21 -- back to 20 or below). WhenHEADwas under the ceiling, the target is the ceiling (rose from 16.28 to 21.28 -- back to 17 or below). - UsedOnce / NeverUsed report only inside a function whose text
changed against
HEAD. A local in a function the edit did not touch stays quiet. Locals outside any function still report. - ModuleAbcSize reports a module over
--max-module-abconly when its whole-file score is strictly higher than that file inHEAD. A score that stayed the same or fell stays quiet, including a legacy module already over the ceiling. A file that does not exist inHEADis held to the ceiling. The message asks to return to the previous score when that score was already over the ceiling (rose from 200 to 210 -- back to 200 or below). WhenHEADwas under the ceiling, the target is the ceiling. - No
HEADblob (not a git checkout, or an untracked file) reports every method over the ceiling, every local, and every module over the ceiling.
--uncommitted and --mr also drop function and local findings on lines
the diff did not touch.
Whole-tree report
--full and --everything report every method over --max-abc, every
local, and every production module over --max-module-abc. ModuleAbcSize
still exempts test trees on those runs. --full keeps the default skips.
--everything lifts gitignore, hidden directories, and vendored/generated/test
pruning. ignore in the user config still applies to both.
User config
One file holds user options. It is $XDG_CONFIG_HOME/abcop when that
variable is set, otherwise ~/.config/abcop. $ABCOP_CONFIG replaces
the path. Nothing is written into the project.
ignore is a gitignore pattern, one option per line, applied in every
project relative to that project's root. A directory pattern covers
everything inside it. Naming the path, --full, and --everything do
not bring a match back. An MCP inspection of a matched path is empty.
ignore = app/services/legacy/
ignore = lib/old.rb
Directives
Everywhere except Rust, RuboCop-style # / // suppressions work
(trailing and block; bare Metrics allowed). rubocop:disable-next is
ignored, matching rubocop.
def legacy_path # rubocop:disable Metrics/AbcSize
...
end
MCP (Model Context Protocol)
Preferred for LLM / agent workflows. Wire abcop as an MCP server so the
model can call abcop_inspection while it edits: feedback arrives in the
same turn, the agent corrects soon, and it writes maintainable code on the
first pass instead of discovering ABC / UsedOnce / NeverUsed only in CI.
abcop --mcp runs a long-lived MCP server on stdio — same idea as
RuboCop’s MCP
and rrubocop, with no Ruby mcp
gem. Tool:
| Tool | Purpose |
|---|---|
abcop_inspection |
Analyse via path / paths (string or array) and/or inline source_code; returns compact offense JSON (code, line, column, message; score / vector for ABC rules). Same edit filter as a normal scan: AbcSize and ModuleAbcSize only when the score rose against HEAD, UsedOnce and NeverUsed only inside functions the edit changed. A new module is held to the module ceiling. Always pass an explicit project path — omitting targets errors out (avoids scanning $HOME when MCP cwd is mis-set). |
- MCP Registry name:
mcp-name: io.github.adrianov/abcop
Metadata lives in server.json, which is part of the
Cargo package on crates.io. Each GitHub
v* release tag publishes that listing to the
MCP Registry (after the
crates.io upload).
Example client config (Cursor / VS Code / Windsurf):
{
"mcpServers": {
"abcop": {
"type": "stdio",
"command": "abcop",
"args": ["--mcp"],
"cwd": "/path/to/your/project"
}
}
}
Claude Code:
claude mcp add abcop -- abcop --mcp
Intended for MCP clients, not interactive use.
Caching
Content-addressed cache under $XDG_CACHE_HOME/abcop (or ~/.cache/abcop;
override with ABCOP_CACHE_DIR). Warm reruns ~5× faster. Keys cover
contents, version, rule revision, threshold, checks and path — no
cross-project collisions. Auto-pruned to 20 000 entries; --no-cache
disables. Nothing is written inside the project.
Supported languages
Seventeen languages plus embedded JS in HTML/templates, four rules each, one CI gate.
| Language | Files | Notes |
|---|---|---|
| Ruby | .rb .rake .ru .gemspec, Gemfile, Rakefile, … |
RuboCop-parity method AbcSize; blocks outside methods are units |
| Rust | .rs |
|
| Python | .py .pyi .pyw |
|
| Go | .go |
|
| PHP | .php |
|
| Java | .java |
|
| C# | .cs |
|
| Solidity | .sol |
|
| Dart | .dart |
|
| Zig | .zig |
|
| Haskell | .hs .lhs |
|
| JavaScript | .js .mjs .cjs .jsx |
also <script> in HTML/templates |
| TypeScript | .ts .tsx .mts .cts |
lang="ts" / typescript script types |
| Embedded JS | .html .htm .xhtml .erb .slim .haml .pug .vue .svelte .ejs .njk .jinja .j2 .twig .liquid .hbs …, *.js.erb |
extract scripts; blank <% %>, {{ }}, {% %} holes |
| C / C++ | .c .h .cc .cpp .cxx .hpp .hxx .hh |
.h via C++ grammar |
| Objective-C | .m .mm |
|
| Swift | .swift |
Named declarations are measured units; anonymous function-likes roll into
the enclosing unit; nested units never double-count. C-family: file-scope
globals are out of single-file reach; loop-head locals are protocol;
field writes also read the object; export-macro class forms
(class UTIL_EXPORT Foo) are skipped for variable rules.
Benchmarks
Apple M1 Pro, warm cache:
| Corpus | Size | abcop | rubocop --only AbcSize¹ |
Full rubocop |
|---|---|---|---|---|
| rubocop/lib | 943 files, 110k LOC | 0.13 s | 5.1 s (~39×) | 18.3 s |
| cargo registry sample | 6,603 files, 2.6M LOC | ~2.8 s | — | — |
¹ --cache false — rubocop's own cache otherwise makes repeats look free.
Development
cargo test
cargo build --all-targets # zero warnings
abcop src # dogfood
Shared engine: src/scope_model/ (backend, walk, eval); language
collectors sit beside each backend (clike/, sollang/, …). Probe
grammar nodes with abcop --dump-tree FILE. Parity:
scripts/compare_parity.py.
License
GNU GPL v3 or later (SPDX: GPL-3.0-or-later). See LICENSE.
Copyright © 2026 Peter Adrianov. All rights reserved.
abcop MCP questions
How can I use abcop with an AI agent?
You can use the --mcp flag to run abcop as an MCP server on stdio, allowing models to receive complexity offenses immediately during the editing process.
Which programming languages does abcop support?
It is a self-contained binary that supports Ruby, Rust, Python, Go, PHP, Java, C#, Dart, JavaScript, TypeScript, C, C++, Objective-C, Swift, Solidity, Zig, and Haskell.