Imperal MCP

imperal-mcp — 面向 LLM 和 AI Agent 的 ICNLI 驱动超级套件 🐝

Python 3.7 – 3.14 · pip install "imperal-mcp[code]" 可在所有这些版本上开箱即用。

别再让你的 LLM 在盲目状态下运行。 imperal-mcp 是面向 LLM 的一体化超级套件与外骨骼，可为 Claude Code、Claude Desktop、Cursor、OpenAI Codex、Windsurf、Gemini CLI、Cline 和 Goose 提供实时 Tree-sitter AST 调用图、精准读取符号、无形的 ShadowGit 检查点、跨平台云记忆，以及由 ICNLI 和 Imperal Cloud 驱动的全栈云应用构建器。

只需安装一次，你的编码 Agent 就能不再把整个文件塞进上下文，通过一次调用映射并浏览陌生代码库，在每次编辑时自动检查影响范围和语法，在所有 IDE、终端和聊天界面中记住你的架构，并在 Imperal Marketplace 上构建、部署和变现全栈云应用。

---

开发者为何立即转用 imperal-mcp

看看接入 imperal-mcp 后，典型 LLM 编码会话会发生怎样的变化：

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

imperal-mcp 消除的 5 个结构性瓶颈

标准大模型工作流中的瓶颈	imperal-mcp SuperSuite 提供的能力	为什么你会立即感受到不同
不必要的 Token 与上下文消耗 — Agent 为了检查单个函数，就把数千行文件和原始 grep 输出读入上下文窗口。	精准 AST 与调用图切片（outline、read_symbol、graph_slice、contract_slice）仅返回所请求的符号定义、签名和调用边。	让上下文窗口保持精准 — 加载 30 行经 AST 验证的代码，而不是 2,000 行噪声；并通过 token_savings() 精确审计节省量。
缓慢、重复的项目摸底 — 每项新任务开始时，都要依次执行数十次 find、ls、grep 和 cat，模型才能理解项目结构。	一次完成结构化摸底（orient、repo_profile、search_code、coding_context）根据实时代码图梳理语言、入口点、测试运行器和排序后的符号。	冷启动零延迟 — 你的 Agent 在第 1 轮就能理解仓库架构。
跨工具的上下文丢失与遗忘 — 从 Cursor 切换到 Claude Code，或从终端切换到网页或移动端时，大模型会忘记你的架构、规则和决策。	跨平台统一云端记忆（recall_context、remember_fact、save_repo_note）会在所有 MCP 客户端、Imperal Web Panel 和 Telegram 之间同步用户指令与带引用的仓库笔记。	再也不用重复说明 — 你使用的每个平台和模型，都能共享一个持久的工程大脑。
担心破坏共享代码 — 大模型在未检查下游调用方或契约的情况下修改共享辅助函数，多文件实验失败后还会弄脏 .git。	影响范围计算与 ShadowGit 快照（impact_of_change、check_syntax、checkpoint、checkpoint_diff、checkpoint_rollback）会在修改前验证依赖项，并在 .git 之外为工作树创建快照。	充满信心地重构 — 修改前了解调用关系，实验失败时无需触碰 git log 即可回滚。
本地脚本走进死胡同 — 大多数 MCP 服务只封装单个 API；你无法将工作流变成可复用的应用或收入来源。	全栈应用构建器与市场变现（validate_ir、smoke_ir、deploy_ir、run_read_tool、run_write_tool、upload_file）让你能够在 Imperal Marketplace 上构建、部署并变现云应用。	让工作流创造收入 — 为自己、团队或整个 Imperal 生态系统构建云端扩展。

---

SuperSuite 的 5 大核心支柱

1. 精准上下文与真实 Token 遥测（AST 符号切片）

将数千行无关代码塞进大模型的上下文窗口会浪费 Token、延长首 Token 响应时间，并降低推理准确性。

• 先梳理，再只读取关键信息：与其将整个 1,500 行模块读入上下文，不如让你的 Agent 调用 outline(path)，查看包含类、方法和函数精确行范围的精简结构图，然后调用 read_symbol(path, "ClassName.method")（或 L120-180），只加载目标代码段。
• 真实的磁盘遥测数据（token_savings()）：在会话的任何时候调用 token_savings()，即可查看精确测量的字符数和行数（returned_chars 与 baseline_chars、returned_lines 与 baseline_lines、baseline_files，以及各工具的细分数据）。基线直接根据磁盘上实际匹配的文件测量（baseline_basis: "matched_files_on_disk"），绝不会通过与整个仓库或虚构倍数对比来夸大数据。

