Investigations

Investigations is a production-grade Model Context Protocol (MCP) server providing forensic investigations, root cause analysis, and systematic evidence-based problem solving. Works with Cursor, Windsurf, and Claude via stdio. Distributed via npm and Docker. Built and maintained by BuildWorks.AI.

Features

$3

- Case Initialization: Create and manage investigation cases with proper metadata
- Evidence Collection: Gather evidence from multiple sources while maintaining chain of custody
- Case Tracking: Monitor investigation progress and status
- Case Search: Find and filter investigations by various criteria

$3

- Log Analysis: Collect and analyze application, system, and security logs
- Configuration Inspection: Gather system and application configurations
- Performance Metrics: Collect CPU, memory, disk, and network metrics
- Network Analysis: Gather connection, interface, and routing information
- Process Information: Collect running processes and system state
- Filesystem Data: Gather file system information and directory contents
- Database Information: Collect query results and database state
- Security Data: Users, permissions, security logs, open ports, running services, file integrity, suspicious processes, vulnerability scan
- Infrastructure: System, hardware, software, services, load balancer, proxies with scoring
- Container: Docker info, containers, images, volumes, networks with scoring
- Cloud: Cloud provider, instance metadata, security groups with scoring
- Monitoring: Tools, alerts, metrics history, health checks, dashboards with scoring

$3

- Timeline Analysis: Chronological reconstruction of events
- Causal Analysis: Map cause-effect relationships to identify root causes
- Performance Analysis: Identify bottlenecks and optimization opportunities
- Security Analysis: Detect threats and assess vulnerabilities
- Correlation Analysis: Correlate evidence from multiple sources
- Statistical Analysis: Detect anomalies and patterns

$3

- Multi-Format Reports: Generate reports in JSON, Markdown, HTML, PDF, XML, YAML, CSV, Excel, and PowerPoint
- Comprehensive Documentation: Include evidence, analysis, timeline, and recommendations
- Professional Layout: Executive summaries and detailed findings
- Audit Trails: Complete chain of custody documentation

$3

- Visualization Tools: Timeline, evidence flow, analysis confidence, severity distribution, category breakdown, network diagram, process flow
- API Integrations: Slack, Jira, Confluence, GitHub, GitLab, Jenkins, Prometheus, Grafana, Elasticsearch, Splunk

⚠️ Security Disclaimer

IMPORTANT SECURITY NOTICE: This software is designed for forensic investigations and root cause analysis. Users must understand and accept the following security implications:

$3

- Sensitive Data: This tool collects system information, logs, configurations, and potentially sensitive data
- Data Storage: All investigation data is stored locally in JSON files in ./.investigations/ directory
- No Encryption: Data is stored in plain text JSON format without encryption
- Data Retention: Automatic FIFO cleanup removes old investigations (max 50)
- Storage Management: Users are responsible for managing the .investigations/ folder
- Git Ignore: Users must add .investigations/ to their .gitignore file to prevent committing sensitive data

$3

- Access Control: Ensure proper file permissions on the storage directory
- Network Security: Evidence collection may involve network requests and data transmission
- System Access: The tool requires system-level access to collect evidence
- Data Sensitivity: Be aware of what data is being collected and stored

$3

- Authorization Required: Only use on systems you own or have explicit permission to investigate
- Data Protection: Comply with applicable data protection laws (GDPR, CCPA, etc.)
- Chain of Custody: Maintain proper chain of custody for forensic evidence
- Legal Compliance: Ensure investigations comply with local laws and regulations

$3

- No Warranty: This software is provided "as is" without security guarantees
- Use at Own Risk: Users assume all risks associated with data collection and storage
- Professional Use: Intended for qualified professionals in controlled environments

By using this software, you acknowledge and accept these security implications and limitations.

Storage Management

$3

All investigation data is stored in the ./.investigations/ directory with the following structure:
``
.investigations/
├── investigations/
│ ├── {investigation_id}.json
│ └── index.json
├── evidence/
│ ├── {investigation_id}/
│ │ └── {evidence_id}.json
│ └── index.json
├── analysis/
│ ├── {investigation_id}/
│ │ └── {analysis_id}.json
│ └── index.json
└── reports/
├── {investigation_id}/
│ └── {report_id}.json
└── index.json
`

$3

- Directory Management: Users are responsible for creating, managing, and cleaning up the .investigations/ folder
- Git Ignore: CRITICAL: Add .investigations/ to your .gitignore file to prevent committing sensitive investigation data
- File Permissions: Ensure proper file permissions on the storage directory
- Data Cleanup: Manually delete the folder when no longer needed
- Backup: Create backups of investigation data if needed for long-term storage

$3

`gitignore

Investigations MCP storage directory

