@brutalist/mcp 0.6.11 → 0.6.13

package/README.md

@@ -1,59 +1,48 @@
-# Brutalist MCP 💀
+# Brutalist MCP
 
-Your startup will fail. Your architecture will collapse. Your code is a security nightmare.
+Multi-perspective code analysis using Claude Code, Codex, and Gemini CLI agents.
 
-But this time, you'll know *why* before users do.
+Get direct, honest technical feedback on your code, architecture, and ideas before they reach production.
 
-## Deploy AI Critics That Don't Lie
+## What It Does
 
-Every AI tells you what you want to hear. This one tells you what you need to know.
+The Brutalist MCP connects your AI coding assistant to three different CLI agents (Claude, Codex, Gemini), each providing independent analysis. This gives you multiple perspectives on:
 
-Three brutal CLI agents. Zero sugar-coating. Maximum carnage.
+- Code quality and security vulnerabilities
+- Architecture decisions and scalability
+- Product ideas and technical feasibility
+- Research methodology and design flaws
 
-Three brutal CLI agents that can analyze anything. Each agent brings different perspectives to demolish your work from every angle.
+Real file-system access. Straightforward analysis. No sugar-coating.
 
-Real file-system analysis. Actual brutal prompts. Intelligent pagination for enterprise codebases. No participation trophies.
+## Quick Start
 
-## Setup
+### Step 1: Install a CLI Agent
 