2. 实时代码图、调用契约与影响范围分析

安装 imperal-mcp[code] 后，服务会维护增量式的 Tree-sitter AST 和依赖关系图（并内置 Python ast 回退机制，因此即使在精简环境中，Python 语法检查和大纲功能也能正常使用）：

• orient(query) — 一站式任务启动入口，将仓库概况与针对任务排名靠前的符号和代码匹配结果结合起来。
• repo_profile() & coding_context() — 即时概览语言、文件数量、架构枢纽、测试命令提示以及 Git 工作区状态。
• search_code(query, kind, path_glob) — 在已索引的工作区中进行符号、语义和词法混合搜索。
• graph_slice(symbols, depth) — 批量查询符号定义、签名、直接调用方和被调用方。
• contract_slice(symbols) — 检查精确的函数签名、返回注解、抛出的异常以及实际调用点的参数形式。
• impact_of_change(symbols) — 在修改代码之前，计算所有依赖于待修改代码的下游文件和调用方符号。
• check_syntax(path) — 每次编辑后即时验证语法，并可选配置 Claude Code 的自动 PostToolUse 钩子。

3. 在所有平台和界面中持久保存记忆与上下文

架构知识不应被锁定在单个 IDE 标签页或模型供应商中：

• remember_fact(fact, category, tags) — 在 Imperal Cloud Memory 中存储常设工程规则、用户偏好和操作指令。
• save_repo_note(note, repo, citations) — 记录与项目相关的持久仓库约定、构建命令和架构不变量。
• recall_context(query) — 从任意兼容 MCP 的客户端（Claude Code、Cursor、Windsurf、Codex、Gemini CLI）、Imperal Web Panel 或 Telegram 中检索相关用户事实和仓库备注。

4. 在 Imperal Marketplace 上构建、部署和变现应用

由 ICNLI（基础设施上下文自然语言接口） 提供支持，imperal-mcp 是完整的 云应用 SDK 和执行引擎：

• 通过自然语言开发全栈云应用：使用内置 MCP 资源（imperal://ir-spec、imperal://ui-catalog、imperal://examples）和 build_imperal_app 提示词，让你的 LLM 将需求编译为声明式的 Imperal 中间表示（app.ir.json） 包，其中包含 UI 视图、状态架构、连接器和类型化工具处理程序。
• 在数秒内验证、冒烟测试并部署：
  1. validate_ir(app_ir) — 在本地静态验证 IR 封装及每个声明式步骤。
  2. smoke_ir(app_ir, function, args) — 在 Imperal Cloud 的隔离沙盒存储中执行实时试运行，并检查 {ok, result, trace}。
  3. deploy_ir(app_ir, app_id) — 将已验证的应用直接部署到你的 Imperal Cloud 账户。
• 在 Imperal Marketplace 上发布并变现：应用部署并测试完成后，你可以将其发布到 Imperal Marketplace，与其他开发者和企业分享或出售自定义 SaaS 连接器、DevOps 自动化工具、分析套件和领域工作流。

5. 隐形 ShadowGit 安全网与能力门控的云端执行

• ShadowGit 检查点（checkpoint、checkpoint_diff、checkpoint_rollback）：在进行高风险重构前，将工作区快照保存到隔离的 shadow git 存储中，而不会在真实 .git 历史记录中创建杂乱的 WIP 提交。可随时比较差异；如果实验失败，也可回滚（checkpoint_rollback 明确标记为破坏性操作，因此 MCP 客户端会在覆盖工作文件前提示确认）。
• 工作区边界保护：所有本地代码和文件工具都会严格解析工作区路径——请求若指向配置的工作区根目录之外的路径或 root 目录（例如 ~/.zshrc 或 /etc），将以 OutsideWorkspaceError 拒绝。
• 三级云端安全机制（read / write / destructive）：
  • run_read_tool 执行只读操作，并自动清除响应中的个人身份信息。
  • run_write_tool 直接执行标准写入工具；对于 destructive 工具，需要用户交互式同意（MCP elicitation）；对于金融／资金操作，则强制要求通过带外面板审批。

完整工具与资源目录（25 个工具 + 5 个资源）

本地代码智能与调用图（imperal-mcp[code]）

