# Forensics Connection MCP Server

A Model Context Protocol (MCP) server that analyzes forensic evidence to identify people and their connections, then generates Python code for network visualization.

## Features

- **LLM-Powered Relationship Analysis**: Uses OpenAI's GPT-4 to intelligently analyze relationships between people in evidence text
- **Network Visualization**: Generates comprehensive Python code using NetworkX and Matplotlib for interactive network graphs
- **Evidence Parsing**: Automatically extracts and categorizes different types of evidence (police reports, witness statements, communications, etc.)
- **Connection Strength Scoring**: Assigns relationship strength scores (1-10) based on evidence quality
- **Cluster Analysis**: Identifies groups and central figures in the network
- **Flexible Filtering**: Configurable minimum connection strength thresholds

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd mcp-forensics
```

2. Install dependencies:
```bash
npm install
```

3. Set up environment variables:
```bash
cp .env.example .env
# Edit .env and add your OpenAI API key
```

4. Build the project:
```bash
npm run build
```

## Configuration

Create a `.env` file with your OpenAI API key:

```env
OPENAI_API_KEY=your_openai_api_key_here
```

## Usage

### As an MCP Server

The server can be used with any MCP-compatible client:

```bash
npm start
```

### Available Tools

#### `analyze_connections`

Analyzes evidence text to identify people and their connections.

**Parameters:**
- `evidence` (required): The evidence text to analyze
- `options` (optional):
  - `includeVisualization` (boolean, default: true): Whether to include Python visualization code
  - `minimumConnectionStrength` (number, default: 3): Minimum connection strength to include (1-10)
  - `groupByOrganization` (boolean, default: true): Whether to group people by organization

**Returns:**
- List of people identified with their organizations and roles
- Connections between people with strength scores and evidence
- Central figures in the network
- Clusters/groups of related people
- Python code for network visualization

### Example Usage

```typescript
// Example evidence input
const evidence = `
Police Report #001: Incident occurred at 123 Main St on January 15, 2024 at 2:30 PM. 
Witness John Smith reported suspicious activity. Vehicle license plate ABC123 was seen leaving the scene.

Email Chain - Subject: Concerns about OpenAI: 
From: elon.musk@x.com To: satya.nadella@microsoft.com, mark.zuckerberg@meta.com 
"I'm increasingly concerned about Sam's strategic direction..."

Meeting Notes - Private Tech Leaders Dinner: 
Attendees: Musk, Nadella, Zuckerberg. Topic: OpenAI concerns.
`;

// The server will return detailed analysis and Python visualization code
```

## LLM-Enhanced Relationship Analysis

The system uses OpenAI's GPT-4 to analyze relationships with sophisticated context understanding:

- **Direct Communications**: Emails, messages, calls (strength: 9-10)
- **Face-to-Face Meetings**: Shared events, professional collaboration (strength: 7-8)
- **Group Communications**: Shared concerns, indirect interactions (strength: 5-6)
- **Professional Associations**: Mentioned together, weak connections (strength: 3-4)
- **Coincidental Mentions**: Very weak connections (strength: 1-2)

## Python Visualization Output

The generated Python code includes:

- **Network Graph**: Interactive visualization with NetworkX and Matplotlib
- **Organization Grouping**: Color-coded nodes by organization
- **Connection Types**: Different edge styles for different relationship types
- **Centrality Analysis**: Node sizes based on degree centrality
- **Statistical Report**: Network statistics and key findings
- **Customizable Layout**: Spring layout for optimal node positioning

### Required Python Dependencies

The generated code requires:

```bash
pip install networkx matplotlib numpy
```

## Development

### Scripts

- `npm run build`: Compile TypeScript to JavaScript
- `npm run dev`: Build with watch mode
- `npm start`: Run the compiled server
- `npm run inspector`: Run with MCP inspector for debugging

### Project Structure

```
src/
├── index.ts              # Main server entry point
├── types.ts              # TypeScript type definitions
├── evidenceParser.ts     # Evidence parsing and LLM analysis
├── pythonGenerator.ts    # Python code generation
└── ...
```

## Connection Types

The system identifies several types of connections:

- **communication**: Direct communications (emails, messages)
- **meeting**: In-person meetings and events
- **witness**: Witness/observer relationships
- **location**: Geographic/location-based connections
- **organization**: Same organization affiliations
- **other**: General associations and mentions

## Error Handling

- Fallback to pattern-based analysis if LLM calls fail
- Rate limiting protection for OpenAI API calls
- Comprehensive error reporting and logging
- Graceful degradation for missing data

## License

MIT License