@ayazdata/trace-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,28 +1,26 @@
-# Trace MCP Server
+# @ayazdata/trace-mcp
 
-Connect Claude Code, Codex, and Gemini to [Trace](https://trace.akpinar.dev) malware analysis platform.
+MCP server for [Trace](https://trace.akpinar.dev) — AI-powered malware analysis platform.  
+Connects Claude Code, Codex CLI, and Gemini CLI directly to a Trace instance.
 
-## Install — Claude Code
+> **Live instance:** `https://trace.akpinar.dev`  
+> **npm:** `@ayazdata/trace-mcp`
 
-```bash
-claude mcp add trace \
-  -e TRACE_URL=https://trace.akpinar.dev \
-  -e TRACE_TOKEN=your_token_here \
-  -- npx -y trace-mcp
-```
+---
+
+## Quick Install
 
-Or for the public instance (no token required):
+### Claude Code
 ```bash
-claude mcp add trace -e TRACE_URL=https://trace.akpinar.dev -- npx -y trace-mcp
+claude mcp add trace -e TRACE_URL=https://trace.akpinar.dev -- npx -y @ayazdata/trace-mcp
 ```
 
-## Install — Codex CLI
-
+### Codex CLI
 Add to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.trace]
 command = "npx"
-args = ["-y", "trace-mcp"]
+args = ["-y", "@ayazdata/trace-mcp"]
 startup_timeout_sec = 15
 
 [mcp_servers.trace.env]
@@ -30,15 +28,14 @@ TRACE_URL = "https://trace.akpinar.dev"
 TRACE_TOKEN = ""
 ```
 
-## Install — Gemini CLI
-
+### Gemini CLI
 Add to `~/.gemini/settings.json`:
 ```json
 {
   "mcpServers": {
     "trace": {
       "command": "npx",
-      "args": ["-y", "trace-mcp"],
+      "args": ["-y", "@ayazdata/trace-mcp"],
       "env": {
         "TRACE_URL": "https://trace.akpinar.dev",
         "TRACE_TOKEN": ""
@@ -48,28 +45,88 @@ Add to `~/.gemini/settings.json`:
 }
 ```
 
+### Project-level (any tool that supports .mcp.json)
+A `.mcp.json` is included at the repo root — tools that support project-level MCP config will pick it up automatically when you open the project.
+
+---
+
 ## Self-hosted
 
-Replace `https://trace.akpinar.dev` with your own instance URL.
+If you run your own Trace instance, replace the URL:
+```bash
+claude mcp add trace -e TRACE_URL=http://localhost:8090 -- npx -y @ayazdata/trace-mcp
+```
+
+For authenticated endpoints, generate a JWT token from Trace settings and pass it:
+```bash
+claude mcp add trace \
+  -e TRACE_URL=https://your-instance.com \
+  -e TRACE_TOKEN=your_jwt_token \
+  -- npx -y @ayazdata/trace-mcp
+```
 
-## Tools
+---
 
-| Tool | Description |
+## Available Tools
+
+| Tool | What it does |
 |------|-------------|
-| `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 |
+| `trace_upload_file` | Upload a local file for malware analysis. Returns `analysis_id`. |
+| `trace_get_analysis` | Full results for an analysis — risk score, YARA hits, MITRE techniques, IOCs, AI summary. |
+| `trace_list_analyses` | List recent analyses. Filter by `risk_level` or `status`. |
+| `trace_get_iocs` | Extract IOCs (IPs, domains, hashes, URLs, registry keys) from an analysis. |
+| `trace_get_sigma_matches` | Sigma detection rules that triggered on a sample. |
+| `trace_get_ai_summary` | AI-generated threat narrative for an analysis. |
+| `trace_lookup_hash` | Threat intel lookup for a SHA256 hash (VirusTotal + internal DB). |
+| `trace_dashboard_stats` | Platform-wide stats: total analyses, risk distribution, detection rates. |
+| `trace_get_mitre` | Top MITRE ATT&CK techniques observed across all analyses. |
+| `trace_get_process_tree` | Process execution tree from dynamic/sandbox analysis. |
+
+---
+
+## Telegram Bot — @Ayaz_Trace_Bot
+
+Trace also ships a Telegram bot for on-the-go analysis.
+
+**Start:** Search `@Ayaz_Trace_Bot` on Telegram or open [t.me/Ayaz_Trace_Bot](https://t.me/Ayaz_Trace_Bot)
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Welcome message and usage guide |
+| `/help` | Same as /start |
+| `/set_detail short` | Receive compact analysis reports |
+| `/set_detail detailed` | Receive full analysis reports (default) |
+
+### Usage
+
+1. Send any file **as a Document** (not compressed) — the bot queues it for analysis.
+2. When analysis completes, you get a notification with risk score, threat level, and detections.
+3. High-risk files trigger a quarantine alert automatically.
+
+> URL scanning is not yet supported. Send files directly.
+
+### Self-hosting the bot
+
+Set `TELEGRAM_BOT_TOKEN` in your `.env` before starting the stack:
+```env
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+```
+The bot starts automatically with the backend on `docker compose up`.
+
+---
 
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TRACE_URL` | `http://localhost:8090` | Trace instance URL |
-| `TRACE_TOKEN` | _(empty)_ | JWT token for authenticated endpoints |
+| `TRACE_URL` | `http://localhost:8090` | Trace instance base URL |
+| `TRACE_TOKEN` | *(empty)* | JWT token — required only for auth-protected endpoints |
+
+---
+
+## Requirements
+
+- Node.js 18+
+- A running Trace instance (or use the live one at `trace.akpinar.dev`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayazdata/trace-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for Trace Malware Analysis Platform — connect Claude, Codex, and Gemini to your Trace instance",
   "type": "module",
   "bin": {