工具	只读	破坏性	功能
orient(query, root?)	是	否	一次调用即可了解任务背景：将仓库概况（files、languages、git、test_hints、sample_symbols）与针对 query 的高相关度语义及词法代码匹配结果结合起来。
repo_profile(root?)	是	否	返回结构化的仓库概览：文件数量、语言分布、当前 git 引用、测试运行器提示，以及关键入口符号。
search_code(query, k?, path_glob?, kind?, root?)	是	否	在已索引的工作区中进行混合式语义 + 词法 + 符号搜索（kind：all、symbol 或 file）。
outline(path, root?)	是	否	构建源文件的结构图（类、函数、方法和主要区域，并标出精确的 1 起始行号范围），无需加载完整文件内容。
read_symbol(path, name, root?)	是	否	仅读取特定函数、类、方法（Class.method）或行范围（L10-50），行号从 1 开始。
graph_slice(symbols, depth?, root?)	是	否	从实时 AST 调用图中，返回一个或多个符号的定义位置、签名、直接调用方和直接被调用方。
contract_slice(symbols?, query?, kind?, k?, root?)	是	否	一次调用即可提取经验证的符号契约（定义、签名和调用点证据）。
impact_of_change(symbols, root?)	是	否	计算下游影响范围：调用或依赖你计划修改的符号的所有文件和符号。
check_syntax(path, root?)	是	否	在编辑后验证源文件语法（使用 Tree-sitter 处理多语言 AST，并使用 Python ast 和 JSON 标准库进行验证；对于不支持的文件类型，返回 supported: false, clean: null）。
coding_context(root?)	是	否	返回 git 分支、HEAD、工作区中有未提交更改的文件以及近期提交，帮助快速了解当前情况。
token_savings()	是	否	报告与磁盘上实际匹配文件相关的实测会话字符和行数数据（baseline_basis: "matched_files_on_disk"、baseline_files、returned_chars、baseline_chars、saved_chars、returned_lines、baseline_lines、saved_lines、compression_pct、by_tool）。

本地 ShadowGit 检查点（imperal-mcp[code]）

工具	只读	有破坏性	功能说明
checkpoint(label?, touched_paths?, root?)	否	否	将工作区状态快照保存到隔离的 ShadowGit 存储中，不触碰 .git 历史记录。
checkpoint_diff(target?, root?)	是	否	显示当前工作文件与 ShadowGit 检查点（step 编号或 ref）之间的统一差异。
checkpoint_rollback(target?, root?)	否	是	从 ShadowGit 检查点恢复工作区文件（设置 destructiveHint=True，以便 MCP 客户端在覆盖工作文件前提示用户）。

跨平台云端记忆（Imperal Cloud）

工具	只读	有破坏性	功能说明
recall_context(query?, category?, limit?)	是	否	从 Imperal Cloud（memory-index）召回持久有效的规则、架构决策、用户偏好及跨界面事实，并自动清理个人身份信息（PII）。
remember_fact(fact, category?, tags?)	否	否	将持久事实、规则或用户偏好存入统一的 Imperal Cloud 记忆，并在 Terminal、Web Panel 和 Telegram 之间共享。
save_repo_note(note, repo?, citations?)	否	否	将带有引用依据（file:line）的架构或仓库备注保存到 Imperal Cloud 记忆中。

Imperal Cloud 应用构建器、沙盒与执行（ICNLI）

工具	只读	有破坏性	功能说明
validate_ir(app_ir)	是	否	对 app.ir.json 包执行离线结构与语义验证（ir_version: "1.0"、状态、视图、处理程序）。
smoke_ir(app_ir, function, args?)	是	否	在 Imperal Cloud 的隔离沙盒存储中逐步执行处理程序，并返回 {ok, result, trace}。
deploy_ir(app_ir, app_id?)	否	否	验证应用并将 app.ir.json 部署到你的 Imperal Cloud 账户。
list_apps()	是	否	列出你的 Imperal Cloud 账户中所有已安装和可用的应用，并提供 {id, name, version, description, category, status}。
get_app(app_id)	是	否	返回完整的应用清单、工具架构以及 action_type 分类（read / write / destructive）。
run_read_tool(app_id, function, params?)	是	否	执行 read 级云端工具，并清理响应中的 PII（email、phone、ssn、card、jwt、api_key、iban）。
run_write_tool(app_id, function, params?)	否	是	直接执行 write 工具；对 destructive 工具请求交互式人工许可（approve_once / autopilot / reject）；并阻止直接进行资金转账，改为要求在面板中确认。
upload_file(path, name?)	否	否	将本地文件上传到你的 Imperal Cloud 存储，并返回可用于云端工具调用的 storage:// URI。

内置 MCP 资源

