jira-tempo-mcp

MCP server for self-hosted Jira (Server / Data Center) + Tempo Timesheets 4. Track time, list worklogs, and generate weekly reports — all from your AI agent (Copilot, Claude, etc.) via the Model Context Protocol.

📖 Русская версия: README.ru.md

📚 Documentation

📋 Features

The flat list of all 19 tools is below. For a grouped capability map — reading, time tracking, template decomposition, reports, CLI, agent — see docs/features.md.

Since v0.2.0 the server supports team reports (per-user aggregation with rate-limiting) and custom report templates (Jinja2 sandbox + opt-in Python). Since v0.3.0 all report generators support three output formats: txt (plain text), md (Markdown with tables and emojis), and json (structured JSON). See docs/reports.md for details.

See docs/api.md for the full tool reference with parameters and examples.

🚀 Quick start

Get up and running in under a minute:

Install (one command):

curl -fsSL https://raw.githubusercontent.com/Korrnals/jira-tempo-mcp/main/scripts/install.sh | bash

Or from the package indexes once published:

pip install jira-tempo-mcp      # PyPI
npm i -g jira-tempo-mcp         # npm wrapper (installs the Python package)

Then install the report specialist into your AI harness (or skip — the CLI lists supported ones):

jira-tempo-mcp install-specialist

Update to the latest version:

jira-tempo-mcp update    # pip upgrade (wheel) — or git pull + reinstall (editable)

This downloads and runs the interactive installer, which:

• ✅ Checks Python 3.11+ and pip
• ✅ Clones the repo and creates a venv
• ✅ Installs the package
• ✅ Guides you through Jira credentials setup
• ✅ Registers the MCP server in VS Code (user + workspace)
• ✅ Installs the standalone JTM: Jira Tempo Reports Copilot Chat agent by default (skip with --no-agent) — see §JTM Agent for details

💡 Tip: The installer never requires sudo — everything lives in user space. It's idempotent: re-running updates without clobbering existing config.

Uninstall:

# Remove everything (MCP server + Copilot Chat agent + skill):
curl -fsSL https://raw.githubusercontent.com/Korrnals/jira-tempo-mcp/main/scripts/install.sh | bash -- --uninstall
# …or from a local clone:
python install.py uninstall

# Remove ONLY the Copilot Chat agent (keep the MCP server):
python install.py --uninstall-agent

The full uninstall removes the VS Code mcp.json entry, the Copilot Chat agent + skill + knowledge doc, and optionally the .env.local Jira credentials and the pip package (it asks before removing those). The agent-only removal leaves the MCP server fully functional — use it if you installed the agent but decided you do not want it.

Docker:

# Option A — docker run with an .env file (chmod 600, gitignored):
cp .env.example .env  # fill in JIRA_BASE_URL, JIRA_USER, JIRA_PAT
docker run -i --rm --env-file .env ghcr.io/korrnals/jira-tempo-mcp:0.6.3

# Option B — docker compose (uses docker-compose.yml at repo root):
docker compose up -d
docker compose logs -f jira-tempo-mcp
# drive the server via stdio:
docker compose run --rm -T jira-tempo-mcp

The image is published to ghcr for every release: ghcr.io/korrnals/jira-tempo-mcp:<version> and :latest. Pin to a version tag (e.g. :0.6.3) for reproducibility; use :latest to track the newest release.

⚠️ Warning: The install script URL works once the repository is public. Until then, clone manually and run python install.py.

cd jira-tempo-mcp
python install.py

git clone https://github.com/Korrnals/jira-tempo-mcp.git
cd jira-tempo-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
jira-tempo-mcp serve

docker run -i --rm \
  --env-file .env \
  ghcr.io/korrnals/jira-tempo-mcp:latest

⚙️ Configuration

All configuration is via environment variables. Required:

Optional: JIRA_TIMEZONE, TEMPO_API_TOKEN, LOG_LEVEL, JIRA_HTTP_TIMEOUT, and report-related vars (REPORT_*).

Full reference: docs/configuration.md.

🔌 MCP integration

The server runs over stdio and is registered in VS Code mcp.json:

