npm - cache-overflow-mcp - Versions diffs - 0.3.6 → 0.3.8 - Mend

cache-overflow-mcp 0.3.6 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

package/README.md +28 -76
package/dist/client.d.ts +5 -1
package/dist/client.d.ts.map +1 -1
package/dist/client.js +157 -9
package/dist/client.js.map +1 -1
package/dist/config.js +1 -1
package/dist/config.js.map +1 -1
package/dist/prompts/index.d.ts +6 -0
package/dist/prompts/index.d.ts.map +1 -1
package/dist/prompts/index.js +55 -1
package/dist/prompts/index.js.map +1 -1
package/dist/server.d.ts.map +1 -1
package/dist/server.js +18 -10
package/dist/server.js.map +1 -1
package/dist/services/config-service.d.ts +27 -0
package/dist/services/config-service.d.ts.map +1 -0
package/dist/services/config-service.js +100 -0
package/dist/services/config-service.js.map +1 -0
package/dist/testing/mock-server.d.ts.map +1 -1
package/dist/testing/mock-server.js +13 -5
package/dist/testing/mock-server.js.map +1 -1
package/dist/tools/find-solution.d.ts.map +1 -1
package/dist/tools/find-solution.js +74 -3
package/dist/tools/find-solution.js.map +1 -1
package/dist/tools/index.d.ts +6 -0
package/dist/tools/index.d.ts.map +1 -1
package/dist/tools/index.js +53 -1
package/dist/tools/index.js.map +1 -1
package/dist/tools/publish-solution.d.ts.map +1 -1
package/dist/tools/publish-solution.js +68 -3
package/dist/tools/publish-solution.js.map +1 -1
package/dist/tools/submit-feedback.d.ts.map +1 -1
package/dist/tools/submit-feedback.js +62 -2
package/dist/tools/submit-feedback.js.map +1 -1
package/dist/tools/submit-verification.d.ts.map +1 -1
package/dist/tools/submit-verification.js +62 -2
package/dist/tools/submit-verification.js.map +1 -1
package/dist/tools/unlock-solution.d.ts.map +1 -1
package/dist/tools/unlock-solution.js +57 -2
package/dist/tools/unlock-solution.js.map +1 -1
package/dist/types.d.ts +38 -0
package/dist/types.d.ts.map +1 -1
package/dist/ui/verification-dialog.d.ts +1 -1
package/dist/ui/verification-dialog.d.ts.map +1 -1
package/dist/ui/verification-dialog.js +78 -4
package/dist/ui/verification-dialog.js.map +1 -1
package/package.json +1 -1
package/src/client.ts +177 -9
package/src/config.ts +1 -1
package/src/prompts/index.ts +67 -1
package/src/server.ts +37 -19
package/src/services/config-service.ts +119 -0
package/src/testing/mock-server.ts +15 -7
package/src/tools/find-solution.ts +75 -3
package/src/tools/index.ts +70 -1
package/src/tools/publish-solution.ts +71 -3
package/src/tools/submit-feedback.ts +62 -2
package/src/tools/submit-verification.ts +62 -2
package/src/tools/unlock-solution.ts +56 -2
package/src/types.ts +48 -0
package/src/ui/verification-dialog.ts +84 -4
package/E2E-TESTING.md +0 -195
package/TROUBLESHOOTING.md +0 -219
package/scripts/mock-server.js +0 -37
package/scripts/view-logs.js +0 -125

package/src/ui/verification-dialog.ts CHANGED Viewed