资源 URI	内容
imperal://exoskeleton-protocol	面向大模型的操作规范：先确认环境，精准读取 AST，检查影响范围，并验证语法。
imperal://ui-catalog	app.ir.json 视图中可用的 17 种声明式 UI 组件参考。
imperal://ir-spec	app.ir.json 封装格式、状态架构及 17 种确定性处理程序步骤类型的完整规范。
imperal://examples	完整、可运行的 app.ir.json 参考应用。
imperal://build-prompt	设计、验证、冒烟测试和部署 Imperal 应用的分步系统操作手册。

---

安装与快速入门

1. 安装软件包

# 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：在 Python 3.10 及更高版本中，imperal-mcp 可原生运行。在较旧的系统 Python（3.7–3.9）中，零依赖的 _launch.py 引导程序会通过 uv 自动配置隔离的 Python 3.12 运行时，并在首次启动时安装 imperal-mcp[code]==<version>，因此完整的 AST 与调用图 Exoskeleton 即使在旧系统上也能无缝运行。

2. 使用 Imperal Cloud 进行身份验证（适用于 Cloud Memory 和 Apps）

imperal-mcp login

这会针对 Imperal Cloud（api / gateway）启动基于浏览器的 OAuth 2.0 Device Authorization + PKCE 流程，并将凭据以 0600 权限保存到 ~/.config/imperal/credentials.json。（即使尚未登录，本地代码智能工具也可以离线运行。）

3. 连接你的 LLM 客户端

选项 A：Claude Code 一键设置（推荐）

在项目仓库中运行：

imperal-mcp claude-setup --with-hooks

此操作安全且幂等：

• 将 imperal 服务添加到 .mcp.json（保留所有现有的 mcpServers 条目，并拒绝覆盖格式错误的 JSON 文件）。
• 将 IMPERAL-MCP-EXOSKELETON 操作章节追加到 CLAUDE.md（保留所有现有项目指令）。
• 使用运行 claude-setup 的确切 Python 环境二进制文件，在 .claude/settings.local.json 中安装 PostToolUse 钩子。在执行 Edit、MultiEdit 或 Write 后，该钩子会运行 check_syntax，并以退出代码 2 将任何语法错误报告到 stderr，让 Claude Code 立即发现并修复语法错误。

选项 B：Claude Code CLI

claude mcp add imperal -- imperal-mcp

选项 C：Cursor / Claude Desktop / Windsurf / Cline（.mcp.json 或 claude_desktop_config.json）

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

选项 D：OpenAI Codex / Gemini CLI / Goose

将任何兼容 MCP 的 stdio 客户端指向 imperal-mcp 可执行文件，并将 IMPERAL_WORKSPACE 设为仓库根目录。

---

CLI 参考

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

---

架构与安全保障

1. 公共云拓扑（api、gateway、worker）： 所有云请求均通过 HTTPS 与 Imperal Cloud 的 api 和 gateway 端点通信，并将隔离的应用执行和沙箱冒烟测试分派给 worker 运行时。
2. 严格的工作区隔离： 每个本地工具都会通过 os.path.realpath 解析路径和 root 覆盖值，并验证 os.path.commonpath([workspace_root, candidate]) == workspace_root。尝试读取工作区以外的内容会引发 OutsideWorkspaceError。
3. 配置文件完整性： claude-setup 和 install-hooks 会严格解析现有的 .mcp.json 和 .claude/settings.local.json——如果用户文件存在 JSON 语法错误，CLI 会拒绝覆盖该文件，而不是清除现有设置。
4. 主动清除个人身份信息（PII）： 所有云端读取和记忆载荷都会经过 defensive_scrub 处理，在进入模型上下文之前，清除电子邮件地址、电话号码、SSN、支付卡信息、JWT、API 密钥和 IBAN。

---

许可证、协议与商标

• 代码许可证：依据 GNU 通用公共许可证 v3.0（GPL-3.0-only） 授权。
• 协议规范：基于 ICNLI（Infrastructure Contextual Natural Language Interface），这是一项采用 CC BY-SA 4.0 授权的开放规范。
• 隐私政策：有关本地执行、凭据存储和 PII 清除的详情，请参阅 PRIVACY.md。
• 商标与归属： Imperal、Imperal Cloud、Webbee 和 ICNLI 是 Imperal, Inc. 的商标。 Claude、Claude Code、Claude Desktop 和 Anthropic 是 Anthropic, PBC 的商标。Cursor 是 Anysphere, Inc. 的商标。OpenAI 和 Codex 是 OpenAI, Inc. 的商标。Windsurf 是 Exafunction, Inc.（Codeium）的商标。Gemini 是 Google LLC 的商标。所有第三方产品和公司名称仅用于说明 MCP 互操作性和兼容性；这并不表示获得认可或存在关联。