.investigations/
`

Installation

$3

- Node.js: Version 18.0.0 or higher (LTS recommended)
- npm: Version 8.0.0 or higher
- Operating System: macOS, Linux, or Windows

$3

- Memory: Minimum 512MB RAM
- Disk Space: 100MB for installation
- Network: Internet connection for initial installation

$3

`bash
npm install -g investigations@latest
`

Important Notes:
- Always use @latest to ensure you get the most recent version and avoid npx resolution conflicts with global installations
- If you encounter "failed to initialize server" errors, see the Troubleshooting section below

Or clone the repository:
`bash
git clone https://github.com/buildworksai/investigations-mcp.git
cd investigations-mcp
`

2. Install dependencies:
`bash
npm install
`

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

4. Run the server:
`bash
npm start
`

Quick Start

$3

1. Start an Investigation
`bash
investigation_start \
--title "API Performance Issue" \
--description "Response times increased significantly" \
--severity high \
--category performance \
--reported-by "monitoring-system"
`

2. Collect Evidence
`bash
investigation_collect_evidence \
--investigation-id "inv_001" \
--sources '[
{
"type": "logs",
"path": "/var/log/app.log",
"time_range": {
"start": "2024-01-15T14:00:00Z",
"end": "2024-01-15T16:00:00Z"
}
},
{
"type": "metrics",
"parameters": {
"metrics": ["cpu", "memory", "disk"]
}
}
]'
`

3. Analyze Evidence
`bash
investigation_analyze_evidence \
--investigation-id "inv_001" \
--analysis-type timeline \
--hypothesis "Database connection pool exhaustion"
`

4. Generate Report
`bash
investigation_generate_report \
--investigation-id "inv_001" \
--format markdown \
--include-evidence true
`

Available Tools

| Tool | Description |
|------|-------------|
| investigation_start | Initialize a new investigation case |
| investigation_collect_evidence | Collect evidence from specified sources |
| investigation_analyze_evidence | Perform systematic analysis of evidence |
| investigation_trace_causality | Trace causal relationships between events |
| investigation_validate_hypothesis | Validate hypothesis against evidence |
| investigation_document_findings | Document investigation findings |
| investigation_generate_report | Generate comprehensive report |
| investigation_list_cases | List investigation cases with filtering |
| investigation_get_case | Get detailed case information |
| investigation_search_evidence | Search through collected evidence |

MCP Client Configuration

$3

Add to your Cursor settings:

`json
{
"mcp": {
"servers": {
"investigations": {
"command": "npx",
"args": ["investigations"],
"env": {
"INVESTIGATIONS_STORAGE_PATH": "/absolute/path/to/.investigations"
}
}
}
}
}
`

$3

To ensure consistent initialization across different launch contexts, configure an absolute storage path for JSON storage. You can do this via either an environment variable or a CLI flag. Replace the placeholder with a valid absolute directory on your system.

- Environment variable (recommended):
`bash


Use an absolute path


export INVESTIGATIONS_STORAGE_PATH="/absolute/path/to/.investigations"
`

- CLI flag:
`bash
investigations --storage-path "/absolute/path/to/.investigations"
`

- Example MCP server config (env var):
`json
{
"mcp": {
"servers": {
"investigations": {
"command": "npx",
"args": ["investigations"],
"env": {
"INVESTIGATIONS_STORAGE_PATH": "/absolute/path/to/.investigations"
}
}
}
}
}
`

- Example MCP server config (CLI flag):
`json
{
"mcp": {
"servers": {
"investigations": {
"command": "npx",
"args": [
"investigations",
"--storage-path",
"/absolute/path/to/.investigations"
],
"env": {}
}
}
}
}
`

Notes:
- Always use an absolute directory path; the server will create it if it does not exist and the parent is writable.
- Prefer the environment variable for editor-agnostic setups; use the CLI flag if your client does not support injecting environment variables.

$3

Add to your Windsurf configuration:

`json
{
"mcp": {
"servers": {
"investigations": {
"command": "npx",
"args": ["investigations"],
"env": {
"INVESTIGATIONS_STORAGE_PATH": "/absolute/path/to/.investigations"
}
}
}
}
}
`

Docker Support

$3


`bash

Build the Docker image

npm run docker:build

Run the container

npm run docker:run
`

$3

`bash

Run in development mode

npm run docker:dev
`

Examples

See the examples/ directory for detailed usage scenarios:
- Performance Investigation
- Security Investigation
- Configuration Investigation

Development

$3

`bash
npm test
`

$3

`bash
npm run lint
npm run lint:fix
`

$3

`bash
npm run dev
`

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

$3

#### Package Installation Failures
If you encounter installation errors, try these steps in order:

`bash


1. Clear npm and npx caches

npm cache clean --force
rm -rf ~/.npm/_npx

2. Verify Node.js version (requires 18+)

