# DESA — Model Context Protocol (MCP) Integration

> **Version:** 1.0.0
> **Maintained by:** [Platphorm News](https://platphormnews.com)
> **Last Updated:** 2025-03-07

## Overview

DESA implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to enable AI agents, LLMs, and automated tools to interact with the PowerShell script analysis engine programmatically.

## MCP Endpoint

```
POST https://desa.platphormnews.com/api/mcp
Content-Type: application/json
```

All MCP communication uses **JSON-RPC 2.0** over HTTPS.

## Protocol Handshake

### Initialize

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  }
}
```

### List Tools

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

### Call a Tool

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "desa_analyze_script",
    "arguments": {
      "script": "$encoded = [Convert]::ToBase64String(...)",
      "options": {
        "deep_decode": true,
        "extract_iocs": true
      }
    }
  }
}
```

## Available Tools

### desa_analyze_script

Submit a PowerShell script for full analysis.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `script` | string | Yes | PowerShell script content |
| `options.deep_decode` | boolean | No | Enable recursive deobfuscation |
| `options.extract_iocs` | boolean | No | Extract IOCs from decoded content |

**Returns:** Full analysis result with threat score, findings, IOCs, and MITRE ATT&CK mappings.

### desa_decode_string

Decode an obfuscated string.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input` | string | Yes | Encoded string to decode |
| `encoding` | string | No | Hint: `base64`, `hex`, `xor` |

**Returns:** Decoded content with encoding chain metadata.

### desa_extract_iocs

Extract IOCs from text content.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Text to scan for IOCs |

**Returns:** Array of IOCs with type, value, confidence, and context.

### desa_get_threat_intel

Retrieve threat intelligence for an IOC.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ioc` | string | Yes | IOC value (IP, hash, domain) |
| `type` | string | No | IOC type hint |

**Returns:** Threat reputation, related samples, and enrichment data.

### desa_list_detection_rules

Browse available detection rules.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Filter by category |
| `severity` | string | No | Filter by severity |

**Returns:** Array of detection rules with metadata.

## MCP Client Library

DESA provides a TypeScript MCP client at `lib/mcp/client.ts`:

```typescript
import { createDESAMCPClient } from '@/lib/mcp/client'

const client = createDESAMCPClient({
  endpoint: 'https://desa.platphormnews.com/api/mcp'
})

// Initialize handshake
await client.initialize()

// List available tools
const tools = await client.listTools()

// Call a tool
const result = await client.callTool('desa_analyze_script', {
  script: '$encoded = [Convert]::ToBase64String(...)',
  options: { deep_decode: true }
})
```

## MCP Hub Registration

DESA registers its tools with the PlatphormNews MCP Hub at `mcp.platphormnews.com`. This enables:

- **Tool Discovery:** Other network services can discover DESA's capabilities.
- **Cross-Service Orchestration:** AI agents can compose workflows across multiple PlatphormNews services.
- **Capability Negotiation:** Services advertise supported tools, resources, and prompts.

## Network MCP Services

| Service | MCP Endpoint | Tools |
|---------|-------------|-------|
| **DESA** | `desa.platphormnews.com/api/mcp` | Script analysis, IOC extraction |
| **MSI** | `msi.platphormnews.com/api/mcp` | Threat intelligence, sample analysis |
| **JSON** | `json.platphormnews.com/api/mcp` | JSON formatting, validation |
| **XML** | `xml.platphormnews.com/api/mcp` | XML validation, feed management |
| **SVG** | `svg.platphormnews.com/api/mcp` | SVG report generation |
| **MCP Hub** | `mcp.platphormnews.com/api/mcp` | Tool registry, service discovery |

## Error Handling

MCP errors follow JSON-RPC 2.0 conventions:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": { "details": "Script content is required" }
  }
}
```

| Code | Meaning |
|------|---------|
| -32700 | Parse error |
| -32600 | Invalid request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |

## Links

- **MCP Specification:** [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- **MCP Hub:** [mcp.platphormnews.com](https://mcp.platphormnews.com)
- **DESA API:** [desa.platphormnews.com/api/docs](https://desa.platphormnews.com/api/docs)
- **PlatphormNews:** [platphormnews.com](https://platphormnews.com)