README.md•5.08 kB
# 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