# Contributing to dns-security-mcp

Thank you for your interest in contributing to **dns-security-mcp** — a 103-tool MCP server for comprehensive DNS security analysis.

## Table of Contents

- [Development Setup](#development-setup)
- [Project Structure](#project-structure)
- [Adding a New Tool](#adding-a-new-tool)
- [Adding a New Category](#adding-a-new-category)
- [Code Guidelines](#code-guidelines)
- [Pull Request Process](#pull-request-process)
- [Reporting Bugs](#reporting-bugs)

---

## Development Setup

### Prerequisites

| Tool | Version | Purpose |
|------|---------|---------|
| [Bun](https://bun.sh) | 1.3.9+ | Runtime & package manager |
| [Node.js](https://nodejs.org) | 18+ | Publish target |
| Git | any | Version control |

### Quick Start

```bash
git clone https://github.com/orhanyildirim/dns-security-mcp.git
cd dns-security-mcp
bun install
bun run dev          # Watch mode
bun run build        # Build for npm
```

### Useful Commands

```bash
bun run src/index.ts --help              # CLI help
bun run src/index.ts --list              # List all 103 tools
bun run src/index.ts --tool <name> '<json>'  # Run a single tool
```

---

## Project Structure

```
src/
├── index.ts                  # Entry point & CLI
├── dns-packet.d.ts           # Type declarations for dns-packet
├── protocol/
│   ├── mcp-server.ts         # MCP server setup (stdio transport)
│   └── tools.ts              # Tool registry (imports all 13 categories)
├── types/
│   └── index.ts              # Shared types (ToolDef, etc.)
├── utils/
│   ├── cache.ts              # TTL cache
│   ├── rate-limiter.ts       # Per-provider rate limiter
│   └── dns-client.ts         # Raw DNS wire-format client
├── data/
│   ├── dnsbl-lists.ts        # DNSBL/SURBL list data
│   ├── takeover-fingerprints.ts  # Subdomain takeover signatures
│   ├── tunneling-signatures.ts   # DNS tunnel tool fingerprints
│   └── dkim-selectors.ts     # Common DKIM selector list
│
│  ── Categories (13 directories, 103 tools) ──
│
├── dns/           # 12 tools — DNS reconnaissance
├── dnssec/        #  8 tools — DNSSEC validation
├── email/         #  9 tools — Email security (SPF/DKIM/DMARC)
├── hijack/        #  9 tools — DNS hijacking detection
├── tunnel/        #  7 tools — DNS tunneling detection
├── ct/            #  7 tools — Certificate Transparency
├── domain/        # 10 tools — Domain intelligence
├── typo/          #  8 tools — Typosquatting detection
├── blocklist/     #  6 tools — Blocklist & reputation
├── infra/         #  9 tools — Infrastructure security
├── privacy/       #  6 tools — DNS privacy
├── threat/        #  7 tools — Threat intelligence
└── report/        #  5 tools — Reporting & compliance
```

Each category directory contains a single `index.ts` that exports a `ToolDef[]` array.

---

## Adding a New Tool

### 1. Choose the Right Category

Pick the category that best fits your tool. If none fits, see [Adding a New Category](#adding-a-new-category).

### 2. Define the Tool

Open `src/<category>/index.ts` and add a new entry to the exported array:

```typescript
{
  name: "category_tool_name",
  description: "One-line description of what the tool does",
  inputSchema: {
    type: "object" as const,
    properties: {
      domain: {
        type: "string",
        description: "Target domain to analyze",
      },
      // ... more parameters
    },
    required: ["domain"],
  },
  handler: async (args: Record<string, unknown>) => {
    const domain = args.domain as string;

    // Implementation here
    // Use node:dns/promises, node:tls, node:net, node:dgram, dns-packet, etc.

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  },
}
```

### 3. Naming Convention

- Tool names: `category_action_noun` (e.g. `dns_zone_transfer`, `email_check_spf`)
- Use the category prefix consistently
- Keep names descriptive but concise

### 4. Schema Rules

- Every property must have `.describe()` or a `description` field
- Use Zod-compatible JSON Schema types
- Mark truly optional parameters as such; keep `required` array accurate

### 5. Implementation Guidelines

- Use **Node.js built-ins** where possible: `node:dns/promises`, `node:tls`, `node:https`, `node:net`, `node:dgram`, `node:crypto`
- Use **`dns-packet`** for raw DNS wire-format encoding/decoding
- Use **native `fetch()`** for HTTP API calls
- Wrap external calls in try/catch; return structured error messages
- Respect rate limiting via `src/utils/rate-limiter.ts`
- Use TTL cache via `src/utils/cache.ts` for expensive lookups

### 6. Register (if adding a new category)

The tool is auto-registered if you add it to an existing category's array. For new categories, see below.

---

## Adding a New Category

1. Create `src/<category>/index.ts` exporting a `ToolDef[]`
2. Import and spread it in `src/protocol/tools.ts`:

```typescript
import { newTools } from "../newcategory/index.js";

export const allTools: ToolDef[] = [
  // ... existing spreads
  ...newTools,
];
```

3. Update this document's project structure table

---

## Code Guidelines

| Rule | Detail |
|------|--------|
| **Language** | TypeScript strict mode |
| **Imports** | ESM with `.js` extension (`"../utils/cache.js"`) |
| **Formatting** | 2-space indent, no semicolons optional (match existing) |
| **Error handling** | Always try/catch external calls; return structured errors |
| **API keys** | Always optional — graceful error when missing |
| **No side effects** | Tools must be read-only; never modify DNS records |
| **Dependencies** | Minimize — prefer Node.js built-ins over npm packages |
| **Rate limiting** | Use the shared rate limiter for any external API |
| **Caching** | Use TTL cache for expensive/repeated lookups |

---

## Pull Request Process

1. **Fork & branch** — create a feature branch from `main`
2. **Implement** — follow the guidelines above
3. **Test locally** — run your tool via CLI:
   ```bash
   bun run src/index.ts --tool your_tool_name '{"domain":"example.com"}'
   ```
4. **Verify build** — `bun run build` must succeed without errors
5. **Verify listing** — `bun run src/index.ts --list` must show your tool
6. **Commit** — use [Conventional Commits](https://www.conventionalcommits.org/):
   ```
   feat(dns): add dns_new_tool for X analysis
   fix(email): handle missing DKIM selector gracefully
   docs: update CHANGELOG for v0.2.0
   ```
7. **Open PR** — target `main`, describe what the tool does and why

### PR Checklist

- [ ] Tool name follows `category_action` convention
- [ ] All schema fields have descriptions
- [ ] API keys are optional with graceful fallback
- [ ] Error cases return structured messages (not thrown exceptions)
- [ ] `bun run build` passes
- [ ] `bun run src/index.ts --list` shows the new tool
- [ ] Tool tested with real domains via CLI

---

## Reporting Bugs

Open a [GitHub Issue](https://github.com/orhanyildirim/dns-security-mcp/issues) with:

- **Tool name** (e.g. `dns_zone_transfer`)
- **Input** — the JSON arguments you passed
- **Expected behavior**
- **Actual behavior** — error message or incorrect output
- **Environment** — OS, Bun/Node version, MCP client

---

Thank you for helping make DNS security analysis more accessible!