Skip to main content
New aislop v0.8.3: MCP server, TypeScript typecheck engine, hallucinated-import detector + 8 new multi-language patterns. Read more →
MCP server

MCP server.

aislop ships as an MCP server. Add one block to your agent's config and the model can call aislop_scan / aislop_fix / aislop_why / aislop_baseline directly — every project, every session, no per-repo install.

Current in 0.8.3

The aislop-mcp binary ships in the same npm package as the CLI. Wire it into your agent's MCP config once and the agent can self-check on every turn — no terminal command, no per-repo install. Stays local: stdio transport, your code never leaves the machine.

MCP vs hooks vs handoff

Three integration shapes. They stack — pick the ones that match how your team works.

MCP
Tool palette
Agent decides when to call aislop. One install, every project. What this page covers.
Hook
Per-edit (forced)
aislop runs after every Edit/Write the agent makes. Findings come back as additionalContext. Hook docs.
Handoff
Manual
aislop fix --<agent> opens the agent with all remaining diagnostics as a prompt. Handoff docs.

MCP is pull (agent-initiated); hooks are push (always-on). Use both — MCP gives the agent agency to scan when it suspects a regression; hooks guarantee a scan even when the agent doesn't think to ask.

Install

Add the aislop entry to your agent's MCP config and restart the agent. First call downloads the package via npx (~3s cold, instant after).

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aislop": {
      "command": "npx",
      "args": ["-y", "aislop-mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json (or per-project .cursor/mcp.json)

{
  "mcpServers": {
    "aislop": {
      "command": "npx",
      "args": ["-y", "aislop-mcp"]
    }
  }
}

Claude Code

~/.claude/mcp.json for global, .mcp.json in repo root for project-scoped.

{
  "mcpServers": {
    "aislop": {
      "command": "npx",
      "args": ["-y", "aislop-mcp"]
    }
  }
}

Codex CLI (TOML)

~/.codex/config.toml

[mcp_servers.aislop]
command = "npx"
args = ["-y", "aislop-mcp"]

Pinned version: replace aislop-mcp with aislop-mcp@0.8.3. Pre-installed locally: pnpm add -D aislop, then point command at ./node_modules/.bin/aislop-mcp.

Tools

Four tools the agent can call. All run locally; the server reads your project files via the same engines as the CLI.

aislop_scan read-only

Run the engines on the project, return score + counts + top findings. Use before claiming work is done.

Args: { path?: string }
Returns: { score, counts, findings[≤25], languages, frameworks, fileCount }
aislop_fix writes files

Apply mechanical fixes (formatting, unused imports, narrative comments, duplicate imports). Runs a fresh scan before and after, so the response carries the score delta.

Args: { path?: string, force?: boolean }
Returns: { ok, fixed, scoreBefore, scoreAfter, delta, remaining, counts, findings, elided }

force: true runs aislop fix --force: writes package.json overrides and may delete unused files. Off by default.

aislop_why read-only

Look up an aislop rule. Returns the engine + a deep-link into the /patterns reference for full bad/good examples.

Args: { rule_id: string }
Returns: { id, engine, docs, hint }
aislop_baseline read-only

Read the project's baseline (the score the per-edit hook compares against). Useful when deciding whether to set up regression tracking.

Args: { path?: string }
Returns: { exists, score?, lastScanAt?, fileCount?, hint? }

How it works

  1. The agent host (Claude Desktop, Cursor, Codex) reads your mcp.json on startup.
  2. It spawns npx -y aislop-mcp as a child process, piped over stdin/stdout.
  3. The agent sends JSON-RPC messages: initialize, tools/list, tools/call.
  4. aislop-mcp answers from the same engines as the CLI: aislop_scan runs in-process; aislop_fix spawns aislop fix for the actual mutations.
  5. When the agent process exits, aislop-mcp exits too. Nothing persists outside .aislop/.

Transport is stdio only — there is no network listener, no auth, no remote endpoint. Your code never leaves the machine. (A hosted variant is on the roadmap as a separate transport for the scanaislop.com hosted product; not in this release.)

Verifying the install

After restarting your agent, ask it:

# paste into Claude / Cursor / etc.
$ Useaislop_scantoscorethisproject,thenexplainthetop3findings.

The agent should respond with a score (0–100), counts of errors / warnings / fixable, and a summary of the top findings. If it doesn't see aislop_scan as a tool, the most common cause is the agent host wasn't restarted after editing the MCP config.

Recommended workflow

MCP plus the per-edit hook is the strongest combination. Each plays a distinct role:

During the agent's turn

Hook fires after every Edit/Write. The agent sees regressions in aislop.hook.v2 envelope and self-corrects.

When the agent suspects something

The model calls aislop_scan via MCP to get the full project picture, not just the touched file.

Before declaring done

Agent calls aislop_fix to clear what's mechanically fixable. Saves tokens — no need to ask the model to format imports or remove dead comments.

Troubleshooting

  • Tool not visible after install: restart the agent host. Most agents only read mcp.json at startup.
  • npx hangs on first call: first run downloads the package (~3s). If your network is slow, pre-install with pnpm add -D aislop and point the config at ./node_modules/.bin/aislop-mcp.
  • Tool returns an error: the response includes isError: true and a JSON body with the message. The most common cause is calling aislop_baseline on a project that hasn't run aislop hook baseline yet — the response then says { exists: false, hint }.
  • Want stdout/stderr from the spawned aislop fix: not exposed yet. Call aislop fix in your terminal directly when you need the raw output.

Related