Metadata-Version: 2.4
Name: honeydb-ai
Version: 0.2.3
Summary: HoneyDB AI Interface with HoneyDB MCP Server
Author-email: Deception Logic <info@deceptionlogic.com>
License: Proprietary License
        
        Copyright (c) 2024–2026 Deception Logic. All Rights Reserved.
        
        This software and associated documentation files (the "Software") are the 
        proprietary and confidential property of Deception Logic.
        
        NOTICE: All information contained herein is, and remains the property of 
        Deception Logic. The intellectual and technical concepts contained herein 
        are proprietary to Deception Logic and may be covered by U.S. and Foreign 
        Patents, patents in process, and are protected by trade secret or copyright law.
        
        Dissemination of this information or reproduction of this material is strictly 
        forbidden unless prior written permission is obtained from Deception Logic.
        
        Unauthorized copying of this file, via any medium, is strictly prohibited.
        
        For licensing inquiries, please contact: info@deceptionlogic.com
        
Project-URL: Homepage, https://honeydb.io
Project-URL: Documentation, https://honeydb.io/docs
Project-URL: Repository, https://github.com/honeydbio/mcp-cli
Project-URL: Bug Tracker, https://github.com/honeydbio/mcp-cli/issues
Keywords: honeydb,threat-intelligence,mcp,ai,security,honeypot,deception
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic<1.0.0,>=0.57.0
Requires-Dist: fastmcp<3.0.0,>=2.13.1
Requires-Dist: openai<2.0.0,>=1.97.0
Requires-Dist: typer<1.0.0,>=0.16.0
Requires-Dist: google-genai<2.0.0,>=1.25.0
Requires-Dist: prompt_toolkit<4.0.0,>=3.0.0
Requires-Dist: rich<14.0.0,>=13.9.0
Requires-Dist: pygments<3.0.0,>=2.17.0
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.1
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: filelock<4.0.0,>=3.13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Dynamic: license-file

# 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**
