imperal-mcp — The ICNLI-Powered SuperSuite for LLMs & AI Agents 🐝

Python 3.7 – 3.14 · pip install "imperal-mcp[code]" works out of the box on every one of them.

Stop running your LLM blind. imperal-mcp is the all-in-one SuperSuite & Exoskeleton for LLMs — upgrading Claude Code, Claude Desktop, Cursor, OpenAI Codex, Windsurf, Gemini CLI, Cline, and Goose with a live Tree-sitter AST call graph, surgical symbol reading, invisible ShadowGit checkpoints, cross-platform cloud memory, and a full-stack cloud app builder powered by ICNLI and Imperal Cloud.

With a single install, your coding agent stops dumping whole files into context, maps and navigates unfamiliar repositories in one call, checks blast radius and syntax automatically on every edit, remembers your architecture across every IDE, terminal, and chat surface, and builds, deploys, and monetizes full-stack cloud apps on the Imperal Marketplace.

Why Developers Switch to imperal-mcp Immediately

Watch what happens to a typical LLM coding session the moment you attach imperal-mcp:

WITHOUT imperal-mcp (Standard Agent Workflow)
  1. cat / Read 1,800-line service.py         -> 72,000 chars dumped into context
  2. grep -rn "process_Order" across repo     -> 140 noisy text matches
  3. Read 3 more full files to trace callers  -> +95,000 chars burned
  4. Edit shared function blind               -> breaks 2 callers & leaves syntax error
  5. Switch from Cursor to Claude Code        -> total amnesia; re-explain architecture from scratch

WITH imperal-mcp (The SuperSuite Exoskeleton)
  1. orient("process_order")                  -> repo profile + top ranked AST symbols in 1 call
  2. outline("service.py")                    -> compact structural map with exact line ranges
  3. read_symbol("service.py", "Order.run")   -> reads ONLY the 28 lines you need
  4. impact_of_change(["Order.run"])          -> lists every dependent file & caller before you touch a line
  5. PostToolUse hook -> check_syntax         -> catches syntax errors in milliseconds after every Edit/Write
  6. checkpoint("before-refactor")            -> instant ShadowGit snapshot outside .git (rollback in 1 call)
  7. recall_context / save_repo_note          -> every rule & repo note follows you across Claude, Cursor & Telegram

The 5 Structural Bottlenecks imperal-mcp Eliminates

The 5 Core Pillars of the SuperSuite

1. Surgical Context & Honest Token Telemetry (AST Symbol Slicing)

Stuffing an LLM's context window with thousands of lines of unrelated code wastes tokens, slows down time-to-first-token, and degrades reasoning accuracy.

• Map First, Read Only What Matters: Instead of reading an entire 1,500-line module into context, your agent calls outline(path) to view a compact structural map of classes, methods, and functions with exact line ranges, then calls read_symbol(path, "ClassName.method") (or L120-180) to load only the target span.
• Honest, On-Disk Telemetry (token_savings()): Call token_savings() at any point in your session to inspect exact, measured character and line counts (returned_chars vs baseline_chars, returned_lines vs baseline_lines, baseline_files, and per-tool breakdowns). Baselines are measured directly from the real matched files on disk (baseline_basis: "matched_files_on_disk") — never inflated against the whole repository or synthetic multipliers.

2. Live Code Graph, Call Contracts & Blast-Radius Analysis

When installed with imperal-mcp[code], the server maintains an incremental Tree-sitter AST & dependency graph (with a built-in Python ast fallback so Python syntax checks and outlines work even in minimal environments):

• orient(query) — One-call task launchpad combining the repository profile with the top-ranked symbols and code matches for your task.
• repo_profile() & coding_context() — Instant overview of languages, file counts, architectural hubs, test command hints, and git working-tree status.
• search_code(query, kind, path_glob) — Hybrid symbol, semantic, and lexical search across the indexed workspace.
• graph_slice(symbols, depth) — Batch lookup of symbol definitions, signatures, direct callers, and callees.
• contract_slice(symbols) — Inspect exact function signatures, return annotations, raised exceptions, and real call-site argument shapes.
• impact_of_change(symbols) — Compute every downstream file and caller symbol that depends on the code you plan to edit before making changes.
• check_syntax(path) — Instant syntax validation after every edit, plus optional automatic PostToolUse hooks for Claude Code.