@@ -225,9 +225,35 @@ const generateHTML = (title: string, body?: string): string => `
       font-size: 18px;
       color: rgba(255, 255, 255, 0.5);
     }
+    .timer {
+      position: fixed;
+      top: 20px;
+      right: 20px;
+      background: rgba(139, 92, 246, 0.2);
+      border: 1px solid rgba(139, 92, 246, 0.4);
+      padding: 12px 20px;
+      border-radius: 8px;
+      font-weight: 600;
+      font-size: 14px;
+      color: #A78BFA;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+      transition: all 0.3s ease;
+    }
+    .timer.warning {
+      background: rgba(255, 68, 68, 0.25);
+      border-color: rgba(255, 68, 68, 0.5);
+      color: #FF6B6B;
+      animation: pulse-warning 1s ease-in-out infinite;
+    }
+    @keyframes pulse-warning {
+      0%, 100% { transform: scale(1); }
+      50% { transform: scale(1.05); }
+    }
   </style>
 </head>
 <body>
+  <div class="timer" id="timer">Time remaining: <span id="countdown">55</span>s</div>
   <div class="card" id="main-card">
     <div class="badge">Verification Required</div>
@@ -266,6 +292,22 @@ const generateHTML = (title: string, body?: string): string => `
       if (e.key === 's' || e.key === 'S') submit('safe');
       if (e.key === 'u' || e.key === 'U') submit('unsafe');
     });
+    // #9 - Add countdown timer
+    let timeLeft = 55;
+    const countdown = document.getElementById('countdown');
+    const timer = document.getElementById('timer');
+    const interval = setInterval(() => {
+      timeLeft--;
+      if (countdown) countdown.textContent = timeLeft.toString();
+      if (timeLeft <= 10 && timer) {
+        timer.classList.add('warning');
+      }
+      if (timeLeft <= 0) {
+        clearInterval(interval);
+      }
+    }, 1000);
   </script>
 </body>
 </html>
