hacktricks-mcp-server 1.3.1 → 1.3.3

package/README.md

@@ -15,27 +15,26 @@ MCP (Model Context Protocol) server for searching and querying [HackTricks](http
 
 ## Setup
 
-### 1. Clone and Initialize
+### Option 1: Install from npm (Recommended)
 
 ```bash
-git clone https://github.com/Xplo8E/hacktricks-mcp-server.git
-cd hacktricks-mcp-server
-git submodule update --init --recursive
-```
-
-### 2. Install Dependencies
+# Install the package
+npm install -g hacktricks-mcp-server
 
-```bash
-bun install
+# The postinstall script will automatically clone HackTricks repository
 ```
 
-### 3. Build
+### Option 2: Install from source
 
 ```bash
-bun run build
+git clone https://github.com/Xplo8E/hacktricks-mcp-server.git
+cd hacktricks-mcp-server
+git submodule update --init --recursive
+npm install
+npm run build
 ```
 
-### 4. Configure Claude
+### Configure Claude
 
 Add to your Claude settings (`~/.claude/settings.json`):
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "hacktricks-mcp-server",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "MCP server for searching HackTricks documentation",
   "main": "dist/index.js",
   "type": "module",
-  "mcpName": "io.github.xplo8e/hacktricks-mcp-server",
+  "mcpName": "io.github.Xplo8E/hacktricks-mcp-server",
   "repository": {
     "type": "git",
     "url": "https://github.com/Xplo8E/hacktricks-mcp-server.git"
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "keywords": [
     "mcp",

package/scripts/postinstall.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { existsSync, rmSync } from 'fs';
+import { execSync } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '..');
+const hacktricksPath = join(rootDir, 'hacktricks');
+
+console.log('📦 Setting up HackTricks MCP Server...');
+
+// Check if hacktricks directory already exists and is valid
+if (existsSync(hacktricksPath)) {
+  // Verify it's a valid git repo with content
+  const gitDir = join(hacktricksPath, '.git');
+  const srcDir = join(hacktricksPath, 'src');
+
+  if (existsSync(gitDir) && existsSync(srcDir)) {
+    console.log('✓ HackTricks repository already exists');
+    process.exit(0);
+  } else {
+    console.log('⚠️  Incomplete HackTricks directory found, removing...');
+    try {
+      rmSync(hacktricksPath, { recursive: true, force: true });
+    } catch (e) {
+      console.error('❌ Could not remove incomplete directory');
+      console.error(`   Please remove manually: ${hacktricksPath}`);
+      process.exit(1);
+    }
+  }
+}
+
+// Check if git is installed
+try {
+  execSync('git --version', { stdio: 'ignore' });
+} catch (error) {
+  console.error('❌ Git is not installed');
+  console.error('   Please install git: https://git-scm.com/downloads');
+  console.error('   Then run: npm rebuild hacktricks-mcp-server');
+  process.exit(0); // Exit 0 to not fail npm install
+}
+
+// Check for SKIP_POSTINSTALL environment variable
+if (process.env.SKIP_POSTINSTALL === 'true') {
+  console.log('ℹ️  Skipping HackTricks clone (SKIP_POSTINSTALL=true)');
+  console.log('   Run manually: git clone https://github.com/carlospolop/hacktricks.git');
+  process.exit(0);
+}
+
+console.log('📥 Cloning HackTricks repository (this may take a minute)...');
+
+try {
+  execSync(
+    'git clone --depth 1 --single-branch https://github.com/carlospolop/hacktricks.git',
+    {
+      cwd: rootDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 120000 // 2 minute timeout
+    }
+  );
+
+  // Verify clone was successful
+  if (existsSync(join(hacktricksPath, 'src'))) {
+    console.log('✓ HackTricks repository cloned successfully');
+    console.log('✓ Setup complete! You can now use the HackTricks MCP server.');
+  } else {
+    throw new Error('Clone incomplete - src directory not found');
+  }
+} catch (error) {
+  console.error('❌ Failed to clone HackTricks repository');
+  console.error(`   Error: ${error.message}`);
+  console.error('');
+  console.error('   Please run manually:');
+  console.error(`   cd ${rootDir}`);
+  console.error('   git clone https://github.com/carlospolop/hacktricks.git');
+  console.error('');
+  console.error('   Or set SKIP_POSTINSTALL=true to skip this step');
+
+  // Clean up partial clone
+  if (existsSync(hacktricksPath)) {
+    try {
+      rmSync(hacktricksPath, { recursive: true, force: true });
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+  }
+
+  process.exit(0); // Exit 0 to not fail npm install
+}

package/.github/workflows/publish-mcp.yml

@@ -1,49 +0,0 @@
-name: Publish to MCP Registry
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write  # Required for OIDC token generation
-      contents: read
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build package
-        run: npm run build
-
-      - name: Publish to npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Download mcp-publisher CLI
-        run: |
-          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz
-          chmod +x mcp-publisher
-
-      - name: Publish to MCP Registry
-        env:
-          ACTIONS_ID_TOKEN_REQUEST_TOKEN: ${{ env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }}
-          ACTIONS_ID_TOKEN_REQUEST_URL: ${{ env.ACTIONS_ID_TOKEN_REQUEST_URL }}
-        run: |
-          ./mcp-publisher publish \
-            --registry-url "https://registry.modelcontextprotocol.io" \
-            --mcp-file "./server.json" \
-            --auth-method github-oidc

package/.github/workflows/test-event.json

@@ -1,9 +0,0 @@
-{
-  "ref": "refs/tags/v1.3.1",
-  "repository": {
-    "name": "hacktricks-mcp-server",
-    "owner": {
-      "name": "Xplo8E"
-    }
-  }
-}

package/.gitmodules

@@ -1,3 +0,0 @@
-[submodule "hacktricks"]
-	path = hacktricks
-	url = https://github.com/carlospolop/hacktricks.git

package/.mcp.json

@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "hacktricks": {
-      "command": "node",
-      "args": [
-        "dist/index.js"
-      ],
-      "env": {}
-    }
-  }
-}

package/CHANGELOG.md

@@ -1,30 +0,0 @@
-# Changelog
-
-## [1.3.0] - 2025-12-26
-
-### Tools
-
-| Tool | Description |
-|------|-------------|
-| `search_hacktricks` | Search with results grouped by file, showing title, match count, and relevant sections |
-| `get_hacktricks_page` | Get full page content |
-| `get_hacktricks_outline` | Get table of contents (section headers) |
-| `get_hacktricks_section` | Extract specific section by name |
-| `get_hacktricks_cheatsheet` | Extract only code blocks/payloads |
-| `list_hacktricks_categories` | Browse categories and file structure |
-| `hacktricks_quick_lookup` | ⚡ One-shot exploitation lookup with alias support |
-
-### Features
-
-- **Grouped search results** - Results aggregated by file with title, match count, sections, and top matches
-- **Section extraction** - Read specific sections (~200 tokens) instead of full pages (~3000 tokens)
-- **Quick lookup** - One-shot "how do I exploit X" answers with alias expansion (sqli, xss, rce, etc.)
-- **Smart tool descriptions** - Guide Claude toward efficient usage patterns
-- **Category filtering** - Narrow searches to specific categories
-- **Code block extraction** - Get just the commands/payloads
-
-### Security
-
-- Command injection protection via `execFile()`
-- Path traversal prevention
-- Input validation on all parameters

package/TESTING.md

@@ -1,188 +0,0 @@
-# Testing the HackTricks MCP Server
-
-This document describes how to test the MCP server functionality.
-
-## Manual Testing
-
-### Prerequisites
-```bash
-cd ~/projects/hacktricks-mcp
-bun install
-bun run build
-```
-
-### Test 1: Verify Build Output
-```bash
-ls -la dist/
-# Should show index.js
-```
-
-### Test 2: Test Search Functionality (CLI)
-```bash
-# Test basic search
-rg -n -i --type md "SUID" hacktricks/ | head -10
-
-# Test regex search
-rg -n -i --type md "docker.*escape" hacktricks/ | head -5
-
-# Test no results
-rg -n -i --type md "xyznotfound12345" hacktricks/
-```
-
-### Test 3: Test File Reading
-```bash
-# Test reading a valid file
-cat hacktricks/src/linux-hardening/privilege-escalation/README.md | head -20
-
-# Test path traversal protection (should fail)
-cat hacktricks/../../../etc/passwd 2>&1
-```
-
-### Test 4: List Categories
-```bash
-ls hacktricks/src/ | grep -v "\.md$" | grep -v "^images$" | sort
-```
-
-## Integration Testing with Claude Code
-
-### 1. Add to Claude Code Settings
-
-Edit `~/.claude/settings.json`:
-```json
-{
-  "mcpServers": {
-    "hacktricks": {
-      "command": "node",
-      "args": ["/Users/vinay/projects/hacktricks-mcp/dist/index.js"],
-      "disabled": false
-    }
-  }
-}
-```
-
-### 2. Restart Claude Code
-
-### 3. Test Commands
-
-Try these queries with Claude Code:
-
-**Search Test:**
-```
-"Search HackTricks for SUID privilege escalation"
-```
-
-**Category List Test:**
-```
-"What categories are available in HackTricks?"
-```
-
-**Page Retrieval Test:**
-```
-"Show me the Linux privilege escalation page from HackTricks"
-```
-
-**Edge Cases:**
-```
-"Search HackTricks for: XXE|SSRF|CSRF"  # Regex test
-"Search HackTricks for: docker.*escape"  # Regex test
-```
-
-## Expected Results
-
-### Search Results Format
-```
-Found X matches for: "query"
-
-📄 path/to/file.md:123
-Content of matching line
-
-📄 path/to/another.md:456
-Another matching line
-```
-
-### Category List Format
-```
-Available HackTricks Categories (X):
-
-- AI
-- binary-exploitation
-- crypto
-- linux-hardening
-...
-```
-
-### Page Content Format
-```
-[Full markdown content of the page]
-```
-
-## Debugging
-
-Check MCP server logs in Claude Code console:
-```
-[HackTricks MCP] Searching for: "query"
-[HackTricks MCP] Found X results (showing Y)
-[HackTricks MCP] Reading file: path/to/file.md
-[HackTricks MCP] File size: XXXX bytes
-```
-
-## Error Testing
-
-### Test Empty Query
-```
-search_hacktricks("")
-# Expected: "Search query cannot be empty"
-```
-
-### Test Invalid Path
-```
-get_hacktricks_page("../../../etc/passwd")
-# Expected: "Invalid file path: directory traversal not allowed"
-```
-
-### Test Non-existent File
-```
-get_hacktricks_page("src/nonexistent.md")
-# Expected: "File not found: src/nonexistent.md"
-```
-
-### Test Invalid Regex
-```
-search_hacktricks("[[invalid")
-# Expected: "Invalid search pattern: ..."
-```
-
-## Performance Testing
-
-### Large Query Results
-```bash
-# Search for common term
-rg -n -i --type md "privilege" hacktricks/ | wc -l
-# Should handle large result sets (limited to 50)
-```
-
-### File Size Limits
-```bash
-# Find largest markdown file
-find hacktricks/src -name "*.md" -type f -exec du -h {} + | sort -rh | head -5
-# Ensure server can handle large files
-```
-
-## Security Testing
-
-### Command Injection Prevention
-Test that special characters in queries don't execute commands:
-```
-search_hacktricks("test; ls -la")
-search_hacktricks("test && whoami")
-search_hacktricks("test $(whoami)")
-```
-All should search for the literal strings, not execute commands.
-
-### Path Traversal Prevention
-```
-get_hacktricks_page("../../../etc/passwd")
-get_hacktricks_page("/etc/passwd")
-get_hacktricks_page("src/../../..")
-```
-All should be rejected with appropriate error messages.