leolech14/PROJECT_sniper-mcp-server

🎯 Multi-Indexer Sniper Tagger Query Gun - MCP Server

Transform 10,465-line monoliths into semantically-navigable, surgically-editable organisms

🚀 Cloud Hosting Options (24/7 FREE)

1. Google Cloud App Engine ⭐ RECOMMENDED

• Free Tier: F1 instance (28 hours/month free)
• Uptime: 99.95% with automatic scaling
• Deploy: ./deploy.sh (auto-detects GCP)
• URL: https://your-project.appspot.com

2. Railway 🚂

• Free Tier: $5/month credit (enough for 24/7)
• Deploy: railway up after npm install -g @railway/cli
• Features: Automatic GitHub deployment

3. Render 🌐

• Free Tier: 750 hours/month (enough for 24/7)
• Deploy: Connect GitHub repo to render.com
• Features: Zero-config deployment

4. Vercel ⚡

• Free Tier: Serverless functions
• Deploy: vercel --prod
• Best for: Serverless MCP functions

🔧 MCP Tools Available

🔍 scan_components

Auto-scan and index all HTML components in Python scripts

{
  "tool": "scan_components",
  "arguments": {
    "script_path": "mr-fix-my-project-please.py",
    "target_dir": "."
  }
}

🎯 query_components

Query components using semantic tags

{
  "tool": "query_components",
  "arguments": {
    "query": "@html:form AND @component:modal OR @layer:overlay"
  }
}

⚡ sniper_edit

Apply surgical edits to specific line ranges

{
  "tool": "sniper_edit",
  "arguments": {
    "target_file": "script.py",
    "line_ranges": [[100, 150], [200, 250]],
    "edit_operation": "replace",
    "new_content": "new HTML code here"
  }
}

📊 impact_analysis

Analyze impact before applying changes

{
  "tool": "impact_analysis",
  "arguments": {
    "target_file": "script.py",
    "proposed_edits": [
      {"type": "method_removal", "target": "_generate_form_html"}
    ]
  }
}

📦 extract_component

Extract component to separate file

{
  "tool": "extract_component",
  "arguments": {
    "component_id": "form_component_1",
    "target_file": "script.py",
    "new_file_path": "components/form.py"
  }
}

📋 get_registry

Get complete task registry

{
  "tool": "get_registry",
  "arguments": {
    "include_completed": false
  }
}

🛠️ Quick Start

1. Install Dependencies

npm install

2. Build Server

npm run build

3. Deploy to Cloud (Free 24/7)

./deploy.sh

4. Test Local Development

npm run dev

🎯 Usage Example

import { SniperGunMCPServer } from './dist/index.js';

// Server provides 6 MCP tools via stdio transport
// Connect from any MCP client (Claude Code, etc.)

// Example workflow:
// 1. Scan components in large Python file
// 2. Query specific HTML patterns (@html:form, @component:modal)
// 3. Analyze impact of proposed changes
// 4. Apply surgical edits to precise line ranges
// 5. Extract components to separate files

📊 Architecture

🎯 Sniper Gun MCP Server
├── 🔍 HTML Component Scanner (Python)
├── 🏷️ Semantic Tagger (Python)
├── 🎯 Query Engine (TypeScript)
├── ⚡ Surgical Editor (TypeScript)
├── 📊 Impact Analyzer (TypeScript)
└── 📦 Component Extractor (TypeScript)

🌐 Semantic Query Language

• @html:form - Find HTML form components
• @component:modal - Find modal components
• @layer:overlay - Find overlay layers
• @method:_generate_* - Find generator methods
• @editable:true - Find editable components
• @complexity:high - Find complex components

Combine with operators:

• AND - Intersection
• OR - Union
• NOT - Exclusion

Example: @html:form AND @component:modal NOT @deprecated:true

💡 Use Cases

1. Legacy Code Refactoring: Navigate 10,465-line monoliths with semantic precision
2. Component Extraction: surgically extract reusable components
3. Impact Analysis: Understand changes before breaking anything
4. Query-Driven Development: Find and edit components by semantic meaning
5. Automated Refactoring: Batch operations on similar components

📈 Performance

• Scan Speed: 10,465 lines in ~2 seconds
• Query Response: <100ms for most queries
• Memory Usage: <50MB for large codebases
• Accuracy: 95%+ component identification

🔐 Security

• No hardcoded API keys (uses Doppler)
• Read-only file operations by default
• Impact analysis before destructive changes
• Audit trail for all operations

🎯 Transform monolithic pain into surgical precision with the Multi-Indexer Sniper Tagger Query Gun!