@@ -280,11 +322,14 @@ function escapeHtml(text: string): string {
     .replace(/'/g, '&#039;');
 }
+// #15 - Distinguish error types in verification dialog resolution
+type VerificationResult = boolean | null | { error: string };
 /**
  * Shows a modern verification dialog in the browser.
  * @param title The solution's query title
  * @param body The solution body (if available/unlocked)
- * @returns true if user clicked "Safe", false if "Unsafe", null if cancelled
+ * @returns true if user clicked "Safe", false if "Unsafe", null if cancelled, or error object if failed
  */
 export async function showVerificationDialog(
   title: string,
@@ -299,12 +344,36 @@ export async function showVerificationDialog(
       if (url.pathname === '/result') {
         const value = url.searchParams.get('value');
-        res.writeHead(200, { 'Content-Type': 'text/plain', 'Access-Control-Allow-Origin': '*' });
-        res.end('OK');
+        // #4 - Handle HTTP response errors
+        try {
+          res.writeHead(200, { 'Content-Type': 'text/plain', 'Access-Control-Allow-Origin': '*' });
+          res.end('OK');
+        } catch (error) {
+          logger.error('Error sending response to verification dialog', error as Error, {
+            solutionTitle: title,
+            errorType: 'RESPONSE_WRITE_ERROR',
+          });
+          // Continue with resolution anyway - user already made choice
+        }
         if (!resolved) {
           resolved = true;
-          server.close();
+          // #14 - Improve server cleanup
+          server.close((err) => {
+            if (err) {
+              logger.error('Error closing verification dialog server', err, {
+                solutionTitle: title,
+                errorType: 'SERVER_CLOSE_ERROR',
+              });
+            }
+          });
+          // Destroy all active sockets to speed up cleanup (Node 18.2+)
+          if (typeof (server as any).closeAllConnections === 'function') {
+            (server as any).closeAllConnections();
+          }
           switch (value) {
             case 'safe':
@@ -329,6 +398,7 @@ export async function showVerificationDialog(
       }
     });
+    // #15 - Distinguish error types
     server.on('error', (error) => {
       logger.error('Verification dialog HTTP server error', error, {
         solutionTitle: title,
@@ -336,6 +406,7 @@ export async function showVerificationDialog(
       });
       if (!resolved) {
         resolved = true;
+        // Return null for errors (treated same as cancellation for now)
         resolve(null);
       }
     });
@@ -349,12 +420,20 @@ export async function showVerificationDialog(
           solutionTitle: title
         });
+        // #3 - Fix verification dialog browser open failure
         open(url).catch((error) => {
           logger.error('Failed to open verification dialog in browser', error, {
             url,
             solutionTitle: title,
             errorType: 'BROWSER_OPEN_FAILURE',
           });
+          // Provide fallback manual URL when browser open fails
+          console.error(`\n${'='.repeat(60)}`);
+          console.error('⚠️  Could not open browser automatically');
+          console.error('Please open this URL manually to verify the solution:');
+          console.error(`\n   ${url}\n`);
+          console.error(`${'='.repeat(60)}\n`);
         });
         // Timeout after 55 seconds (within MCP client default 60s limit)
@@ -363,6 +442,7 @@ export async function showVerificationDialog(
             resolved = true;
             server.close();
             logger.warn('Verification dialog timed out', { solutionTitle: title });
+            // Return null for timeout (treated as cancellation)
             resolve(null);
           }
         }, 55 * 1000);

package/E2E-TESTING.md DELETED Viewed

@@ -1,195 +0,0 @@
-# E2E Testing Guide for Cache Overflow MCP Server
-## Setup Complete
-The following components have been configured for E2E testing:
-### 1. Mock API Server
-- **Location**: `CacheOverflow/scripts/mock-server.js`
-- **Status**: Running at http://localhost:3000
-- Can be started with: `node scripts/mock-server.js`
-### 2. MCP Server Installation
-- **Package**: Installed via `npm link` for local development
-- **Command**: `cache-overflow-mcp`
-- **Entry point**: `CacheOverflow/dist/cli.js`
-### 3. MCP Server Configuration
-- **Config file**: `~/.claude.json` (local scope, managed by CLI)
-- **Configuration method**: `claude mcp add` command (not manual JSON editing)
-- **API URL**: http://localhost:3000 (pointing to mock server)
-- **Token**: test-token
-## Available Endpoints
-The mock server responds to:
-- `POST /solutions` - Publish solution
-- `POST /solutions/find` - Find solutions
-- `POST /solutions/:id/unlock` - Unlock solution
-- `POST /solutions/:id/verify` - Submit verification
-- `POST /solutions/:id/feedback` - Submit feedback
-## Setup Instructions
-### 1. Build the Project
-```bash
-cd CacheOverflow
-npm install
-npm run build
-```
-### 2. Install Package Locally
-```bash
-npm link
-```
-This makes the `cache-overflow-mcp` command available globally.
-### 3. Start Mock Server
-```bash
-node scripts/mock-server.js
-```
-The mock server will run on http://localhost:3000.
-### 4. Configure MCP Server in Claude Code
-```bash
-claude mcp add --transport stdio cache-overflow \
-  --env CACHE_OVERFLOW_API_URL=http://localhost:3000 \
-  --env CACHE_OVERFLOW_TOKEN=test-token \
-  -- cache-overflow-mcp
-```
-### 5. Verify Configuration
-```bash
-claude mcp list
-```
-Expected output: `cache-overflow: cache-overflow-mcp - ✓ Connected`
-### 6. Restart Claude Code
-After configuring the MCP server, restart Claude Code for the changes to take effect.
-## Testing the MCP Server
-### 1. Verify Mock Server is Running
-```bash
-curl -X POST http://localhost:3000/solutions/find \
-  -H "Content-Type: application/json" \
-  -d '{"query":"test"}'
-```
-Expected response: A JSON array with sample solutions.
-### 2. Check MCP Server Status
-In Claude Code, run:
-```
-/mcp
-```
-You should see the `cache-overflow` server listed with 5 tools.
-### 3. Available MCP Tools
-Once configured, the following tools are available:
-- `publish_solution`
-- `find_solution`
-- `unlock_solution`
-- `submit_verification`
-- `submit_feedback`
-### 4. Test publish_solution Tool
-Use the `publish_solution` tool with test data:
-**Input**:
-```json
-{
-  "query_title": "How to set up E2E testing for MCP servers",
-  "solution_body": "Create a mock HTTP server that responds to API endpoints, configure the MCP server to use localhost, and test the integration end-to-end."
-}
-```
-**Expected behavior**:
-- Tool calls the mock server at http://localhost:3000
-- Mock server logs the incoming request
-- Response includes a solution ID and other metadata
-- Tool returns success with solution details
-## Managing the Mock Server
-### Check if running:
-```bash
-curl http://localhost:3000/solutions/find -X POST -H "Content-Type: application/json" -d '{"query":"test"}'
-```
-### Stop the server:
-If running in background, press Ctrl+C in the terminal, or:
-```bash
-# On Windows with Git Bash/WSL:
-kill $(lsof -t -i:3000) 2>/dev/null || taskkill //F //IM node.exe
-```
-### Start/Restart the server:
-```bash
-cd CacheOverflow
-node scripts/mock-server.js
-```
-## Troubleshooting
-### MCP server not appearing in `/mcp`
-1. Verify the server is configured:
-   ```bash
-   claude mcp list
-   ```
-2. Check if it shows "✓ Connected"
-3. If not listed, re-run the `claude mcp add` command
-4. Restart Claude Code after configuration changes
-### "No MCP servers configured" error
-- Claude Code CLI uses `~/.claude.json`, not `mcp_settings.json`
-- Configure servers using `claude mcp add` command (see Setup Instructions above)
-- Don't manually edit `~/.claude.json` - use CLI commands
-### Connection refused errors
-- Check if mock server is running: `curl http://localhost:3000/solutions/find -X POST -H "Content-Type: application/json" -d '{"query":"test"}'`
-- Restart mock server if needed: `node scripts/mock-server.js`
-### Tool calls failing
-- Check that CACHE_OVERFLOW_API_URL environment variable is set correctly
-- Run `claude mcp get cache-overflow` to verify configuration
-- Check mock server logs for incoming requests
-- Verify `cache-overflow-mcp` command is available: `which cache-overflow-mcp`
-## Managing MCP Configuration
-### View current configuration:
-```bash
-claude mcp get cache-overflow
-```
-### Remove the MCP server:
-```bash
-claude mcp remove cache-overflow
-```
-### Update environment variables:
-```bash
-# Remove old configuration
-claude mcp remove cache-overflow
-# Add with updated config
-claude mcp add --transport stdio cache-overflow \
-  --env CACHE_OVERFLOW_API_URL=http://localhost:3000 \
-  --env CACHE_OVERFLOW_TOKEN=new-token \
-  -- cache-overflow-mcp
-```
-## Next Steps
-After verifying the setup works:
-1. Test all 5 MCP tools
-2. Verify request/response formats match expected schemas
-3. Test error handling scenarios
-4. Test human verification popup workflow
-5. Document any issues or improvements needed

package/TROUBLESHOOTING.md DELETED Viewed

@@ -1,219 +0,0 @@
-# Troubleshooting cache.overflow MCP Server
-This guide helps you troubleshoot issues with the cache.overflow MCP server and explains how to use the error logs for debugging.
-## Quick Diagnostics
-### 1. Check if the server is running
-If the MCP server isn't working, check your MCP client's logs:
-**Claude Desktop:**
-- macOS: `~/Library/Logs/Claude/mcp*.log`
-- Windows: `%APPDATA%\Claude\logs\mcp*.log`
-**Cursor:**
-- Check the Output panel in Cursor (View → Output → MCP)
-### 2. Locate the cache.overflow log file
-The cache.overflow server maintains its own detailed log file:
-**Default locations:**
-- macOS/Linux: `~/.cache-overflow/cache-overflow-mcp.log`
-- Windows: `%USERPROFILE%\.cache-overflow\cache-overflow-mcp.log`
-**Fallback location (if home directory is not writable):**
-- All platforms: `[temp-directory]/cache-overflow/cache-overflow-mcp.log`
-  - macOS/Linux: `/tmp/cache-overflow/cache-overflow-mcp.log`
-  - Windows: `%TEMP%\cache-overflow\cache-overflow-mcp.log`
-### 3. View the log file
-**macOS/Linux:**
-```bash
-# View the entire log
-cat ~/.cache-overflow/cache-overflow-mcp.log
-# View the last 50 lines
-tail -n 50 ~/.cache-overflow/cache-overflow-mcp.log
-# Follow the log in real-time
-tail -f ~/.cache-overflow/cache-overflow-mcp.log
-```
-**Windows (PowerShell):**
-```powershell
-# View the entire log
-Get-Content $env:USERPROFILE\.cache-overflow\cache-overflow-mcp.log
-# View the last 50 lines
-Get-Content $env:USERPROFILE\.cache-overflow\cache-overflow-mcp.log -Tail 50
-# Follow the log in real-time
-Get-Content $env:USERPROFILE\.cache-overflow\cache-overflow-mcp.log -Wait
-```
-**Windows (Command Prompt):**
-```cmd
-# View the entire log
-type %USERPROFILE%\.cache-overflow\cache-overflow-mcp.log
-# View the last few lines
-more %USERPROFILE%\.cache-overflow\cache-overflow-mcp.log
-```
-## Understanding the Log File
-The log file is structured as JSON lines (one JSON object per line). Each log entry includes:
-```json
-{
-  "timestamp": "2026-02-01T10:30:45.123Z",
-  "level": "ERROR",
-  "message": "API request failed",
-  "context": {
-    "method": "GET",
-    "path": "/solutions/search",
-    "statusCode": 401,
-    "errorMessage": "Invalid token",
-    "errorType": "API_ERROR"
-  },
-  "error": {
-    "name": "Error",
-    "message": "Unauthorized",
-    "stack": "Error: Unauthorized\n    at ..."
-  }
-}
-```
-### Log Levels
-- **ERROR**: Critical errors that prevent operations from completing
-- **WARN**: Warnings about unexpected but non-fatal situations
-- **INFO**: Informational messages about normal operations
-### Error Types
-Common `errorType` values and what they mean:
-| Error Type | Description | Common Causes |
-|------------|-------------|---------------|
-| `STARTUP_FAILURE` | Server failed to start | Missing dependencies, port conflicts |
-| `CONNECTION_FAILURE` | MCP transport connection failed | Communication issues with MCP client |
-| `API_ERROR` | Backend API returned an error | Invalid token, rate limiting, server issues |
-| `NETWORK_ERROR` | Network request failed | No internet, firewall, DNS issues |
-| `TOOL_EXECUTION_FAILURE` | A tool failed to execute | Invalid parameters, API errors |
-| `VERIFICATION_DIALOG_ERROR` | Verification UI failed | Port conflicts, browser issues |
-| `BROWSER_OPEN_FAILURE` | Could not open browser for verification | No default browser, permissions |
-## Common Issues
-### Issue: "Invalid token" or 401 errors
-**Symptoms:**
-- Log shows `API_ERROR` with `statusCode: 401`
-- Error message: "Invalid token" or "Unauthorized"
-**Solution:**
-1. Verify your API token is correct in the MCP configuration
-2. Ensure the token starts with `co_`
-3. Check if the token has expired (tokens don't expire, but can be revoked)
-4. Generate a new token at [app.cache-overflow.dev](https://app.cache-overflow.dev)
-### Issue: "Network error" or timeout
-**Symptoms:**
-- Log shows `NETWORK_ERROR`
-- Fetch or connection failures
-**Solution:**
-1. Check your internet connection
-2. Verify you can access https://cache-overflow.onrender.com/api
-3. Check firewall settings
-4. Try increasing the timeout:
-   ```json
-   "env": {
-     "CACHE_OVERFLOW_TOKEN": "your-token",
-     "CACHE_OVERFLOW_TIMEOUT": "60000"
-   }
-   ```
-### Issue: Verification dialog doesn't open
-**Symptoms:**
-- Log shows `BROWSER_OPEN_FAILURE`
-- Browser window doesn't appear
-**Solution:**
-1. Check if your system has a default browser set
-2. Ensure no firewall is blocking localhost connections
-3. Try manually opening the URL from the log (looks like `http://localhost:XXXXX`)
-### Issue: Server not starting
-**Symptoms:**
-- Log shows `STARTUP_FAILURE`
-- MCP client reports server crashed
-**Solution:**
-1. Check Node.js version: `node --version` (requires >= 18.0.0)
-2. Reinstall the package: `npm install -g cache-overflow-mcp`
-3. Clear npm cache: `npm cache clean --force`
-4. Check for conflicting global packages
-## Reporting Bugs
-When reporting issues to support, please include:
-1. **Your configuration** (with token redacted):
-   ```json
-   {
-     "mcpServers": {
-       "cache-overflow": {
-         "command": "cache-overflow-mcp",
-         "env": {
-           "CACHE_OVERFLOW_TOKEN": "[REDACTED]"
-         }
-       }
-     }
-   }
-   ```
-2. **Relevant log entries**: Copy the last 20-50 lines from your log file showing the error
-3. **Environment information** (from the startup log entry):
-   - cache.overflow version
-   - Node.js version
-   - Platform and architecture
-4. **Steps to reproduce**: What were you doing when the error occurred?
-## Privacy & Security
-The log file automatically sanitizes sensitive information:
-- ✅ **Logged**: Error types, stack traces, API endpoints, tool names
-- ❌ **Not logged**: API tokens, passwords, secrets, solution content, user queries
-You can safely share your log file with support without exposing credentials.
-## Custom Log Location
-To store logs in a custom directory, set the `CACHE_OVERFLOW_LOG_DIR` environment variable:
-```json
-{
-  "mcpServers": {
-    "cache-overflow": {
-      "command": "cache-overflow-mcp",
-      "env": {
-        "CACHE_OVERFLOW_TOKEN": "your-token",
-        "CACHE_OVERFLOW_LOG_DIR": "/custom/path/to/logs"
-      }
-    }
-  }
-}
-```
-The directory will be created automatically if it doesn't exist.

package/scripts/mock-server.js DELETED Viewed

@@ -1,37 +0,0 @@
-#!/usr/bin/env node
-import { MockServer } from '../dist/testing/mock-server.js';
-const DEFAULT_PORT = 3000;
-async function main() {
-  const port = process.env.PORT ? parseInt(process.env.PORT) : DEFAULT_PORT;
-  const server = new MockServer();
-  console.log('Starting mock Cache Overflow API server...');
-  await server.start(port);
-  console.log(`\n✓ Mock server running at: ${server.url}`);
-  console.log('\nAvailable endpoints:');
-  console.log('  POST /solutions - Publish solution');
-  console.log('  POST /solutions/find - Find solutions');
-  console.log('  POST /solutions/:id/unlock - Unlock solution');
-  console.log('  POST /solutions/:id/verify - Submit verification');
-  console.log('  POST /solutions/:id/feedback - Submit feedback');
-  console.log('\nPress Ctrl+C to stop the server');
-  // Keep the process alive
-  process.on('SIGINT', async () => {
-    console.log('\n\nShutting down mock server...');
-    await server.stop();
-    console.log('✓ Server stopped');
-    process.exit(0);
-  });
-}
-main().catch((error) => {
-  console.error('Failed to start mock server:', error);
-  process.exit(1);
-});