ARIVE

# ARIVE MCP Server [](https://bun.sh/) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](LICENSE) A complete, production-ready TypeScript Model Context Protocol (MCP) server that implements the **ARIVE** framework: **Analyze**, **Reason**, **Integrate**, **Verify**, **Explain**. ARIVE merges local context compression, step-by-step backtracking reasoning graphs, isolated directory task runners, test verification loops, and telegraphic language output into a single, cohesive developer assistant engine. --- ## Architecture & Phases ```mermaid graph TD A[Analyze: Router & Compressor] --> R[Reason: Reflective Engine] R --> I[Integrate: Task Directories] I --> V[Verify: TDD Loop] V -- Failure Backprop --> R V --> E[Explain: Lithic Formatter] subgraph Analyze Phase ContentRouter --> SmartCrusher ContentRouter --> ASTCompressor ContentRouter --> CodeMapScanner ASTCompressor --> CcrRegistry end ``` ### A - Analyze (Context Compression) - **Content Router**: Automatically classifies incoming text blocks into `json`, `code`, `logs`, or `prose` to determine the optimal compression strategy. - **Smart JSON Crusher**: Recursively traverses JSON data, collapsing large arrays with more than 2 elements and replacing them with a summary description while preserving SRE/error fields. - **AST Code Compressor**: Discards comments, JSDocs, whitespace runs, and formatting details using the TypeScript Compiler API. - **Cache Aligner**: Normalizes spacing and carriage returns to ensure maximum KV cache hit rates on providers like Anthropic or Gemini. - **CCR Registry**: A hash-based Content-Compressed Retrieval store (`ccr:sha256_hash`). Allows referencing large payloads using 68-character hashes. - **CodeMap Scanner**: Recursively scans folders to generate directory trees, maps TypeScript export/import dependency flows, and queries Git branch statistics. ### R - Reason (Step-by-Step Logic Sequences) - **Reflective Engine**: Tracks thought sequences in a graph. Supports branching and backtracking: if a backtracking revision is requested, thoughts after the revision target are flagged as `"backtracked"` (retained in log but deactivated), and a new active sequence branches out. State is saved atomically to `.arive/thinking_state.json`. ### I - Integrate (Isolated Workspaces) - **Directory Isolation**: Spawns isolated, concurrent task directories under `.arive-tasks/<taskId>`. Prevents modifying the user's active files during automated refactoring/mutation runs. - **Subagent Runner**: Spawns CLI commands inside the isolated directory, guarding against sandbox directory escapes and command injection, and capturing subprocess runtime errors. ### V - Verify (TDD & Verification Loops) - **TDD Orchestrator**: Executes verification tests (e.g., `bun test`, `pytest`) inside the isolated CWD. - **Backprop Reflex**: Integrates assertion failures back into the reasoning history, prompting the engine to revise its hypothesis on subsequent iterations. - **CCR Verification**: Validates that retrieved raw content matches its original hash key before usage. ### E - Explain (Lithic Token Compression) - **Lithic Formatter**: Compresses conversational text into token-saving, telegraphic styles: - `lite`: Strips filler words ("just", "actually", "basically"). - `full`: Strips articles ("the", "a") and auxiliary verbs ("is", "are"). - `ultra`: telegraphic keyword mapping (e.g. `tests/verify.test.ts:24 fail`). - `normal`: Returns raw text without modification. --- ## Exposed MCP Tools ### `arive_compress` Compresses strings based on code, JSON, logs or prose optimizations, returning hash references for large sizes. | Parameter | Type | Required | Default | Description | | :------------ | :------ | :------- | :------ | :--------------------------------------------------------------- | | `content` | string | Yes | | The content raw text block to compress. | | `contentType` | enum | No | `auto` | Category of content: `json`, `code`, `logs`, `prose`, or `auto`. | | `forceCcr` | boolean | No | `false` | Force storing the result in the CCR registry. | ### `arive_decompress` Resolves CCR reference hashes back to their raw uncompressed representation. | Parameter | Type | Required | Default | Description | | :-------- | :----- | :------- | :------ | :-------------------------------------- | | `hash` | string | Yes | | The CCR hash (e.g., `ccr:sha256_hash`). | ### `arive_think` Records a single thought block in the reasoning sequence, managing backtracking. | Parameter | Type | Required | Default | Description | | :------------------- | :------ | :------- | :------ | :--------------------------------------------------- | | `thought` | string | Yes | | The reasoning thought text. | | `thoughtNumber` | integer | Yes | | The current thought index. | | `totalThoughts` | integer | Yes | | The estimated total thoughts. | | `nextThoughtNeeded` | boolean | Yes | | Whether another thought is expected after this one. | | `isRevision` | boolean | No | | Flag indicating this thought revises a previous one. | | `revisesThoughtNum` | integer | No | | The thought number being revised. | | `branchToThoughtNum` | integer | No | | The thought number to branch from (if backtracking). | ### `arive_integrate` Controls the workspace lifecycle (local directory tasks) and spawns subprocesses. | Parameter | Type | Required | Default | Description | | :-------- | :----- | :------- | :------ | :-------------------------------------------------------- | | `taskId` | string | Yes | | Unique identifier for the task workspace. | | `action` | enum | Yes | | The action to perform: `create`, `execute`, or `cleanup`. | | `command` | string | No | | CLI command to execute when action is `execute`. | ### `arive_verify` Runs testing suites in the task directory workspace path and backpropagates failures. | Parameter | Type | Required | Default | Description | | :------------ | :----- | :------- | :------ | :------------------------------------------ | | `taskId` | string | Yes | | Unique identifier for the task workspace. | | `testCommand` | string | Yes | | The test command to run (e.g., `bun test`). | ### `arive_explain` Transforms conversational messages into telegraphic token-saving ponytail styles, or returns ponytail instruction rules. | Parameter | Type | Required | Default | Description | | :-------- | :----- | :------- | :------ | :------------------------------------------------------------------- | | `message` | string | Yes | | The natural language text to compress, or get instructions for. | | `brevity` | enum | No | `full` | The level of brevity/laziness: `lite`, `full`, `ultra`, or `normal`. | ### `arive_codemap` Scans folder structure tree, maps imports/exports, or runs git diff checks. | Parameter | Type | Required | Default | Description | | :------------- | :------ | :------- | :------- | :-------------------------------------------------------- | | `action` | enum | Yes | | The codemap operation: `tree`, `dependencies`, or `diff`. | | `dir` | string | No | `.` | The directory to scan for tree or dependencies. | | `excludes` | array | No | `[]` | List of directories or files to exclude. | | `maxDepth` | integer | No | `10` | Max depth to scan for directory tree. | | `targetBranch` | string | No | `master` | Target branch for git diff comparison. | ### `arive_install` Automatically registers the ARIVE MCP server in all detected AI clients and installs Git pre-commit hooks, ARIVE protocol lifecycle hooks, ponytail rules/skills, and plugins. | Parameter | Type | Required | Default | Description | | :-------------- | :----- | :------- | :------ | :-------------------------------------------------------------------------------------------------- | | `workspacePath` | string | No | | Optional path to the project/workspace root directory to install rules, skills, plugins, and hooks. | | `editor` | string | No | | Optional name of the specific AI editor to target (e.g. `cursor`, `cline`, `roo`, `windsurf`). | --- ## ARIVE Protocol Lifecycle Hooks The ARIVE framework supports executing custom pre- and post-hook scripts at different stages of tool executions. If the `.arive/hooks` directory exists, the server will check for files matching specific hook names: - `pre-analyze` / `post-analyze` (run by `arive_compress` & `arive_codemap`) - `pre-reason` / `post-reason` (run by `arive_think`) - `pre-integrate` / `post-integrate` (run by `arive_integrate`) - `pre-verify` / `post-verify` (run by `arive_verify`) - `pre-explain` / `post-explain` (run by `arive_explain`) ### Environment Variables When a hook is executed, it receives the following environment variables: - `ARIVE_HOOK_NAME`: The name of the hook (e.g. `pre-integrate`). - `ARIVE_HOOK_PHASE`: The phase of the ARIVE protocol (e.g. `integrate`). - `ARIVE_HOOK_CONTEXT`: JSON-stringified argument context passed to the tool. - `ARIVE_HOOK_RESULT`: (Only for `post-` hooks) JSON-stringified result/response payload of the tool execution. If a `pre-` hook exits with a non-zero status code, the action is blocked, and the tool returns a failure error. --- ## Installation & Setup ### Requirements - [Bun](https://bun.sh/) (runtime & package manager) - [Git](https://git-scm.com/) ### Clone and Install ```bash # Clone the repository git clone https://github.com/sixtysixx/ARIVE.git cd ARIVE # Install dependencies bun install ``` ### Automatic Installation You can automatically register the ARIVE MCP server in all detected AI clients and install Git pre-commit hooks, ARIVE protocol lifecycle hooks, ponytail rules/skills, and plugins. Run the installer CLI using Bun: ```bash # Install for all detected editors bun run install # Install specifically for a preferred AI editor arive install --editor cursor arive install -e opencode ``` Supported editors: `cursor`, `cline`, `roo` (or `roocode`), `windsurf`, `opencode`, `kilocode`, `claude` (Claude Desktop), `claudecode` (Claude Code), `antigravity` (Google Antigravity), `omp` (oh-my-pi). Or use the `arive_install` MCP tool from within any active client (passing the optional `editor` or `workspacePath`). ### Running Tests ```bash bun test ``` ### Type Checking ```bash bun x tsc --noEmit ``` --- ## Client Configurations To register the ARIVE MCP server in your local AI editing clients: ### Gemini CLI (`antigravity-cli`) ARIVE ships a root-level `plugin.json`, `mcp_config.json`, `rules/`, and `skills/` so the entire repo is a valid Antigravity plugin. Install it in one command: ```bash agy plugin install https://github.com/sixtysixx/ARIVE ``` The CLI stages the plugin at `~/.gemini/antigravity-cli/plugins/arive/` and automatically loads the MCP server, Ponytail rules, and skills on next launch. Alternatively, register the MCP server manually in `%USERPROFILE%\.gemini\antigravity-cli\mcp_config.json`: ```json { "mcpServers": { "arive": { "command": "bunx", "args": ["--silent", "github:sixtysixx/ARIVE"] } } } ``` ### omp (oh-my-pi) Add this configuration to your user-level config at `~/.omp/agent/mcp.json` or your project-level config at `.omp/mcp.json`: ```json { "mcpServers": { "arive": { "command": "bunx", "args": ["--silent", "github:sixtysixx/ARIVE"] } } } ``` ### Claude Desktop Add this to your configuration (e.g., `%APPDATA%\EasyCode\claude_desktop_config.json` or standard `claude_desktop_config.json` configuration path): ```json { "mcpServers": { "arive": { "command": "bunx", "args": ["--silent", "github:sixtysixx/ARIVE"] } } } ``` ### OpenCode ARIVE ships a root-level `opencode.mjs` plugin module. Add the repo as a plugin in your global config (`~/.config/opencode/opencode.json`) or project config (`.opencode/opencode.json`) and the MCP server registers automatically: ```json { "plugin": ["github:sixtysixx/ARIVE"] } ``` Alternatively, register the MCP server manually: ```json { "mcp": { "arive": { "type": "local", "command": ["bunx", "--silent", "github:sixtysixx/ARIVE"], "enabled": true } } } ``` ### KiloCode KiloCode shares the same plugin architecture as OpenCode. Add the repo as a plugin in your KiloCode config and the MCP server registers automatically: ```json { "plugin": ["github:sixtysixx/ARIVE"] } ``` Alternatively, use the **MCP Servers** panel (gear icon → **Edit Global MCP**), or define it locally under `.kilocode/mcp.json`: ```json { "mcpServers": { "arive": { "command": "bunx", "args": ["--silent", "github:sixtysixx/ARIVE"] } } } ``` ### VS Code (Cline & Roo Code) You can configure this globally (via the **MCP Servers** tab in the Cline/Roo Code pane, clicking **Edit Global MCP**) or locally for a specific workspace: - **Cline Project-Level Config:** `.cline/mcp.json` - **Roo Code Project-Level Config:** `.roo/mcp.json` ```json { "mcpServers": { "arive": { "command": "bunx", "args": ["--silent", "github:sixtysixx/ARIVE"] } } } ``` ### Cursor Add this through the Cursor settings UI under **Settings > Features > MCP**, clicking **Add new MCP server** (with type `stdio` and command `bunx --silent github:sixtysixx/ARIVE`), or add it manually to your project's `.cursor/mcp.json`: ```json { "mcpServers": { "arive": { "command": "bunx", "args": ["--silent", "github:sixtysixx/ARIVE"] } } } ``` --- ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- ## Credits ARIVE integrates ideas and pipelines from the following core development paradigms - Thank you for the inspiration: - **headroom** (`chopratejas/headroom`): Local, reversible context compression. - **sequentialthinking** (`modelcontextprotocol/servers/sequentialthinking`): Step-by-step reasoning with reflective backtracking. - **ponytail** (`DietrichGebert/ponytail`): Lazy senior dev mode rulesets, skills, and plugins. - **codemap** (`JordanCoin/codemap`): Compact structural file tree and dependency flow mapping.