# QSS GPS MCP

Add GPS goals and log time directly from Claude. No timesheets to open, no commands to run.

---

## Install (employees do this once)

Open Claude Desktop → **Settings → Developer → Edit Config** and paste:

```json
{
  "mcpServers": {
    "qss-gps": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/YOUR_ORG/qss-gps-mcp",
        "qss-gps-mcp"
      ]
    }
  }
}
```

Save the file and restart Claude Desktop. That's it — Claude Desktop downloads and runs the MCP automatically.

---

## First-time login (once per ~30 days)

The first time you use any GPS tool, Claude will tell you to connect first.
Ask Claude:

> "Connect my GPS account"

A **browser window will open** on your desktop showing the GPS login page. Log in with your GPS credentials. Once you see the dashboard, the window closes and you're connected. Claude will confirm.

The session lasts ~30 days. Claude will remind you when it expires.

---

## Daily use — adding tasks

Just tell Claude what you did:

> "Add a task to Zscaler today: Fixed the Jenkins pipeline timeout issue. 3 hours."

> "Log 1 hour for Aroris yesterday — daily standup call."

> "Add to AveriSource on June 24: Sprint planning and backlog grooming. 2 hours."

Claude creates the goal in GPS and logs the time automatically. A browser window may appear briefly — that's normal.

---

## Bulk backfill — filling a whole month

> "Fill Aroris goals for July 2026 — daily standup only, 1 hour per day."

> "Fill Zscaler for July 1–22 using my task log at ~/projects/zscaler/.claude/task-log/tasks.md — 8 hours per day."

Claude will:
1. Show you a preview of every day
2. Ask you to confirm
3. Insert goals (canary date first, then the rest)
4. Log time against each goal (canary first, then the rest)

---

## Available tools

| Tool | What it does |
|------|-------------|
| `save_gps_session` | Opens GPS login window — run once per ~30 days |
| `add_task` | Add one task — creates goal + logs time |
| `preview_goals` | Preview a date range without submitting anything |
| `create_goals` | Create GPS goals (`dry_run=True` by default) |
| `log_time` | Log time against goals (`dry_run=True` by default) |

---

## Task log format (for bulk backfill from a file)

```markdown
### 2026-07-01 — Fixed login timeout bug
**Done:** Found the JWT TTL was set to 15 min, changed to 8h. Deployed to staging.
---

### 2026-07-02 — Jenkins pipeline upgrade
**Done:** Upgraded Jenkins from 2.401 to 2.440, resolved plugin conflicts.
---
```

---

## Session storage

The GPS session is saved to `~/.config/qss-gps/storage_state.json` on your machine.
Delete this file to force a fresh login.

Idempotency files (so re-runs skip already-done dates) are also in `~/.config/qss-gps/`.

---

## Requirements

- **Claude Desktop** (macOS or Windows)
- **uv** — installed automatically with Claude Desktop on macOS, or install from [astral.sh/uv](https://astral.sh/uv)
- No Python install needed. No server to host. No commands to run.