3. Persistent Memory & Context Across Every Platform and Surface

Your architectural knowledge should never be locked inside a single IDE tab or model vendor:

• remember_fact(fact, category, tags) — Store standing engineering rules, user preferences, and operational directives in Imperal Cloud Memory.
• save_repo_note(note, repo, citations) — Record durable repository conventions, build commands, and architectural invariants tied to your project.
• recall_context(query) — Retrieve relevant user facts and repository notes from any MCP-compatible client (Claude Code, Cursor, Windsurf, Codex, Gemini CLI), the Imperal Web Panel, or Telegram.

4. Build, Deploy & Monetize Apps on the Imperal Marketplace

Powered by ICNLI (Infrastructure Contextual Natural Language Interface), imperal-mcp is a complete Cloud Application SDK & Execution Engine:

• Author Full-Stack Cloud Apps from Natural Language: Using the built-in MCP resources (imperal://ir-spec, imperal://ui-catalog, imperal://examples) and the build_imperal_app prompt, your LLM compiles your intent into a declarative Imperal Intermediate Representation (app.ir.json) bundle — complete with UI views, state schemas, connectors, and typed tool handlers.
• Validate, Smoke-Test & Deploy in Seconds:
  1. validate_ir(app_ir) — Statically verify the IR envelope and every declarative step locally.
  2. smoke_ir(app_ir, function, args) — Execute a live dry-run inside an isolated sandbox store on Imperal Cloud and inspect {ok, result, trace}.
  3. deploy_ir(app_ir, app_id) — Deploy the verified app directly into your Imperal Cloud account.
• Publish & Monetize on the Imperal Marketplace: Once your app is deployed and tested, you can publish it to the Imperal Marketplace — sharing or selling custom SaaS connectors, DevOps automations, analytics suites, and domain workflows to other developers and businesses.

5. Invisible ShadowGit Safety Net & Capability-Gated Cloud Execution

• ShadowGit Checkpoints (checkpoint, checkpoint_diff, checkpoint_rollback): Snapshot your workspace before risky refactors into an isolated shadow git store without creating noisy WIP commits in your real .git history. Compare diffs at any point or roll back when an experiment fails (checkpoint_rollback is explicitly marked destructive so your MCP client prompts for confirmation before overwriting working files).
• Workspace Boundary Protection: All local code and file tools enforce strict workspace path resolution — requests targeting paths or root directories outside the configured workspace root (such as ~/.zshrc or /etc) are rejected with OutsideWorkspaceError.
• Three-Tier Cloud Safety (read / write / destructive):
  • run_read_tool executes read-only operations and automatically scrubs PII from responses.
  • run_write_tool executes standard write tools directly, requires interactive human consent (MCP elicitation) for destructive tools, and enforces out-of-band panel approval for financial/money operations.

Complete Tool & Resource Catalog (25 Tools + 5 Resources)

Local Code Intelligence & Call Graph (imperal-mcp[code])

Local ShadowGit Checkpoints (imperal-mcp[code])

Cross-Platform Cloud Memory (Imperal Cloud)

Imperal Cloud App Builder, Sandbox & Execution (ICNLI)

Built-In MCP Resources

Installation & Quick Start

1. Install the Package

# Full SuperSuite (Cloud + Local AST Code Graph, Call Graph, Search & ShadowGit)
pip install "imperal-mcp[code]"

# Lightweight Cloud-only install (App Builder, Cloud Tools & Cross-Surface Memory)
pip install imperal-mcp

Python 3.7 – 3.14 compatibility: On Python 3.10+, imperal-mcp runs natively. On older system Pythons (3.7 – 3.9), the zero-dependency _launch.py bootstrapper automatically provisions an isolated Python 3.12 runtime via uv and installs imperal-mcp[code]==<version> on first launch — so the full AST & Call-Graph Exoskeleton works seamlessly even on legacy systems.

2. Authenticate with Imperal Cloud (for Cloud Memory & Apps)

imperal-mcp login

This starts a browser-based OAuth 2.0 Device Authorization + PKCE flow against Imperal Cloud (api / gateway) and stores your credentials in ~/.config/imperal/credentials.json with 0600 permissions. (Local code intelligence tools work offline even before you log in.)

3. Connect Your LLM Client

Option A: One-Command Setup for Claude Code (Recommended)

Run inside your project repository:

imperal-mcp claude-setup --with-hooks

What this does safely and idempotently:

• Adds the imperal server to .mcp.json (preserving any existing mcpServers entries and refusing to overwrite malformed JSON files).
• Appends the IMPERAL-MCP-EXOSKELETON operating section to CLAUDE.md (preserving all existing project instructions).
• Installs a PostToolUse hook in .claude/settings.local.json using the exact Python environment binary that ran claude-setup. After Edit, MultiEdit, or Write, the hook runs check_syntax and reports any syntax errors to stderr with exit code 2 so Claude Code sees and fixes broken syntax immediately.

Option B: Claude Code CLI

claude mcp add imperal -- imperal-mcp

Option C: Cursor / Claude Desktop / Windsurf / Cline (.mcp.json or claude_desktop_config.json)

{
  "mcpServers": {
    "imperal": {
      "command": "imperal-mcp",
      "args": [],
      "env": {
        "IMPERAL_WORKSPACE": "/absolute/path/to/your/repo"
      }
    }
  }
}

Option D: OpenAI Codex / Gemini CLI / Goose

Point any MCP-compatible stdio client at the imperal-mcp executable with IMPERAL_WORKSPACE set to your repository root.

CLI Reference

imperal-mcp                  # Start the MCP server over stdio
imperal-mcp login            # Sign in via browser (Device Code + PKCE); supports --no-browser
imperal-mcp logout           # Revoke refresh token and delete local credentials
imperal-mcp claude-setup     # Configure .mcp.json and CLAUDE.md (--workspace, --with-hooks)
imperal-mcp install-hooks    # Install PostToolUse syntax-check hook in .claude/settings.local.json
imperal-mcp hook             # Run a Claude Code hook event handler (post-tool-use)
imperal-mcp status           # Print JSON readiness and repository profile for --workspace

Architecture & Security Guarantees

1. Public Cloud Topology (api, gateway, worker): All cloud requests communicate over HTTPS with Imperal Cloud's api and gateway endpoints, dispatching isolated app executions and sandbox smoke runs to worker runtimes.
2. Strict Workspace Confinement: Every local tool resolves paths and root overrides via os.path.realpath and verifies os.path.commonpath([workspace_root, candidate]) == workspace_root. Attempts to read outside the workspace raise OutsideWorkspaceError.
3. Config File Integrity: claude-setup and install-hooks parse existing .mcp.json and .claude/settings.local.json strictly — if a user file has a JSON syntax error, the CLI refuses to overwrite it rather than wiping existing settings.
4. Defensive PII Scrubbing: All cloud read and memory payloads pass through defensive_scrub, redacting emails, phone numbers, SSNs, payment cards, JWTs, API keys, and IBANs before entering the model context.

License, Protocol & Trademarks

• Code License: Licensed under the GNU General Public License v3.0 (GPL-3.0-only).
• Protocol Specification: Powered by ICNLI (Infrastructure Contextual Natural Language Interface), an open specification licensed under CC BY-SA 4.0.
• Privacy Policy: See PRIVACY.md for details on local execution, credential storage, and PII redaction.
• Trademarks & Attribution: Imperal, Imperal Cloud, Webbee, and ICNLI are trademarks of Imperal, Inc. Claude, Claude Code, Claude Desktop, and Anthropic are trademarks of Anthropic, PBC. Cursor is a trademark of Anysphere, Inc. OpenAI and Codex are trademarks of OpenAI, Inc. Windsurf is a trademark of Exafunction, Inc. (Codeium). Gemini is a trademark of Google LLC. All third-party product and company names are used solely to indicate MCP interoperability and compatibility; no endorsement or affiliation is implied.