# Wakapi MCP

> The Wakapi MCP tracks your coding time and productivity across editors, languages, and projects. It gives you detailed stats on exactly where you spend your development hours, helping managers audit team activity or freelancers bill accurately.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** coding-stats, time-tracking, wakatime, developer-productivity, open-source

## Description

Need to know how much time you actually spent coding? This connector monitors your entire development workflow by pulling data from your Wakapi instance—a self-hosted alternative to WakaTime. You can get deep stats broken down by language and editor, fetch project summaries for specific date ranges, or just list every project you've ever worked on here. It’s built for developers who need an accurate picture of their time investment.

When your agent runs this MCP through Vinkius, the platform ensures that every data flow is visible in the Vinkius AI Analytics dashboard. This means you always know exactly which tools were called and what specific activity data was pulled—no black boxes here. It’s simply a way to let your agent read out your actual coding history so you can report time accurately for clients or just track personal growth.

## Tools

### send_heartbeats
Sends manual activity pings to keep the coding timeline current and accurate for reporting.

### list_projects
Returns an exhaustive list of all projects that have been tracked by the user.

### get_stats
Retrieves specific coding metrics, including languages and editors, for a user.

### get_summaries
Pulls a detailed overview of activity within defined date ranges or project scopes.

## Prompt Examples

**Prompt:** 
```
Show my coding stats for the last 7 days.
```

**Response:** 
```
I've retrieved your stats for the last week. You spent 24 hours coding, primarily in TypeScript (60%) using VS Code. Your most active project was 'mcp-server-wakapi'.
```

**Prompt:** 
```
List all my projects tracked in Wakapi.
```

**Response:** 
```
I found 12 projects in your Wakapi account. Some of the recent ones include: 'website-frontend', 'api-backend', and 'mobile-app-v2'. Would you like stats for any of these?
```

**Prompt:** 
```
Get a summary of my activity from 2023-10-01 to 2023-10-07.
```

**Response:** 
```
Generating summary for that week... You logged a total of 32 hours. Your peak activity was on Tuesday with 8 hours of work across 3 different projects.
```

## Capabilities

### Retrieve detailed performance statistics
Gets comprehensive metrics on the languages, editors, and operating systems used over a specific period of work.

### Generate activity reports by date range
Creates granular summaries of your coding efforts for defined time windows or individual projects.

### List all tracked development projects
Provides a clear inventory of every project you’ve recorded time against, useful for billing organization.

### Manually update activity timelines
Sends manual heartbeats to ensure your coding timeline remains accurate even if the primary tracking source fails.

## Use Cases

### Client Billing Dispute
The client asks for proof of hours worked last month. The developer prompts their agent: 'Get a summary of my activity from October 1st to October 31st.' The agent runs `get_summaries` and provides the total logged time, breaking it down by project.

### Team Performance Review
The engineering manager needs a high-level overview of what languages were most used across the department last quarter. They prompt: 'Show me coding stats for Q3.' The agent calls `get_stats` and provides a clear, aggregated language breakdown.

### Project Scope Definition
The dev team needs to know what projects are active but not currently tracked. They prompt: 'List all my old projects.' The agent runs `list_projects`, revealing dormant repositories that need re-evaluation.

### Debugging Tracking Gaps
The tracking system briefly went offline during a critical coding session. To prevent data loss, the developer manually sends an activity heartbeat using `send_heartbeats` to mark their continued work period accurately.

## Benefits

- Get specific breakdowns of where you spent your time. Use `get_stats` to see exactly what languages and editors dominated a given period, helping you justify skill sets.
- Stop guessing about project scope creep. The `list_projects` tool gives you an immediate inventory of every single repository or client effort tracked in Wakapi.
- Avoid manual reporting headaches. Asking for activity summaries via `get_summaries` pulls compiled data across dates, giving managers a quick pulse on team velocity.
- Ensure continuity when systems fail. Use `send_heartbeats` to manually log an active coding session if your primary tracking mechanism is down for any reason.
- Simplify billing reports. By combining `list_projects` and `get_summaries`, you can quickly prove time spent on client-specific deliverables, right from the AI agent.

## How It Works

The bottom line is, it lets your AI agent talk directly to your coding history record.

1. First, you connect your Wakapi API URL and key credentials to this MCP within Vinkius.
2. Next, you tell your AI agent what data you need—maybe 'Show me my stats for last month' or 'List all projects.'
3. The MCP executes the necessary tool call, pulls the activity log from Wakapi, and hands the raw data back to your agent.

## Frequently Asked Questions

**How do I use get_stats with Wakapi MCP?**
You ask your agent to 'Show my stats for last week.' The agent uses the `get_stats` tool, which returns a detailed breakdown of languages and editors used during that time.

**Can I track multiple projects with get_summaries?**
Yes. You can specify date ranges or even list several project names in your prompt to the agent, letting `get_summaries` compile a consolidated report for you.

**Do I have to run send_heartbeats often?**
No, but it's useful if your main tracking tool goes down temporarily. You use `send_heartbeats` just to manually log that you were still actively coding and need the time recorded.

**What is the difference between get_stats and get_summaries?**
Stats give granular, comparative metrics (like 'X hours in Python vs. Y hours in Rust'). Summaries give a total overview of activity for a given period.

**How do I handle permissions or scope when using `list_projects`?**
The MCP requires API credentials that grant read access to all tracked data. If a project isn't visible via `list_projects`, check your service key permissions first. The tool only shows what the associated Wakapi account has been granted visibility into.

**What happens if I run `get_stats` for a time period where no activity was recorded?**
The API returns a clear zero-data response rather than an error. You'll receive confirmation that the user spent 0 hours in the specified range, which is helpful for reporting accurate downtime.

**Can I use `send_heartbeats` to correct or modify existing time data?**
No; `send_heartbeats` only reports new activity and cannot change historical records. It acts as an additive log, ensuring that any gaps in your automated tracking are manually filled in.

**What credentials do I need to ensure `get_summaries` works across different time zones?**
You must provide a single API key with global read permissions. The tool handles the time zone conversion internally, so long as your initial query parameters are accurate.

**How can I see my coding statistics for the last 7 days?**
You can use the `get_stats` tool and specify 'last_7_days' as the range. The agent will return a breakdown of your languages, editors, and projects for that period.

**Can I get a list of all projects I have ever tracked in Wakapi?**
Yes! Use the `list_projects` tool. It will retrieve all project names associated with your account, allowing you to see the scope of your tracked work.

**Is it possible to track activity for a specific date range?**
Absolutely. Use the `get_summaries` tool by providing a 'start' and 'end' date in YYYY-MM-DD format. You can even filter this by a specific project name.