node --version

3. Try alternative installation methods

npm install -g investigations@latest

OR

npx investigations@latest --version
`

#### ENOTEMPTY Error with npx
This is a common npm cache corruption issue. The package includes automatic detection and guidance:

`bash


Clear npm and npx cache


npm cache clean --force
rm -rf ~/.npm/_npx
`

#### Storage System
The application uses JSON-based file storage for maximum compatibility. All data is stored in the ./.investigations/ directory with automatic FIFO management.

#### Crypto Deprecation Warnings
If you see warnings about deprecated crypto@1.0.1 package, ensure you're using version 2.2.5 or later, which uses Node.js built-in crypto module instead.

#### MCP Server Connection Issues
If you encounter "failed to initialize server" or "transport error: server terminated" errors:

1. Check version: Ensure you're using version 2.2.5 or later
2. Clear corrupted cache (MOST COMMON FIX):
`bash
npm cache clean --force
rm -rf ~/.npm/_npx
npx investigations@latest --version
`
3. Verify Node.js version: Ensure you're using Node.js 18 or higher
`bash
node --version # Should show v18.x.x or higher
`
4. Check NODE_MODULE_VERSION compatibility:
`bash
node -p "process.versions.modules" # Should match your Node.js version
`
5. Fresh installation:
`bash
npm uninstall -g investigations
npm cache clean --force
rm -rf ~/.npm/_npx
npm install -g investigations@latest
`

#### Native Module Issues (Resolved)
The application now uses JSON-based file storage, eliminating all native module compatibility issues. No more NODE_MODULE_VERSION or better-sqlite3 errors!


#### "No tools" in MCP Client
If your MCP client shows "No tools, prompts, or resources":

1. Verify server startup: Check that the server starts without errors
2. Check MCP configuration: Ensure correct command and args in your MCP config
3. Test manually: Run echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx investigations@latest
4. Restart client: Restart your MCP client after configuration changes

$3

- GitHub Issues: Report bugs or request features
- Documentation: Full documentation
- BuildWorks.AI Support: contact@buildworks.ai

Support

For questions, issues, or contributions:
- Create an issue in the GitHub repository
- Review the SETUP.md for detailed setup instructions
- Check the examples for usage patterns
- Contact BuildWorks.AI support

Roadmap

$3

- [x] Basic investigation case management
- [x] Evidence collection from common sources
- [x] Simple analysis and reporting
- [x] JSON-based file storage setup
- [x] MCP server implementation
- [x] npm and GitHub Packages publishing
- [x] Docker containerization

$3

- [x] Sophisticated causal analysis
- [x] Hypothesis validation with confidence scoring
- [x] Enhanced timeline reconstruction
- [x] Multi-source evidence correlation

$3

- [x] Security forensics capabilities
- [x] Performance analysis tools
- [x] Infrastructure inspection tools
- [x] Custom evidence collectors

$3

- [x] Advanced reporting formats
- [x] Visualization tools
- [x] API integrations
- [x] Comprehensive documentation

Changelog

$3

- Strict argument validation for all MCP tools with Joi schemas
- Type-safe handler inputs in src/index.ts to satisfy CI tsc checks
- Build hardening: resolves MCP request arguments undefined cases
- Docs: clarified absolute storage path configuration for MCP clients
- No behavioral changes to existing tools; validation errors are clearer

$3

- Complete JSON Storage System: Full migration from SQLite to JSON-based file storage with FIFO management.
- Enhanced Storage Architecture: Organized file structure with automatic cleanup and indexing.
- Improved Performance: Eliminated native module dependencies for better compatibility.
- Comprehensive Testing: Updated test suite with FIFO enforcement and date handling.
- Migration Utility: Added migration script for existing SQLite users.
- Updated Documentation: Complete documentation overhaul reflecting new storage system.
- Docker Integration: Updated Docker configurations for JSON storage.
- Simplified Setup: Removed complex setup scripts and native module requirements.
- Better Error Handling: Enhanced error messages and troubleshooting guides.
- Production Ready: Fully tested and verified storage system with automatic cleanup.

$3

- Complete Rebranding: Package renamed from buildworks-ai-investigations-mcp to investigations` for simplicity
- Simplified Installation: Clean, short package name for easier installation and usage
- JSON Storage System: File-based JSON storage with FIFO management (max 50 investigations)
- Enhanced Performance: Optimized for high-concurrency operations (150 concurrent max)
- Comprehensive Testing: 75+ tests with stress testing for 65+ investigations
- Production Ready: Full error handling, logging, health monitoring, and audit trails
- MCP Compliance: Full Model Context Protocol compatibility for IDE integration
- Cross-Platform: Works on macOS, Linux, and Windows
- Zero Dependencies: No native modules or complex database setup required