@ayazdata/trace-mcp 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# Trace MCP Server
+
+Connect Claude Code, Codex, and Gemini to [Trace](https://trace.akpinar.dev) malware analysis platform.
+
+## Install — Claude Code
+
+```bash
+claude mcp add trace \
+  -e TRACE_URL=https://trace.akpinar.dev \
+  -e TRACE_TOKEN=your_token_here \
+  -- npx -y trace-mcp
+```
+
+Or for the public instance (no token required):
+```bash
+claude mcp add trace -e TRACE_URL=https://trace.akpinar.dev -- npx -y trace-mcp
+```
+
+## Install — Codex CLI
+
+Add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.trace]
+command = "npx"
+args = ["-y", "trace-mcp"]
+startup_timeout_sec = 15
+
+[mcp_servers.trace.env]
+TRACE_URL = "https://trace.akpinar.dev"
+TRACE_TOKEN = ""
+```
+
+## Install — Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "trace": {
+      "command": "npx",
+      "args": ["-y", "trace-mcp"],
+      "env": {
+        "TRACE_URL": "https://trace.akpinar.dev",
+        "TRACE_TOKEN": ""
+      }
+    }
+  }
+}
+```
+
+## Self-hosted
+
+Replace `https://trace.akpinar.dev` with your own instance URL.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `trace_upload_file` | Upload file for malware analysis |
+| `trace_get_analysis` | Full analysis results (risk score, YARA, MITRE, IOCs) |
+| `trace_list_analyses` | List recent analyses |
+| `trace_get_iocs` | Extract IOCs from analysis |
+| `trace_get_sigma_matches` | Sigma rule matches |
+| `trace_get_ai_summary` | AI-generated threat summary |
+| `trace_lookup_hash` | SHA256 threat intel lookup |
+| `trace_dashboard_stats` | Dashboard statistics |
+| `trace_get_mitre` | Top MITRE ATT&CK techniques |
+| `trace_get_process_tree` | Process execution tree |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TRACE_URL` | `http://localhost:8090` | Trace instance URL |
+| `TRACE_TOKEN` | _(empty)_ | JWT token for authenticated endpoints |

