# HoneyDB MCP CLI

**MCP-Enabled Threat Intelligence Chat Interface**

## Overview

HoneyDB MCP CLI is a command-line interface that connects your favorite LLM (OpenAI, Anthropic, or Gemini) with **HoneyDB's threat intelligence tools** via the **Model Context Protocol (MCP)**. Ask natural language questions about IP addresses, payloads, honeypot data, and more—your LLM automatically invokes HoneyDB tools to provide accurate, real-time threat intelligence.

### What is MCP?

The [Model Context Protocol](https://spec.modelcontextprotocol.io/) allows LLMs to access external tools and data sources. This CLI connects to the **HoneyDB MCP server**, which exposes 20+ threat intelligence tools that LLMs can invoke autonomously during conversations.

### Supported LLM Providers
- **OpenAI**
- **Anthropic**
- **Google Gemini**

## Features

### Core Features
- **🔧 MCP Tool Integration** - LLMs can invoke HoneyDB tools automatically
- **💬 Interactive Chat** - Natural language interface to threat intelligence data
- **💾 Session Management** - Save, resume, and manage multiple chat sessions
- **🎨 Professional UI** - Dark/light mode, animated thinking indicator, error handling
- **🐝 Thinking Indicator** - Animated bee/honeypot-themed feedback while the LLM processes requests, with graceful fallback for non-interactive terminals

### HoneyDB MCP Tools Available
- **IP Intelligence** - Scanner detection, history, network enrichment
- **Monitors** - Create, view, and delete threat monitors
- **Honeypot Nodes** - Node management and data retrieval
- **Statistics** - Threat data aggregation and analysis
- **Bad Host Tracking** - Recent malicious activity monitoring

### Recent Enhancements
- **✅ MCP Integration** - Full MCP protocol support with HoneyDB server
- **🔒 Enhanced Security** - File locking prevents data corruption
- **⌨️ Graceful Interruption** - Ctrl+C cancellation without data loss
- **🎯 Terminal Detection** - Automatic dark/light mode support
- **🔐 Privacy-First Logging** - Never logs API keys or message content
- **🔄 Hot Configuration Reload** - Update settings without restarting
- **📑 Session Pagination** - Efficiently manage thousands of sessions
- **🐝 Thinking Indicator** - Animated bee/honeypot-themed feedback while awaiting LLM responses
- **🤖 Updated LLM Models** - Current flagship models set as defaults: GPT-5.4 (OpenAI), Claude Opus 4.6 (Anthropic), Gemini 3.1 Pro (Gemini)

## Installation

### Requirements
- Python 3.10 or newer
- HoneyDB API credentials ([sign up at honeydb.io](https://honeydb.io/))
- At least one LLM provider API key (OpenAI, Anthropic, or Gemini)

### Install with pip

```bash
git clone https://github.com/honeydbio/mcp-cli.git
cd mcp-cli

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies and the package
pip install -r requirements.txt
pip install .
```

### Install with uv (Faster Alternative)

[uv](https://github.com/astral-sh/uv) is a fast drop-in replacement for `pip` and `venv`. Installation steps are identical — substitute `uv` for `pip` and `python -m venv`:

```bash
git clone https://github.com/honeydbio/mcp-cli.git
cd mcp-cli

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

uv pip install -r requirements.txt
uv pip install .
```

### Install with pipx

```bash
git clone https://github.com/honeydbio/mcp-cli.git
cd mcp-cli
pipx install .
```


## Quick Start

### 1. Interactive Setup (Recommended)

Run the setup wizard to configure everything at once:

```bash
honeydb-ai config setup
```

The wizard will prompt you for:
1. **HoneyDB API credentials** (required for MCP tools)
   - API ID
   - API Key
   - Get them at: https://honeydb.io/

2. **LLM Provider** (choose one)
   - OpenAI (recommended)
   - Anthropic
   - Google Gemini

3. **MCP Server**
   - Production (default): `https://honeydb.ai/sse`
   - Development (optional): For testing

4. **UI Preferences**
   - Theme (auto-detect, dark, light)
   - Verbose tool calls (show MCP tool invocations)

### 2. Manual Configuration

Set credentials individually:

```bash
# HoneyDB credentials (REQUIRED)
honeydb-ai config set honeydb_api_id your-api-id
honeydb-ai config set honeydb_api_key your-api-key

# LLM Provider API Key (at least one REQUIRED)
honeydb-ai config set openai_api_key sk-your-key-here
# OR
honeydb-ai config set anthropic_api_key sk-ant-your-key-here
# OR
honeydb-ai config set gemini_api_key your-key-here

# Optional: Set default provider
honeydb-ai config set default_provider openai

# Optional: Use development MCP server
honeydb-ai config set mcp_server_url https://honeydb-mcp-dev-db384193f137.herokuapp.com/sse
```

### 3. Start Chatting

```bash
honeydb-ai chat
```

## Usage Examples

### Basic Threat Intelligence Queries

```
> What threats has IP 1.2.3.4 been involved in?
🔧 Tool Call: get_internet_scanner(ip_address="1.2.3.4")
🔧 Tool Call: get_ip_history(ip_address="1.2.3.4")

HoneyDB: IP 1.2.3.4 is identified as an internet scanner and has been
observed in 42 malicious activities across our honeypot network...

---

> Show bad hosts for the service MSSQL
🔧 Tool Call: get_bad_hosts(service="MSSQL")

HoneyDB: Here are the most recent bad hosts targeting MSSQL:
- 198.51.100.42 — 17 attempts, last seen 2026-03-17
- 203.0.113.88 — 9 attempts, last seen 2026-03-16
...

---

> Create a monitor for IP range 10.0.0.0/24
🔧 Tool Call: put_monitors(type="ip_range", range=["10.0.0.0", "10.0.0.255"])

HoneyDB: ✅ Monitor created successfully for IP range 10.0.0.0/24
```

### Session Management

```bash
# Start a new session
honeydb-ai chat --new

# Resume a previous session
honeydb-ai sessions list
honeydb-ai chat --session <session-id>

# View session history
honeydb-ai sessions show <session-id>

# Export session
honeydb-ai sessions export <session-id> output.json
honeydb-ai sessions export <session-id> output.md --format markdown

# Delete old sessions
honeydb-ai sessions delete <session-id>
```

### Configuration Management

```bash
# View current configuration
honeydb-ai config show

# Show config file location
honeydb-ai config path

# Update settings
honeydb-ai config set temperature 0.8
honeydb-ai config set theme dark
honeydb-ai config set default_model gpt-5.4
```

## Chat Commands

While in chat mode, the following slash commands are available:

| Command | Description |
|---|---|
| `/help` | Show available commands |
| `/exit` or `/quit` | Exit chat mode and return to the shell |
| `/model` | Show current provider, model, and session stats |
| `/model change` | Interactively switch provider and model |
| `/history` | Display the current session's message history |
| `/new` | Start a new chat session |

> **Note:** Typing `exit` or `quit` without the leading `/` will not exit — the CLI will remind you to use `/exit` or `/quit`.

---

## MCP Tool Call Visibility

By default, MCP tool calls are hidden to keep chat clean. Enable verbose mode to see tool invocations:

**During Setup:**
```
Show MCP tool calls during chat? (y/N): y
```

**Or Configure Later:**
```bash
honeydb-ai config set verbose_tool_calls true
```

**When Enabled:**
```
> Check IP 8.8.8.8
🔧 Tool Call: get_internet_scanner(ip_address="8.8.8.8", info=True)
✅ Tool Result: get_internet_scanner
🔧 Tool Call: get_ip_history(ip_address="8.8.8.8")
✅ Tool Result: get_ip_history

HoneyDB: [response incorporating tool results]
```

## Architecture

### MCP Flow Diagram

```
User Input
    ↓
CLI Application (honeydb-ai)
    ↓
LLM Provider (OpenAI/Anthropic/Gemini)
    ↓ (recognizes need for HoneyDB data)
HoneyDB MCP Server (https://honeydb.ai/sse)
    ↓ (authenticated with HoneyDB API credentials)
HoneyDB REST API (https://honeydb.io/api/)
    ↓ (retrieves threat intelligence data)
MCP Server returns results to LLM
    ↓
LLM incorporates data into response
    ↓
CLI displays formatted response to user
```

### Key Components

- **MCP Adapters** (`infrastructure/mcp/`) - Provider-specific MCP integrations
- **LLM Service** (`services/llm_service.py`) - Unified interface to all providers
- **Session Management** (`services/session_service.py`) - Chat history persistence
- **Configuration** (`infrastructure/storage/config_store.py`) - INI-based settings
- **Rich UI** (`infrastructure/ui/`) - Terminal rendering and prompts

## Configuration File

Located at: `~/.honeydb_ai/config.ini`

```ini
[honeydb]
api_id = your-honeydb-api-id
api_key = your-honeydb-api-key
mcp_server_url = https://honeydb.ai/sse

[llm]
default_provider = openai
openai_api_key = sk-...
anthropic_api_key =
gemini_api_key =
default_model = gpt-5.4
temperature = 0.7
max_tokens =

[session]
auto_save = true
sessions_dir = ~/.honeydb_ai/sessions

[ui]
theme = auto
markdown_enabled = true
syntax_highlighting = true
verbose_tool_calls = false

[logging]
log_level = INFO
log_file = ~/.honeydb_ai/honeydb_ai.log
log_max_size_mb = 5
log_backup_count = 3
```

## Troubleshooting

### "HoneyDB API credentials not configured"

**Solution:**
```bash
honeydb-ai config set honeydb_api_id your-id
honeydb-ai config set honeydb_api_key your-key
```

Get credentials at: https://honeydb.io/

### "No LLM provider API keys configured"

**Solution:** Configure at least one LLM provider:
```bash
honeydb-ai config set openai_api_key sk-...
# OR
honeydb-ai config set anthropic_api_key sk-ant-...
# OR
honeydb-ai config set gemini_api_key ...
```

### MCP Tools Not Working

1. **Check HoneyDB credentials are set:**
   ```bash
   honeydb-ai config show
   ```

2. **Verify MCP server URL:**
   ```bash
   # Should be: https://honeydb.ai/sse (production)
   # Or: https://honeydb-mcp-dev-db384193f137.herokuapp.com/sse (dev)
   honeydb-ai config set mcp_server_url https://honeydb.ai/sse
   ```

3. **Enable verbose mode to see tool calls:**
   ```bash
   honeydb-ai config set verbose_tool_calls true
   ```

### Session Corruption

If a session file is corrupted, the CLI will attempt to restore from backup (.bak file). If both are corrupted:

```bash
# Delete the corrupted session
honeydb-ai sessions delete <session-id>

# Start a new session
honeydb-ai chat --new
```

## Development

### Running Tests

```bash
# Create and activate virtual environment
uv venv
source .env/bin/activate  # On Windows: .env\Scripts\activate

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=honeydb_ai
```

### Testing MCP Integration

```bash
# Use development MCP server
honeydb-ai config set mcp_server_url https://honeydb-mcp-dev-db384193f137.herokuapp.com/sse

# Enable verbose mode to see tool calls
honeydb-ai config set verbose_tool_calls true

# Test with a simple query
honeydb-ai chat
You: Hello
# Should invoke the 'hello' greeting tool
```

### Project Structure

```
honeydb_ai/
├── cli/                    # CLI commands and entry points
├── controllers/            # Business logic controllers
├── domain/                 # Domain models and interfaces
├── infrastructure/         # External integrations
│   ├── mcp/               # MCP adapter implementations
│   ├── storage/           # File storage (sessions, config)
│   └── ui/                # Terminal UI components
├── services/              # Service layer (LLM, sessions, config)
└── utils/                 # Utilities (logging, formatting, validation)
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This software is proprietary and confidential. All rights reserved by Deception Logic. See the LICENSE file for details.

## Related Resources

- **HoneyDB Platform**: https://honeydb.io/
- **HoneyDB API Documentation**: https://honeydb.io/api/
- **MCP Specification**: https://spec.modelcontextprotocol.io/
- **MCP Server Source**: `/home/foospidy/github.com/honeydbio/mcp-server/`

## Support

- **Issues**: https://github.com/honeydbio/mcp-cli/issues
- **Discussions**: https://github.com/honeydbio/mcp-cli/discussions
- **HoneyDB Support**: support@honeydb.io

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP client support
- Uses [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Powered by [Typer](https://github.com/tiangolo/typer) for CLI framework
- Uses [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) for interactive prompts

---

**Made with ❤️ by the HoneyDB Team**
