# Query Counter MCP Server

An MCP (Model Context Protocol) server that logs all your LLM queries to a local file and provides interactive analytics. Track your interactions with Claude, ChatGPT, Gemini, and other models with detailed categorization and visualizations.

## Features

- **Dual Format Logging**: CSV (default) or Markdown format
- **Interactive Dashboard**: Beautiful HTML analytics dashboard with charts and KPIs
- **Category Tracking**: Organize queries by type (coding, research, debugging, etc.)
- **Rich Analytics**: Track query volume, model usage, category distribution, and trends
- **Configurable**: Custom log file location and format
- **MCP Compatible**: Works with Claude Desktop and other MCP clients

## Installation

1. **Clone the repository:**

```bash
git clone https://github.com/bjulius/QueryCounterMCP.git
cd QueryCounterMCP
```

2. **Install dependencies:**

```bash
npm install
```

3. **Build the project:**

```bash
npm run build
```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "query-counter": {
      "command": "node",
      "args": [
        "/path/to/your/QueryCounterMCP/build/index.js"
      ]
    }
  }
}
```

**Replace `/path/to/your/QueryCounterMCP/` with the actual path where you cloned the repository.**

**Example paths:**
- macOS: `"/Users/yourname/projects/QueryCounterMCP/build/index.js"`
- Windows: `"C:\\Users\\YourName\\Projects\\QueryCounterMCP\\build\\index.js"`

### Environment Variables

Customize the logging behavior:

```json
{
  "mcpServers": {
    "query-counter": {
      "command": "node",
      "args": [
        "/path/to/your/QueryCounterMCP/build/index.js"
      ],
      "env": {
        "QUERY_LOG_FORMAT": "csv",
        "QUERY_LOG_PATH": "/path/to/your/custom/log.csv"
      }
    }
  }
}
```

**Available Options:**
- `QUERY_LOG_FORMAT`: `"csv"` (default) or `"md"` for Markdown
- `QUERY_LOG_PATH`: Custom path for the log file

## Usage

### Logging Queries

The MCP server automatically logs queries made through Claude Desktop. The AI (Claude) determines the appropriate category based on the conversation context.

**Example interaction:**
```
User: Help me debug a React component that's not rendering properly
Claude: [Uses the log_query tool automatically]
        - model: "Claude Sonnet 4.5"
        - query_summary: "Help me debug a React component"
        - category: "debugging" [AI selected]
```

**Tool Parameters:**
- `model` (required): The LLM model name (selected by AI)
- `query_summary` (required): Brief description of the query (generated by AI)
- `category` (optional): Query category (automatically selected by AI based on query type)

### Viewing the Dashboard

Use the `show_dashboard` tool to generate and view analytics:

```
Please show me the dashboard
```

This will:
1. Generate an interactive HTML dashboard from your query data
2. Automatically open it in your default browser
3. Display real-time analytics and visualizations

## Dashboard Features

The interactive dashboard includes:

### KPI Cards
- **Total Queries Today**: Number of queries logged today (highlighted)
- **Average Queries Per Day**: Mean queries across all days
- **Total Number of Categories**: Unique categories used
- **Max Queries in a Day**: Your highest query volume day

### Visualizations
- **Categories by Percent**: Horizontal bar chart showing category distribution
- **Models by Percent**: Horizontal bar chart of AI model usage
- **Total Queries by Day**: Daily query volume over time

### Design
- Clean, modern interface with responsive layout
- Interactive charts powered by Chart.js
- Data labels on all visualizations for easy reading
- Personalized with your name in the subtitle

## Query Categories

The AI automatically selects the most appropriate category for each query. These categories help organize and analyze your query patterns:

### Development & Code
- `coding` - Writing, debugging, or explaining code
- `refactoring` - Code improvements, restructuring, optimization
- `testing` - Writing or running tests, test analysis
- `debugging` - Troubleshooting errors, investigating issues

### Analysis & Research
- `data-analysis` - Analyzing data, visualizations, statistics
- `research` - Information lookup, documentation searches, learning

### Project Management
- `documentation` - Writing/updating docs, README files, comments
- `configuration` - Settings, setup, tool configuration, environment

### Interaction
- `clarification` - Follow-up questions, asking for details
- `selection` - Short confirmations, choosing options
- `navigation` - UI commands, viewing files, moving around
- `conversation` - General chat, greetings, feedback

## Log File Format

By default, queries are logged to `QueryTrackMCP.csv` in CSV format:

```csv
timestamp,date,model,category,query_summary
2025-10-15T18:20:37.516Z,10/15/2025 2:20:37 PM,Claude Sonnet 4.5,debugging,Help me debug a React component
2025-10-15T18:22:15.342Z,10/15/2025 2:22:15 PM,Claude Sonnet 4.5,coding,Create a user authentication function
2025-10-15T18:25:43.891Z,10/15/2025 2:25:43 PM,Claude Sonnet 4.5,data-analysis,Analyze sales data trends
```

**CSV Format Benefits:**
- ✅ Easy to import into Excel, Google Sheets, or Pandas
- ✅ Efficient for data analysis and reporting
- ✅ Compact file size
- ✅ Perfect for generating the interactive dashboard
- ✅ Can be opened and edited in any spreadsheet application

### Alternative: Markdown Format

To use Markdown format instead, set `QUERY_LOG_FORMAT=md` in your environment variables. This creates a `QueryTrackMCP.md` file:

```markdown
# LLM Query Log

This file tracks all queries made to various LLM models.

---

## 10/15/2025, 2:20:37 PM

- **Model**: Claude Sonnet 4.5
- **Category**: debugging
- **Query**: Help me debug a React component
- **Timestamp**: 2025-10-15T18:20:37.516Z

---
```

**Markdown Format Benefits:**
- ✅ Human-readable format
- ✅ Easy to browse in text editors
- ✅ Great for documentation and version control

## Available Tools

### `log_query`
Logs an LLM query to the tracking file.

**Parameters:**
- `model` (string, required): LLM model name
- `query_summary` (string, required): Brief query description
- `category` (string, optional): Query category

### `show_dashboard`
Generates and displays an interactive HTML analytics dashboard.

**Parameters:** None

**Output:** Opens `query-dashboard.html` in your default browser with:
- 4 KPI cards with key metrics
- 3 interactive charts (categories, models, daily trends)
- Real-time data from your CSV log file

## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes during development
npm run watch

# Build and run
npm run dev
```

## File Structure

```
QueryCounterMCP/
├── src/
│   └── index.ts          # Main MCP server code
├── build/
│   └── index.js          # Compiled JavaScript
├── QueryTrackMCP.csv     # Query log (CSV format)
├── query-dashboard.html  # Generated analytics dashboard
├── CLAUDE.md            # Instructions for Claude Code
└── README.md            # This file
```

## Tips

1. **Use categories consistently** for better analytics
2. **Run the dashboard regularly** to track your query patterns
3. **Set up automatic logging** by integrating with your workflow
4. **Export CSV data** for custom analysis in Excel or Python
5. **Customize the format** based on your needs (CSV for analysis, MD for documentation)

## License

MIT