-### Prerequisites
-
-Install at least one CLI agent:
-- **Claude Code**: `npm install -g claude` (or via Claude desktop app)
-- **Codex**: Install from [OpenAI Codex](https://github.com/openai/codex-cli)
-- **Gemini**: `npm install -g @google/gemini-cli` or authenticate via `gemini auth`
-
-### Installation
-
-<details>
-<summary><strong>Claude Code</strong> — One-liner</summary>
+You need at least one of these installed:
 
 ```bash
-claude mcp add brutalist --scope user -- npx -y @brutalist/mcp
-```
-</details>
+# Option 1: Claude Code (recommended)
+npm install -g claude
 
-<details>
-<summary><strong>VS Code / Cline</strong> — Manual config</summary>
+# Option 2: Codex
+# Install from https://github.com/openai/codex-cli
 
-```bash
-code --add-mcp '{"name":"brutalist","command":"npx","args":["-y","@brutalist/mcp"]}'
+# Option 3: Gemini
+npm install -g @google/gemini-cli
 ```
-</details>
 
-<details>
-<summary><strong>Gemini CLI</strong> — One-liner</summary>
+### Step 2: Install the MCP Server
 
+Choose your IDE:
+
+**Claude Code:**
 ```bash
-gemini mcp add brutalist -- npx -y @brutalist/mcp
+claude mcp add brutalist --scope user -- npx -y @brutalist/mcp
 ```
-</details>
-
-<details>
-<summary><strong>Cursor</strong> — Manual config</summary>
-
-Add to `~/.cursor/mcp.json` or use **Settings → MCP & Integrations**
 
+**Cursor:**
+Add to `~/.cursor/mcp.json`:
 ```json
 {
   "brutalist": {
@@ -62,13 +51,14 @@ Add to `~/.cursor/mcp.json` or use **Settings → MCP & Integrations**
   }
 }
 ```
-</details>
-
-<details>
-<summary><strong>Windsurf</strong> — Manual config</summary>
 
-Add to `~/.codeium/windsurf/mcp_config.json` or use **Plugin Store**
+**VS Code / Cline:**
+```bash
+code --add-mcp '{"name":"brutalist","command":"npx","args":["-y","@brutalist/mcp"]}'
+```
 
+**Windsurf:**
+Add to `~/.codeium/windsurf/mcp_config.json`:
 ```json
 {
   "brutalist": {
@@ -77,187 +67,165 @@ Add to `~/.codeium/windsurf/mcp_config.json` or use **Plugin Store**
   }
 }
 ```
-</details>
 
-## Brutalist Workflows
+### Step 3: Verify Installation
+
+```bash
+# Check which CLI agents are available
+cli_agent_roster()
+```
 
-### 🔍 **Codebase Destruction**
+## Usage Examples
 
-> Analyze actual files in your repository for security holes, performance disasters, and architectural nightmares.
+### Analyze Your Codebase
 
 ```bash
-# Demolish your entire codebase
+# Analyze entire project
 roast_codebase "/path/to/your/project"
 
-# Target specific modules for focused brutality
-roast_codebase "/src/auth"          # Authentication vulnerabilities
-roast_codebase "/src/api/handlers"  # API endpoint disasters
-roast_codebase "/components"        # React component chaos
+# Analyze specific modules
+roast_codebase "/src/auth"
+roast_codebase "/src/api/handlers"
 ```
 
----
-
-### 💡 **Idea Obliteration**
-
-> Reality-check your startup dreams, product concepts, and technical decisions.
+### Validate Ideas
 
 ```bash
-# Startup idea destruction
+# Evaluate a product concept
 roast_idea "A social network for developers to share code snippets"
 
-# Technical decision analysis
+# Review technical decisions
 roast_idea "Migrating our monolith to microservices with Kubernetes"
-
-# Product feature validation
-roast_idea "Adding AI-powered code suggestions to our IDE"
 ```
 
----
-
-### 🏗️ **Architecture Annihilation**
-
-> Find every scaling bottleneck, cost explosion, and operational nightmare in your system design.
+### Review Architecture
 
 ```bash
-# System architecture review
+# System architecture analysis
 roast_architecture "Microservices with event sourcing and CQRS"
 
-# Infrastructure design analysis
+# Infrastructure design review
 roast_architecture """
 API Gateway → Load Balancer → 3 Node.js services → PostgreSQL
 Redis for caching, Docker containers on AWS ECS
 """
 ```
 
----
-
-### 🔒 **Security Demolition**
-
-> Expose authentication bypasses, injection vulnerabilities, and data leak opportunities.
+### Security Analysis
 
 ```bash
-# Authentication system analysis
+# Authentication review
 roast_security "JWT tokens with user roles in localStorage"
 
-# API security review
+# API security check
 roast_security "GraphQL API with dynamic queries and no rate limiting"
 ```
 
----
-
-### 🤺 **Multi-Agent Warfare**
-
-> Deploy multiple CLI agents in adversarial combat for maximum destruction.
+### Compare Perspectives
 
 ```bash
-# Technical decision debate
+# Get multiple viewpoints on technical decisions
 roast_cli_debate "Should we use TypeScript or Go for this API?"
 
-# Architecture comparison battle
+# Compare architecture approaches
 roast_cli_debate "Microservices vs Monolith for our e-commerce platform"
 ```
 
----
-
-### 🛠️ **Meta Commands**
-
-```bash
-# Check which CLI agents are available
-cli_agent_roster()
-```
-
 ## How It Works
 
-This MCP server orchestrates brutal feedback from locally installed CLI agents:
-- **Claude Code CLI** - Anthropic's code assistant with brutal system prompts
-- **Codex CLI** - OpenAI's code-focused model for technical criticism  
-- **Gemini CLI** - Google's model for architectural and system analysis
+This MCP server coordinates analysis from locally installed CLI agents:
+- **Claude Code CLI** - Code review and architectural analysis
+- **Codex CLI** - Security and technical implementation review
+- **Gemini CLI** - System design and scalability analysis
 
-Each agent runs locally on your machine with custom brutal prompts to find real problems before production fails.
+Each agent runs locally with direct file-system access, providing independent perspectives on your code and design decisions.
 
-**⏱️ Analysis Timeout:** 25 minutes default - thorough analysis takes time to find real issues. Complex codebases and architectural reviews need deep analysis to catch subtle problems that quick scans miss.
+**Analysis time:** Up to 25 minutes for complex projects. Thorough analysis requires time to examine code patterns, dependencies, and architectural decisions.
 
-## 📄 Pagination Support (v0.5.0+)
+## Pagination for Large Results
 
-Handle enterprise-scale analyses that exceed Claude Code's 25K token limit:
+For analyses that exceed your IDE's token limit:
 
 ```bash
-# Enable pagination for large codebases
+# Set chunk size for large codebases
 roast_codebase({targetPath: "/monorepo", limit: 20000})
 
-# Continue reading from where you left off
+# Continue from where you left off
 roast_codebase({targetPath: "/monorepo", offset: 20000, limit: 20000})
 
-# Smart chunking preserves readability
+# Use cursor-based navigation
 roast_codebase({targetPath: "/complex-system", cursor: "offset:25000"})
 ```
 
-**Features:**
-- **Smart Boundary Detection** - Preserves paragraphs and sentences
-- **Token Estimation** - Real-time cost awareness (~4 chars = 1 token)
-- **Rich Metadata** - Progress indicators and continuation instructions
-- **Configurable Chunks** - 1K to 100K characters per response
+Features:
+- Smart boundary detection (preserves paragraphs and sentences)
+- Token estimation (~4 chars = 1 token)
+- Progress indicators
+- Configurable chunk size (1K to 100K characters)
 
 ## Tools
 
-### Code & Architecture Analysis
-| Tool | What gets destroyed | CLI Agents Used |
-|------|-------------------|-----------------|
-| `roast_codebase` | Security holes, performance disasters, maintainability nightmares in actual files | All available |
-| `roast_file_structure` | Directory chaos, naming disasters, structural nightmares | All available |
-| `roast_dependencies` | Version conflicts, security vulns, dependency hell | All available |
-| `roast_git_history` | Commit disasters, branching chaos, collaboration failures | All available |
-| `roast_test_coverage` | Testing gaps, quality blind spots, coverage lies | All available |
-
-### Conceptual Analysis
-| Tool | What gets destroyed | CLI Agents Used |
-|------|-------------------|-----------------|
-| `roast_idea` | Why imagination fails to become reality | All available |
-| `roast_architecture` | Scaling failures, cost explosions, operational complexity | All available |
-| `roast_research` | Methodological flaws, irreproducible results, statistical crimes | All available |
-| `roast_security` | Attack vectors, authentication bypasses, data leaks | All available |
-| `roast_product` | UX disasters, adoption barriers, user abandonment | All available |
-| `roast_infrastructure` | Single points of failure, hidden costs, 3AM outages | All available |
-
-### Meta Tools
-| Tool | What it does |
-|------|--------------|
-| `roast_cli_debate` | Multiple CLI agents argue until truth emerges |
-| `cli_agent_roster` | Shows which CLI agents are available on your system |
-
-## CLI Agent Selection
-
-The system automatically detects and uses available CLI agents:
+### Code & Architecture
+
+| Tool | Analyzes |
+|------|----------|
+| `roast_codebase` | Security vulnerabilities, performance issues, code quality |
+| `roast_file_structure` | Directory organization, naming conventions, structure |
+| `roast_dependencies` | Version conflicts, security vulnerabilities, compatibility |
+| `roast_git_history` | Commit quality, branching strategy, collaboration patterns |
+| `roast_test_coverage` | Test coverage, quality gaps, testing strategy |
+
+### Design & Planning
+
+| Tool | Analyzes |
+|------|----------|
+| `roast_idea` | Feasibility, market fit, implementation challenges |
+| `roast_architecture` | Scalability, cost, operational complexity |
+| `roast_research` | Methodology, reproducibility, statistical validity |
+| `roast_security` | Attack vectors, authentication, authorization |
+| `roast_product` | UX, adoption barriers, user needs |
+| `roast_infrastructure` | Reliability, scaling, operational overhead |
+
+### Utilities
+
+| Tool | Purpose |
+|------|---------|
+| `roast_cli_debate` | Multi-agent discussion from different perspectives |
+| `cli_agent_roster` | Show available CLI agents on your system |
+
+## Advanced Usage
+
+### Choose Specific CLI Agents
 
 ```bash
-# Use specific CLI agent
+# Use a specific agent
 roast_codebase(targetPath="/src", preferredCLI="claude")
 
-# Let system choose based on analysis type
-roast_security "/auth/module"  # Prefers Codex for security
+# System automatically selects best agent for task
+roast_security "/auth/module"  # Typically uses Codex
 
-# Force multi-agent analysis (default)
-roast_idea "..."  # All available agents analyze in parallel
+# Multi-agent analysis (default)
+roast_idea "..."  # All available agents provide perspectives
 ```
 
-### Smart Selection Rules
-
-Different CLI agents excel at different analysis types:
-- **Code review**: Claude > Codex > Gemini
-- **Architecture**: Gemini > Claude > Codex  
-- **Security**: Codex > Claude > Gemini
-- **Research**: Claude > Gemini > Codex
+### Agent Strengths
 
-## Why This Works
+Different agents have different strengths:
+- **Code review**: Claude, Codex, Gemini
+- **Architecture**: Gemini, Claude, Codex
+- **Security**: Codex, Claude, Gemini
+- **Research**: Claude, Gemini, Codex
 
-**Problem:** AI optimizes for engagement, not truth.  
-**Solution:** Deploy multiple local CLI agents with adversarial perspectives.  
-**Result:** Brutal honesty through systematic destruction before expensive failures.
+## Why Multiple Perspectives
 
-Your code will fail. Your startup will struggle. Better to learn this from brutal CLI agents than from production outages at 3AM.
+Each CLI agent brings a different approach to analysis:
+- Different training data and focus areas
+- Independent evaluation of the same code
+- Varied perspectives on technical tradeoffs
 
-The only AI that prevents disasters instead of causing them.
+Getting multiple viewpoints helps identify issues that a single perspective might miss.
 
 ---
 
-Local CLI agents → Brutal system prompts → Parallel execution → Adversarial synthesis → Production survival
+**License:** MIT
+**Issues:** https://github.com/ejmockler/brutalist-mcp/issues

package/dist/brutalist-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brutalist-server.d.ts","sourceRoot":"","sources":["../src/brutalist-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWpE,OAAO,EACL,qBAAqB,EAKtB,MAAM,sBAAsB,CAAC;AAc9B,qBAAa,eAAe;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,qBAAqB,CAAC;IACrC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAgC;IACtD,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAC,CAAa;IAErC,OAAO,CAAC,cAAc,CAIjB;gBAEO,MAAM,GAAE,qBAA0B;IA0C9C,OAAO,CAAC,oBAAoB,CAkE1B;IAEF,OAAO,CAAC,oBAAoB,CAsC1B;IAEI,KAAK;YAeG,gBAAgB;YAMhB,eAAe;IAmItB,aAAa,IAAI,MAAM,GAAG,SAAS;IAKnC,OAAO,IAAI,IAAI;IAOtB,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,oBAAoB;IAoG5B;;OAEG;YACW,eAAe;YAuLf,gBAAgB;IAkK9B,OAAO,CAAC,gBAAgB;YA0FV,wBAAwB;IA0FtC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,kBAAkB;IA4E1B,OAAO,CAAC,uBAAuB;IAqH/B,OAAO,CAAC,mBAAmB;YA8Bb,mBAAmB;CAUlC"}
+{"version":3,"file":"brutalist-server.d.ts","sourceRoot":"","sources":["../src/brutalist-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWpE,OAAO,EACL,qBAAqB,EAKtB,MAAM,sBAAsB,CAAC;AAc9B,qBAAa,eAAe;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,qBAAqB,CAAC;IACrC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAgC;IACtD,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAC,CAAa;IAErC,OAAO,CAAC,cAAc,CAIjB;gBAEO,MAAM,GAAE,qBAA0B;IA0C9C,OAAO,CAAC,oBAAoB,CAkE1B;IAEF,OAAO,CAAC,oBAAoB,CAsC1B;IAEI,KAAK;YAeG,gBAAgB;YAMhB,eAAe;IAmItB,aAAa,IAAI,MAAM,GAAG,SAAS;IAKnC,OAAO,IAAI,IAAI;IAOtB,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,oBAAoB;IAoG5B;;OAEG;YACW,eAAe;YAuLf,gBAAgB;IAkK9B,OAAO,CAAC,gBAAgB;YA0FV,wBAAwB;IA0FtC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,kBAAkB;IA6F1B,OAAO,CAAC,uBAAuB;IAuH/B,OAAO,CAAC,mBAAmB;YA8Bb,mBAAmB;CAUlC"}

package/dist/brutalist-server.js

@@ -12,7 +12,7 @@ import { TOOL_CONFIGS } from './tool-definitions.js';
 import { extractPaginationParams, parseCursor, PAGINATION_DEFAULTS, ResponseChunker, createPaginationMetadata, formatPaginationStatus, estimateTokenCount } from './utils/pagination.js';
 import { ResponseCache } from './utils/response-cache.js';
 // Use environment variable or fallback to manual version
-const PACKAGE_VERSION = process.env.npm_package_version || "0.4.4";
+const PACKAGE_VERSION = process.env.npm_package_version || "0.6.12";
 export class BrutalistServer {
     server;
     config;
@@ -26,7 +26,7 @@ export class BrutalistServer {
     constructor(config = {}) {
         this.config = {
             workingDirectory: process.cwd(),
-            defaultTimeout: 1500000, // 25 minutes for thorough CLI analysis
+            defaultTimeout: 120000, // 2 minutes for testing (configurable via BRUTALIST_TIMEOUT env)
             transport: 'stdio', // Default to stdio for backward compatibility
             httpPort: 3000,
             ...config
@@ -373,9 +373,9 @@ export class BrutalistServer {
                 roster += "## Pagination Support (NEW in v0.5.2)\n";
                 roster += "**All tools now support intelligent pagination:**\n";
                 roster += "- Analysis results are cached with 2-hour TTL\n";
-                roster += "- Use `analysis_id` from response to paginate without re-running\n";
+                roster += "- Use `context_id` from response to resume conversation\n";
                 roster += "- Smart text chunking preserves readability\n";
-                roster += "- Example: `roast_codebase(analysis_id: 'a3f5c2d8', offset: 25000)`\n\n";
+                roster += "- Example: `roast_codebase(context_id: 'a3f5c2d8', offset: 25000)`\n\n";
                 roster += "## Brutalist Philosophy\n";
                 roster += "*All tools use CLI agents with brutal system prompts for maximum reality-based criticism.*\n";
                 return {
@@ -445,13 +445,13 @@ export class BrutalistServer {
             const explicitPaginationRequested = args.offset !== undefined ||
                 args.limit !== undefined ||
                 args.cursor !== undefined ||
-                args.analysis_id !== undefined;
-            logger.info(`🔧 DEBUG: explicitPaginationRequested=${explicitPaginationRequested}, offset=${args.offset}, limit=${args.limit}, cursor=${args.cursor}, analysis_id=${args.analysis_id}`);
-            // Check cache if analysis_id provided
-            if (args.analysis_id && !args.force_refresh) {
-                const cachedContent = await this.responseCache.get(args.analysis_id, sessionId);
+                args.context_id !== undefined;
+            logger.info(`🔧 DEBUG: explicitPaginationRequested=${explicitPaginationRequested}, offset=${args.offset}, limit=${args.limit}, cursor=${args.cursor}, context_id=${args.context_id}`);
+            // Check cache if context_id provided
+            if (args.context_id && !args.force_refresh) {
+                const cachedContent = await this.responseCache.get(args.context_id, sessionId);
                 if (cachedContent) {
-                    logger.info(`🎯 Cache HIT for analysis_id: ${args.analysis_id}`);
+                    logger.info(`🎯 Cache HIT for context_id: ${args.context_id}`);
                     const cachedResult = {
                         success: true,
                         responses: [{
@@ -461,14 +461,14 @@ export class BrutalistServer {
                                 executionTime: 0
                             }]
                     };
-                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, args.analysis_id, explicitPaginationRequested);
+                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, args.context_id, explicitPaginationRequested);
                 }
                 else {
-                    logger.warn(`❌ Cache MISS for analysis_id: ${args.analysis_id}, session: ${sessionId}`);
-                    // Don't silently re-run - analysis_id should always hit cache or error
-                    throw new Error(`Analysis ID "${args.analysis_id}" not found in cache. ` +
+                    logger.warn(`❌ Cache MISS for context_id: ${args.context_id}, session: ${sessionId}`);
+                    // Don't silently re-run - context_id should always hit cache or error
+                    throw new Error(`Context ID "${args.context_id}" not found in cache. ` +
                         `It may have expired (2 hour TTL) or belong to a different session. ` +
-                        `Remove analysis_id parameter to run a new analysis.`);
+                        `Remove context_id parameter to run a new analysis.`);
                 }
             }
             // Generate cache key for this request
@@ -482,12 +482,12 @@ export class BrutalistServer {
             if (!args.force_refresh) {
                 const cachedContent = await this.responseCache.get(cacheKey, sessionId);
                 if (cachedContent) {
-                    // Get existing analysis_id or create new alias
-                    const existingAnalysisId = this.responseCache.findAnalysisIdForKey(cacheKey);
-                    const analysisId = existingAnalysisId
-                        ? this.responseCache.createAlias(existingAnalysisId, cacheKey)
-                        : this.responseCache.generateAnalysisId(cacheKey);
-                    logger.info(`🎯 Cache hit for new request, using analysis_id: ${analysisId}`);
+                    // Get existing context_id or create new alias
+                    const existingContextId = this.responseCache.findContextIdForKey(cacheKey);
+                    const contextId = existingContextId
+                        ? this.responseCache.createAlias(existingContextId, cacheKey)
+                        : this.responseCache.generateContextId(cacheKey);
+                    logger.info(`🎯 Cache hit for new request, using context_id: ${contextId}`);
                     const cachedResult = {
                         success: true,
                         responses: [{
@@ -497,7 +497,7 @@ export class BrutalistServer {
                                 executionTime: 0
                             }]
                     };
-                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, analysisId, explicitPaginationRequested);
+                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, contextId, explicitPaginationRequested);
                 }
             }
             // Build context with custom builder if available
@@ -509,7 +509,7 @@ export class BrutalistServer {
             // Run the analysis
             const result = await this.executeBrutalistAnalysis(config.analysisType, primaryArg, config.systemPrompt, context, args.workingDirectory, args.preferredCLI, args.verbose, args.models, progressToken, sessionId, requestId);
             // Cache the result if successful
-            let analysisId;
+            let contextId;
             if (result.success && result.responses.length > 0) {
                 const fullContent = this.extractFullContent(result);
                 if (fullContent) {
@@ -519,14 +519,14 @@ export class BrutalistServer {
                             acc[field] = args[field];
                         return acc;
                     }, {});
-                    const { analysisId: newId } = await this.responseCache.set(cacheData, fullContent, cacheKey, sessionId, // NEW: Bind to session
-                    requestId // NEW: Track request
+                    const { contextId: newId } = await this.responseCache.set(cacheData, fullContent, cacheKey, sessionId, // Bind to session
+                    requestId // Track request
                     );
-                    analysisId = newId;
-                    logger.info(`✅ Cached analysis result with ID: ${analysisId} for session: ${sessionId?.substring(0, 8)}`);
+                    contextId = newId;
+                    logger.info(`✅ Cached analysis result with context ID: ${contextId} for session: ${sessionId?.substring(0, 8)}`);
                 }
             }
-            return this.formatToolResponse(result, args.verbose, paginationParams, analysisId, explicitPaginationRequested);
+            return this.formatToolResponse(result, args.verbose, paginationParams, contextId, explicitPaginationRequested);
         }
         catch (error) {
             return this.formatErrorResponse(error);
@@ -814,7 +814,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         }
         return null;
     }
-    formatToolResponse(result, verbose = false, paginationParams, analysisId, explicitPaginationRequested = false) {
+    formatToolResponse(result, verbose = false, paginationParams, contextId, explicitPaginationRequested = false) {
         logger.info(`🔧 DEBUG: formatToolResponse called with synthesis length: ${result.synthesis?.length || 0}`);
         logger.info(`🔧 DEBUG: result.success=${result.success}, responses.length=${result.responses?.length || 0}`);
         logger.info(`🔧 DEBUG: pagination params:`, paginationParams);
@@ -836,25 +836,41 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         const estimatedTokens = estimateTokenCount(primaryContent);
         const maxTokensWithoutPagination = 25000;
         const needsAutoPagination = estimatedTokens > maxTokensWithoutPagination;
-        // Apply pagination if:
-        // 1. User explicitly requested it, OR
-        // 2. Content is too large (auto-pagination)
-        if ((explicitPaginationRequested || needsAutoPagination) && paginationParams && primaryContent) {
+        // CRITICAL: Always apply pagination if content is too large, even if not explicitly requested
+        // This prevents MCP protocol errors when response exceeds client token limits
+        if (needsAutoPagination || explicitPaginationRequested) {
             if (needsAutoPagination && !explicitPaginationRequested) {
-                logger.info(`🔧 DEBUG: Auto-applying pagination (${estimatedTokens} tokens > ${maxTokensWithoutPagination} limit)`);
+                logger.info(`🔧 AUTO-PAGINATING: ${estimatedTokens} tokens exceeds ${maxTokensWithoutPagination} limit - forcing first page`);
+                // Force pagination params to show first chunk (use token-based limit)
+                const forcedParams = {
+                    offset: 0,
+                    limit: PAGINATION_DEFAULTS.DEFAULT_LIMIT_TOKENS // Use token-based limit
+                };
+                return this.formatPaginatedResponse(primaryContent, forcedParams, result, verbose, contextId);
             }
-            else {
+            else if (paginationParams) {
                 logger.info(`🔧 DEBUG: Applying pagination (explicitly requested)`);
+                return this.formatPaginatedResponse(primaryContent, paginationParams, result, verbose, contextId);
             }
-            return this.formatPaginatedResponse(primaryContent, paginationParams, result, verbose, analysisId);
         }
         // Non-paginated response (only for content that fits within token limit)
         if (primaryContent) {
             logger.info(`🔧 DEBUG: Returning full response (${estimatedTokens} tokens < ${maxTokensWithoutPagination} limit)`);
+            // Include context_id even for non-paginated responses (for future pagination/caching)
+            let responseText = '';
+            if (contextId) {
+                responseText += `# Brutalist Analysis Results\n\n`;
+                responseText += `**🔑 Context ID:** ${contextId}\n\n`;
+                responseText += `---\n\n`;
+                responseText += primaryContent;
+            }
+            else {
+                responseText = primaryContent;
+            }
             return {
                 content: [{
                         type: "text",
-                        text: primaryContent
+                        text: responseText
                     }]
             };
         }
@@ -880,13 +896,15 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 }]
         };
     }
-    formatPaginatedResponse(content, paginationParams, result, verbose, analysisId) {
+    formatPaginatedResponse(content, paginationParams, result, verbose, contextId) {
         // Using imported pagination utilities
         const offset = paginationParams.offset || 0;
-        const limit = paginationParams.limit || PAGINATION_DEFAULTS.DEFAULT_LIMIT;
-        logger.info(`🔧 DEBUG: Paginating content - offset: ${offset}, limit: ${limit}, total: ${content.length}`);
-        // Use ResponseChunker for intelligent boundary detection
-        const chunker = new ResponseChunker(limit, 200); // 200 char overlap
+        // Convert character-based limit to token-based limit (1 token ≈ 4 chars)
+        const limitChars = paginationParams.limit || PAGINATION_DEFAULTS.DEFAULT_LIMIT;
+        const limitTokens = Math.ceil(limitChars / 4); // Convert chars to tokens
+        logger.info(`🔧 DEBUG: Paginating content - offset: ${offset}, limitChars: ${limitChars}, limitTokens: ${limitTokens}, total: ${content.length} chars`);
+        // Use ResponseChunker for intelligent boundary detection (TOKEN-BASED)
+        const chunker = new ResponseChunker(limitTokens, PAGINATION_DEFAULTS.CHUNK_OVERLAP_TOKENS);
         const chunks = chunker.chunkText(content);
         // Find the appropriate chunk based on offset
         let targetChunk = chunks[0]; // Default to first chunk
@@ -905,7 +923,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         const actualOffset = targetChunk.startOffset;
         const endOffset = targetChunk.endOffset;
         // Create pagination metadata using actual chunk boundaries
-        const pagination = createPaginationMetadata(content.length, paginationParams, limit, chunks, targetChunkIndex);
+        const pagination = createPaginationMetadata(content.length, paginationParams, limitTokens, chunks, targetChunkIndex);
         const statusLine = formatPaginationStatus(pagination);
         // Estimate token usage for user awareness
         const chunkTokens = estimateTokenCount(chunkContent);
@@ -917,20 +935,20 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         // Show pagination metadata
         const needsPagination = pagination.totalChunks > 1 || pagination.hasMore;
         const isFirstRequest = offset === 0;
-        // Always show analysis_id on first request for future pagination
-        if (isFirstRequest && analysisId) {
-            paginatedText += `**🔑 Analysis ID:** ${analysisId}\n`;
+        // Always show context_id on first request for future pagination
+        if (isFirstRequest && contextId) {
+            paginatedText += `**🔑 Context ID:** ${contextId}\n`;
             paginatedText += `**🔢 Token Estimate:** ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
         }
         if (needsPagination) {
             paginatedText += `**📊 Pagination Status:** ${statusLine}\n`;
-            if (!isFirstRequest && analysisId) {
-                paginatedText += `**🔑 Analysis ID:** ${analysisId}\n`;
+            if (!isFirstRequest && contextId) {
+                paginatedText += `**🔑 Context ID:** ${contextId}\n`;
             }
             paginatedText += `**🔢 Token Estimate:** ~${chunkTokens.toLocaleString()} tokens (chunk) / ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
             if (pagination.hasMore) {
-                if (analysisId) {
-                    paginatedText += `**⏭️ Continue Reading:** Use \`analysis_id: "${analysisId}", offset: ${endOffset}\`\n\n`;
+                if (contextId) {
+                    paginatedText += `**⏭️ Continue Reading:** Use \`context_id: "${contextId}", offset: ${endOffset}\`\n\n`;
                 }
                 else {
                     paginatedText += `**⏭️ Continue Reading:** Use \`offset: ${endOffset}\` for next chunk\n\n`;
@@ -945,8 +963,8 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             paginatedText += `\n\n---\n\n`;
             if (pagination.hasMore) {
                 paginatedText += `📖 **End of chunk ${pagination.chunkIndex}/${pagination.totalChunks}**\n`;
-                if (analysisId) {
-                    paginatedText += `🔄 To continue: Include \`analysis_id: "${analysisId}"\` with \`offset: ${endOffset}\` in next request`;
+                if (contextId) {
+                    paginatedText += `🔄 To continue: Include \`context_id: "${contextId}"\` with \`offset: ${endOffset}\` in next request`;
                 }
                 else {
                     paginatedText += `🔄 To continue: Use same tool with \`offset: ${endOffset}\``;