# Calq MCP

A Model Context Protocol (MCP) server for time tracking, project management, AI-powered memory, and team collaboration.

## Features

### ⏱️ Time Tracking
- **Timer system** - Start/stop timers for real-time tracking
- **Manual logging** - Log time with backdating support
- **Billing** - Mark entries as billable/billed, track unbilled time

### 🧠 AI-Powered Memory
- **Semantic search** - Find memories and entries by meaning, not just keywords
- **Personal & shared** - Keep notes private or share with your team
- **Project/client linking** - Associate memories with specific projects or clients
- **Vector storage** - Powered by [ChromaDB](https://trychroma.com) and [Voyage AI](https://voyageai.com) embeddings

### 👥 Team Collaboration
- **GitHub OAuth** - Authenticate team members via GitHub (integrated into MCP flow)
- **Role-based access** - Admin and member roles
- **Per-user data** - Timers and entries are user-scoped

### 📊 Project & Client Management
- **Clients** - Manage client information
- **Projects** - Link projects to clients with hourly rates
- **Invoice summaries** - Get unbilled time grouped by client with calculated values

## Prerequisites

- Node.js 20+
- **PostgreSQL** - Relational database for structured data
- **ChromaDB** - Vector database for semantic search
- **Voyage AI API key** - For generating embeddings
- **GitHub OAuth App** - For user authentication

## Installation

### Option 1: Docker Compose (Recommended)

This automatically sets up Calq, PostgreSQL, and ChromaDB:

```bash
git clone https://github.com/Calq-dev/calq-mcp.git
cd calq-mcp

# Copy and configure environment
cp .env.example .env
# Edit .env with your API keys

# Start services (uses default ports 3000 and 8000)
docker compose up -d

# Or with custom ports
MCP_PORT=3001 CHROMA_PORT=8001 docker compose up -d
```

Services:
- **Calq MCP**: `http://localhost:${MCP_PORT}/mcp` (default: 3000)
- **PostgreSQL**: Internal to Docker (port 5432)
- **ChromaDB**: `http://localhost:${CHROMA_PORT}` (default: 8000, internal to Docker)

### Option 2: Local Development

```bash
# 1. Start PostgreSQL and ChromaDB (required)
docker run -d --name postgres -p 5432:5432 \
  -e POSTGRES_USER=calq -e POSTGRES_PASSWORD=calq -e POSTGRES_DB=calq \
  postgres:16-alpine

docker run -d --name chromadb -p 8000:8000 chromadb/chroma:latest

# 2. Clone and install
git clone https://github.com/Calq-dev/calq-mcp.git
cd calq-mcp
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your API keys

# 4. Push database schema
npm run db:push

# 5. Start the server
node src/index.js
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes | PostgreSQL connection URL |
| `POSTGRES_PASSWORD` | No | PostgreSQL password for Docker (default: calq) |
| `VOYAGE_API_KEY` | Yes | Voyage AI API key for embeddings |
| `CHROMA_URL` | No | ChromaDB URL (default: `http://localhost:8000`) |
| `GITHUB_CLIENT_ID` | Yes | GitHub OAuth App client ID |
| `GITHUB_CLIENT_SECRET` | Yes | GitHub OAuth App client secret |
| `MCP_PORT` | No | Server port (default: 3000) |
| `OAUTH_CALLBACK_URL` | No | OAuth callback (default: `http://localhost:3000/oauth/callback`) |

### Database Management

Calq uses [Drizzle ORM](https://orm.drizzle.team) with PostgreSQL:

```bash
# Generate migrations from schema changes
npm run db:generate

# Apply migrations
npm run db:migrate

# Push schema directly (development)
npm run db:push

# Open Drizzle Studio
npm run db:studio
```

### GitHub OAuth Setup

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click "New OAuth App"
3. Fill in:
   - **Application name:** Calq
   - **Homepage URL:** `http://localhost:3000`
   - **Authorization callback URL:** `http://localhost:3000/oauth/github/callback`
4. Copy the Client ID and generate a Client Secret
5. Add both to your `.env` file

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "calq": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

When you first use Calq, Claude Desktop will open a browser for GitHub authentication.

## Tools

### Time Tracking

| Tool | Description |
|------|-------------|
| `commit` | Log time with message, project, and optional date |
| `start` | Start a timer for a project |
| `stop` | Stop timer and log the time |
| `timer_status` | Check if a timer is running |
| `cancel_timer` | Discard timer without logging |
| `delete` | Delete a time entry |
| `edit` | Modify an existing entry |

### Summaries

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects with total time |
| `list_projects_detailed` | Projects with client info and values |
| `get_project_summary` | Detailed summary for a project |
| `get_today_summary` | Today's time by project |
| `get_weekly_summary` | This week's time by day |
| `get_unbilled` | Unbilled time summary |
| `get_invoice_summary` | Unbilled time by client with values |

### Memory

| Tool | Description |
|------|-------------|
| `remember` | Store a memory (personal/shared, linked to project/client) |
| `idea` | Quick capture an idea |
| `recall` | Search memories semantically |
| `search_entries` | Search time entries semantically |
| `list_memories` | List all memories |
| `list_ideas` | List all captured ideas |
| `forget` | Delete a memory |

### Clients & Projects

| Tool | Description |
|------|-------------|
| `add_client` | Add a new client |
| `list_clients` | List all clients |
| `configure_project` | Create/update project with client and hourly rate |

### Users

| Tool | Description |
|------|-------------|
| `whoami` | Show current user info |
| `list_users` | List all users (admin only) |
| `set_user_role` | Change user role (admin only) |
| `team_summary` | Team activity summary |

## Usage Examples

```
"Start timing the website project"
"Stop - finished the navbar"
"Log 2 hours to API work yesterday: implemented auth"
"Remember: client wants deadline moved to January"
"Recall: what did the client say about deadlines?"
"What's my unbilled time for Acme Corp?"
"Configure project website with client Acme and rate 95"
```

## Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│   Calq MCP      │────▶│    ChromaDB     │
│                 │     │  (Port 3000)    │     │  (Port 8000)    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │   PostgreSQL    │
                        │  (Port 5432)    │
                        └─────────────────┘
```

- **PostgreSQL** - Source of truth for structured data (entries, projects, users)
- **ChromaDB** - Vector store for semantic search (memories, entry embeddings)
- **Drizzle ORM** - Type-safe database access layer

## Data Storage

In Docker, data is persisted via volumes:
- `calq-data` - Application data
- `postgres-data` - PostgreSQL database
- `chroma-data` - ChromaDB embeddings

## License

MIT