package/dist/index.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync, existsSync } from "fs";
+const BASE_URL = process.env.TRACE_URL ?? "http://localhost";
+const API_TOKEN = process.env.TRACE_TOKEN ?? "";
+async function traceGet(path) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        headers: API_TOKEN ? { Authorization: `Bearer ${API_TOKEN}` } : {},
+    });
+    if (!res.ok)
+        throw new Error(`${res.status} ${res.statusText}: ${path}`);
+    return res.json();
+}
+async function tracePost(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...(API_TOKEN ? { Authorization: `Bearer ${API_TOKEN}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`${res.status} ${res.statusText}: ${path}`);
+    return res.json();
+}
+async function uploadFile(filePath) {
+    if (!existsSync(filePath))
+        throw new Error(`File not found: ${filePath}`);
+    const fileBuffer = readFileSync(filePath);
+    const fileName = filePath.split("/").pop();
+    const formData = new FormData();
+    formData.append("file", new Blob([fileBuffer]), fileName);
+    const res = await fetch(`${BASE_URL}/api/v1/upload/`, {
+        method: "POST",
+        headers: API_TOKEN ? { Authorization: `Bearer ${API_TOKEN}` } : {},
+        body: formData,
+    });
+    if (!res.ok)
+        throw new Error(`Upload failed: ${res.status}`);
+    return res.json();
+}
+const server = new Server({ name: "trace-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "trace_upload_file",
+            description: "Upload a local file to Trace for malware analysis. Returns analysis_id to track progress.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file_path: { type: "string", description: "Absolute path to the file to analyze" },
+                },
+                required: ["file_path"],
+            },
+        },
+        {
+            name: "trace_get_analysis",
+            description: "Get full analysis results for a given analysis ID. Includes risk score, YARA matches, MITRE techniques, IOCs, AI summary.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    analysis_id: { type: "string", description: "UUID of the analysis" },
+                },
+                required: ["analysis_id"],
+            },
+        },
+        {
+            name: "trace_list_analyses",
+            description: "List recent analyses with status and risk levels.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: { type: "number", description: "Max results (default 20)" },
+                    risk_level: { type: "string", enum: ["critical", "high", "medium", "low", "clean"], description: "Filter by risk level" },
+                    status: { type: "string", enum: ["pending", "running", "completed", "failed"], description: "Filter by status" },
+                },
+            },
+        },
+        {
+            name: "trace_get_iocs",
+            description: "Extract Indicators of Compromise (IPs, domains, hashes, URLs, registry keys) from an analysis.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    analysis_id: { type: "string", description: "UUID of the analysis" },
+                },
+                required: ["analysis_id"],
+            },
+        },
+        {
+            name: "trace_get_sigma_matches",
+            description: "Get Sigma rule matches from an analysis. Shows which detection rules triggered.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    analysis_id: { type: "string", description: "UUID of the analysis" },
+                },
+                required: ["analysis_id"],
+            },
+        },
+        {
+            name: "trace_get_ai_summary",
+            description: "Get AI-generated threat summary for an analysis.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    analysis_id: { type: "string", description: "UUID of the analysis" },
+                },
+                required: ["analysis_id"],
+            },
+        },
+        {
+            name: "trace_lookup_hash",
+            description: "Look up a SHA256 hash in threat intelligence (VirusTotal, internal DB).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sha256: { type: "string", description: "SHA256 hash to look up" },
+                },
+                required: ["sha256"],
+            },
+        },
+        {
+            name: "trace_dashboard_stats",
+            description: "Get dashboard statistics: total analyses, risk distribution, detection rates.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "trace_get_mitre",
+            description: "Get top MITRE ATT&CK techniques observed across all analyses.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: { type: "number", description: "Number of techniques to return (default 10)" },
+                },
+            },
+        },
+        {
+            name: "trace_get_process_tree",
+            description: "Get the process execution tree from a dynamic analysis.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    analysis_id: { type: "string", description: "UUID of the analysis" },
+                },
+                required: ["analysis_id"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case "trace_upload_file":
+                result = await uploadFile(args.file_path);
+                break;
+            case "trace_get_analysis":
+                result = await traceGet(`/api/v1/analysis/${args.analysis_id}`);
+                break;
+            case "trace_list_analyses": {
+                const params = new URLSearchParams();
+                if (args?.limit)
+                    params.set("limit", String(args.limit));
+                if (args?.risk_level)
+                    params.set("risk_level", args.risk_level);
+                if (args?.status)
+                    params.set("status", args.status);
+                result = await traceGet(`/api/v1/analysis/?${params}`);
+                break;
+            }
+            case "trace_get_iocs":
+                result = await traceGet(`/api/v1/analysis/${args.analysis_id}/iocs`);
+                break;
+            case "trace_get_sigma_matches":
+                result = await traceGet(`/api/v1/analysis/${args.analysis_id}/sigma`);
+                break;
+            case "trace_get_ai_summary":
+                result = await traceGet(`/api/v1/analysis/${args.analysis_id}/ai-summary`);
+                break;
+            case "trace_lookup_hash":
+                result = await traceGet(`/api/v1/analysis/threat-intel/lookup/${args.sha256}`);
+                break;
+            case "trace_dashboard_stats":
+                result = await traceGet("/api/v1/dashboard/stats");
+                break;
+            case "trace_get_mitre": {
+                const limit = args?.limit ?? 10;
+                result = await traceGet(`/api/v1/dashboard/top-mitre?limit=${limit}`);
+                break;
+            }
+            case "trace_get_process_tree":
+                result = await traceGet(`/api/v1/analysis/${args.analysis_id}/process-tree`);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ayazdata/trace-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Trace Malware Analysis Platform — connect Claude, Codex, and Gemini to your Trace instance",
+  "type": "module",
+  "bin": {
+    "trace-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "malware-analysis",
+    "security",
+    "trace",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  }
+}