# REMnux Documentation MCP Server

An MCP server that enables AI assistants to search and retrieve information from the [REMnux tools documentation](https://docs.remnux.org).

## What Is This?

[REMnux](https://remnux.org) is a Linux toolkit for reverse-engineering and analyzing malicious software. This MCP server gives AI assistants direct access to REMnux documentation, so you can ask questions about malware analysis tools and get accurate, up-to-date answers.

**What it enables:**

- **Search** for tools by name, category, or functionality
- **Retrieve** detailed information about specific tools
- **Answer questions** about which REMnux tools to use for particular tasks

Instead of relying on the AI's training data (which may be outdated), your AI assistant queries the live REMnux documentation.

## Getting Started

To use this MCP server, add it to your AI tool's configuration. The server is publicly hosted and ready to use.

### Claude Desktop

Add to your Claude Desktop configuration file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "remnux-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs-mcp.remnux.org/sse"]
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add remnux-docs --transport sse https://docs-mcp.remnux.org/sse
```

### Cursor

Add to `.cursor/mcp.json` in your project or global settings:

```json
{
  "mcpServers": {
    "remnux-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs-mcp.remnux.org/sse"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "remnux-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs-mcp.remnux.org/sse"]
    }
  }
}
```

### Other MCP-Compatible Tools

For any MCP-compatible AI tool:

- **Server URL:** `https://docs-mcp.remnux.org/sse`
- **Transport:** SSE (Server-Sent Events)

Most tools support connecting via the `mcp-remote` npm package, which handles the SSE transport.

## Example Queries

Once connected, you can ask your AI assistant questions like:

- "What REMnux tools can I use to analyze a suspicious PDF?"
- "How do I extract strings from a malware sample using REMnux?"
- "What's the difference between peframe and pefile?"
- "Which tools in REMnux can deobfuscate JavaScript?"
- "What network analysis tools are available in REMnux?"

The AI will search the REMnux documentation and provide accurate, current information.

## MCP Tools

The server exposes these tools to AI assistants:

| Tool | Description |
|------|-------------|
| `search_remnux` | Search documentation by keywords |
| `get_article` | Retrieve full details about a specific tool |
| `get_index_info` | Get index statistics and metadata |

## Architecture

This MCP server is built on [Cloudflare Workers](https://developers.cloudflare.com/agents/guides/remote-mcp-server/). The Worker source code is in this repository.

```
┌─────────────────┐     MCP Protocol      ┌─────────────────────┐
│   AI Assistant  │◄────────────────────►│  Cloudflare Worker  │
│  (Claude, etc.) │        (SSE)          │  (MCP Server)       │
└─────────────────┘                       └──────────┬──────────┘
                                                     │
                                                     │ Reads
                                                     ▼
                                          ┌─────────────────────┐
                                          │   Cloudflare R2     │
                                          │  (Search Index)     │
                                          └─────────────────────┘
                                                     ▲
                                                     │ Generated from
                                                     │
                                          ┌─────────────────────┐
                                          │  REMnux salt-states │
                                          │  (Source of Truth)  │
                                          └─────────────────────┘
```

### Components

**Cloudflare Worker** — Hosts the MCP server at `docs-mcp.remnux.org`. Handles requests from AI assistants using the MCP protocol over SSE (Server-Sent Events). Implemented in `src/index.ts` using Cloudflare's [Agents SDK](https://developers.cloudflare.com/agents/) with the `McpAgent` class.

**Cloudflare R2** — Object storage for the search index. The Worker caches the index in memory for 1 hour to minimize reads.

**Search Engine** — Powered by [Fuse.js](https://fusejs.io/) for fuzzy matching. Searches across tool names, descriptions, categories, and full content with weighted relevance scoring.

**MCP Protocol** — The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to external data sources.

### Search Index Generation

The search index is generated from the [REMnux salt-states repository](https://github.com/REMnux/salt-states), which is the source of truth for all REMnux tool configurations and documentation.

The generation process:

1. A Python script in the [salt-states CI directory](https://github.com/REMnux/salt-states/tree/master/.ci) parses tool metadata from the Salt state files
2. It extracts tool names, descriptions, categories, and documentation URLs
3. The script produces a JSON search index conforming to the schema in `src/types.ts`
4. The index is uploaded to the Cloudflare R2 bucket, where the Worker retrieves it

This process runs automatically during REMnux releases, ensuring the search index stays synchronized with the official tool documentation.

### Source Files

| File | Description |
|------|-------------|
| `src/index.ts` | Worker implementation with MCP tool definitions |
| `src/types.ts` | TypeScript types and Zod schemas for the search index |
| `wrangler.jsonc` | Cloudflare Worker deployment configuration |

## Contributing

This project is part of the [REMnux](https://remnux.org) ecosystem. For issues or suggestions related to this MCP server, please open an issue in this repository.