{
  "servers": {
    "jira-tempo": {
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["-m", "jira_tempo_mcp.server"],
      "envFile": "/home/your-username/.config/Code/User/.env.local",
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_USER": "your-username",
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

💡 Tip: Always use absolute paths for envFile — ~ does not work in sandboxed environments (distrobox, snap, containers).

Wheel / pip install (pip install jira-tempo-mcp): point the entry at the console script instead — no PYTHONPATH, no repo checkout needed:

{
  "servers": {
    "jira-tempo": {
      "command": "/home/your-username/.local/bin/jira-tempo-mcp",
      "args": ["serve"],
      "envFile": "/home/your-username/.config/Code/User/.env.local"
    }
  }
}

Note: the install / uninstall subcommands need a git clone (they drive the repo's install.py); a wheel install is configured by hand as above.

Full guide: docs/mcp-integration.md.

jira-tempo-mcp                  # start the MCP server (default)
jira-tempo-mcp serve            # start the MCP server
jira-tempo-mcp install          # interactive installer
jira-tempo-mcp uninstall        # reverse the installation
jira-tempo-mcp update           # self-update (pip upgrade / git pull)
jira-tempo-mcp install-specialist  # install the JTM agent into AI harnesses
jira-tempo-mcp --version        # show version

make ci         # full quality gate — lint + typecheck + test + build
make lint       # ruff
make typecheck  # mypy
make test       # pytest
make build      # python -m build (sdist + wheel)

🤖 JTM Agent (standalone Copilot Chat agent)

This repo ships a standalone AI agent that produces Jira/Tempo worklog reports predictably by calling the jira-tempo MCP generators. It is IDE-agnostic in its knowledge, with a thin VS Code Copilot Chat wrapper for one-click report generation.

What installs where

python install.py installs the agent by default:

• ~/.copilot/agents/jtm-jira-tempo-reports.agent.md — the VS Code Copilot Chat agent.
• ~/.copilot/skills/jira-tempo-reports/SKILL.md — the VS Code-specific skill (interactive picker flow).
• ~/.copilot/skills/jira-tempo-reports/JTM_AGENT.md — the universal knowledge doc (7-type report matrix, scenarios, rules).

The wheel-installed package can re-install the specialist into this or other harnesses (Copilot Chat, ZCode, Claude Code, pi, Hermes, OpenCode — codex unsupported) at any time, no git clone needed. Skills-only harnesses (claude, pi, hermes, opencode) install no agents file — VS Code cross-scans the Claude agents dir, an extra agent file there would show a duplicate picker entry. update auto-refreshes the specialist into the recorded harnesses after each successful upgrade:

jira-tempo-mcp install-specialist            # all supported harnesses
jira-tempo-mcp install-specialist --remove   # uninstall

Full harness table and flags: docs/cli.md.

A loud announcement block at the end of install.py confirms the install. To skip the agent: python install.py --no-agent. To remove only the agent: python install.py --uninstall-agent.

VS Code Copilot Chat (one-click)

After install, open Copilot Chat, pick the agent JTM: Jira Tempo Reports, and click 📊 Недельный отчёт (по умолчанию) for the one-click weekly report (basic + txt + current week + current user). The agent uses a graphical picker (vscode_askQuestions) for ambiguity resolution.

{
  "jira-tempo": {
    "command": "/path/to/your/venv/bin/python",
    "args": ["-m", "jira_tempo_mcp.server"],
    "env": { "PYTHONPATH": "/path/to/this/repo/src" }
  }
}

What the agent does NOT do

• Jira write operations (create/update issues or worklogs) — read-only.
• Analytics beyond raw worklog aggregation (trends, forecasting) — out of scope.
• Custom template authoring (writing .py/.j2 template files) — out of scope.

See JTM_AGENT.md for the full 7-type report matrix, parameter semantics, and work scenarios.

🎨 Custom templates

Since v0.2.0 jira-tempo-mcp supports custom report templates. Drop a .j2 file in a directory and it becomes selectable by name — no code change, no restart beyond reloading the MCP server config.

Quickstart (3 steps)

1. Create the template directory:

   mkdir -p ~/.config/jira-tempo-mcp/templates/
   

2. Add a .j2 template. Copy the ready-made example from this repo as a starting point:

   cp examples/templates/standup.j2 ~/.config/jira-tempo-mcp/templates/
   

3. Generate a report with it via the MCP tools:

   • list_report_templates — see available templates (builtin + custom, with type Jinja2/Python).
   • generate_weekly_report(template="standup") — generate with the chosen template.

Preview before generating

The preview_report_template tool renders a template on built-in mock worklogs — no Jira/Tempo call, no file written. Three sample-data profiles are available:

preview_report_template(template_name="standup", sample_data="default")

📖 Full author reference (context variables, worklog fields, Jinja2 filters, Python protocol, security model): docs/templates.md. For builtin template examples and the rendered-output gallery, see docs/reports.md.

License

MIT

🛠 CI / Релизы — кластерный конвейер release-pipeline

Этот проект подключён к общему кластерному конвейеру релизов (Korrnals/release-pipeline, K3s abyss-ai-agent, namespace release-pipeline). GitHub Actions не используется (биллинг аккаунта заблокирован) — конвейер и есть штатный путь релизов. Релизный артефакт подписывается трёхслойно: SHA256 → SBOM → cosign → GPG.

Релиз новой версии:

1. VERSION → релизный коммит (конвенция репо) → тег vX.Y.Z → push.
2. Обновить версию проекта в projects[] файла ~/.cache/release-pipeline-values.yaml и применить:

   helm upgrade --install release-pipeline \
     ~/LABs/Projects/Project-Umbra/release-pipeline/chart/release-pipeline \
     --kube-context abyss-ai-agent -n release-pipeline \
     -f ~/.cache/release-pipeline-values.yaml
   

3. Наблюдение: kubectl --context abyss-ai-agent -n release-pipeline get jobs, логи: kubectl ... logs -f job/release-<proj>-<ver>.

Подробности (типы проектов, kaniko-контейнеры, teardown): README конвейера.