Content
# Threat Intelligence Integration Query Service
## Project Overview
This project is a threat intelligence integration query service based on FastMCP, supporting the querying of threat intelligence data for IP addresses, URLs, or file hashes (MD5, SHA1, SHA256). The service integrates APIs from multiple threat intelligence platforms, providing security analysts and system administrators with convenient threat intelligence query capabilities to enhance the efficiency of threat identification and response.
## Features
- **Multi-source Data Integration**: Integrates mainstream threat intelligence platforms such as VirusTotal, AbuseIPDB, and 微步在线 (Weibu Online).
- **Unified Query Interface**: Provides a standardized API interface that supports batch queries and automated integration.
- **High-performance Design**: Utilizes an asynchronous query mechanism to support concurrent request processing.
- **Flexible Scalability**: Modular architecture design makes it easy to integrate new intelligence sources.
## Project Structure
```
c2_search_mcp/
├── src/ # Source code directory
│ ├── modules/ # Module directory
│ │ ├── logging/ # Logging module
│ │ ├── query_processor/ # Query processing module
│ │ ├── result_aggregator/ # Result aggregation module
│ │ ├── threat_intel/ # Threat intelligence API integration
│ ├── config.py # Configuration management
│ ├── main.py # Main program entry
│ └── __init__.py # Package initialization file
├── tests/ # Test code
├── docs/ # Documentation
├── config.example.yaml # Configuration file example
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration file
├── uv.lock # uv lock file to ensure environment consistency
└── README.md # Project documentation
```
## Installation Instructions
### Environment Requirements
- Python 3.12 or higher
- uv package management tool
### Installation Steps
1. Clone the code repository
```bash
git clone https://github.com/xuanyu123/c2_search_mcp.git
cd c2_search_mcp
```
2. Install uv (if not already installed)
```bash
# Windows
pip install uv
# Linux/macOS
curl -sSf https://github.com/astral-sh/uv/releases/latest/download/uv-installer.sh | bash
```
3. Synchronize the development environment using uv (recommended)
```bash
# Synchronize dependencies using the uv.lock file
uv sync
```
4. Configure API keys
```bash
cp config.example.yaml config.yaml
# Edit config.yaml to fill in the API keys for each platform
```
## Usage
#### Configure MCP Service
Add to your MCP client configuration file, replacing "YOU_C2_SEARCH_MCP_DIR_PATH" with your own directory.
```bash
"c2_search_mcp": {
"command": "uv",
"args": [
"--directory",
"YOU_C2_SEARCH_MCP_DIR_PATH",
"run",
"-m",
"src.main"
],
"disabled": false,
"autoApprove": []
}
```
### Usage Example
#### Cursor Integration
1. Configure MCP
2. Query using natural language in cursor agent mode
#### Cherry Studio Integration
1. Configure MCP
2. Query using natural language in Cherry Studio agent mode
## Development and Debugging
### MCP Inspector Debugging
MCP Inspector is a powerful debugging tool that helps you monitor and debug the operational status of the MCP service.
1. Start the Inspector
```bash
fastmcp dev src/main.py
```
Or run directly with npx
```bash
npx @modelcontextprotocol/inspector uv run src/main.py
```
2. Access the debugging interface
- Open a browser and go to `http://localhost:port` (check the port in the console)
- In the Inspector interface, you can see all registered MCP services
3. Debugging Features
- Real-time monitoring of service status
- View request/response logs
- Test API interfaces
- View performance metrics
### Troubleshooting
1. Service fails to start
- Check if the configuration file is correct
- Ensure all dependencies are correctly installed
- Check the log file for detailed error information
2. API call fails
- Verify if the API key is correctly configured
- Check network connection status
- Confirm if API request limits have been exceeded
## Contribution Guidelines
We welcome issue reports and feature requests. If you would like to contribute code, please follow these steps:
1. Fork the project repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
