Freelo MCP Server (Neoficiální)

Upozornění: Toto je neoficiální komunitní projekt a není přímo podporován společností Freelo.

MCP Server pro Freelo API v1 - kompletní implementace Model Context Protocol serveru pro komunikaci s Freelo API. Freelo je česká služba pro projektové řízení a správu úkolů.

✨ Vlastnosti

• 🚀 104 MCP tools pokrývajících 100% Freelo API v1

• ✅ Plně otestováno - 207 unit testů + 82 real API testů

• 🔧 Production-ready - Všechny známé bugy opraveny

• 📊 Smart filtering - Podpora pro pagination a advanced filters

• 🔒 Bezpečné - HTTP Basic Authentication s API klíčem

• 🎯 Optimalizováno - Token limit fixes pro velké datasety

• 📝 Kompletní dokumentace - Detailní popis všech tools

• 🏷️ MCP Annotations - Automatické behavioral hints (readOnly, destructive, idempotent)

• 📋 OutputSchema - Zod schemas pro validaci všech API odpovědí

• 🧩 Modulární architektura - Tools organizovány v 19 modulech

Related MCP server: todoist-api-mcp

📊 Stav projektu

🚀 Rychlý start

Instalace přes NPX (doporučeno)

Nejjednodušší způsob jak začít používat Freelo MCP je přes npx - není potřeba nic instalovat!

1️⃣ Pro Claude Desktop (Anthropic Desktop)

1. Najděte konfigurační soubor:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Přidejte Freelo MCP server do konfigurace:

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "vas@email.cz",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 (vas@email.cz)"
      }
    }
  }
}

3. Restartujte Claude Desktop

4. Ověření:

   • V Claude Desktop byste měli vidět 🔌 ikonu v dolním panelu

   • Zkuste: "Zobraz moje Freelo projekty"

2️⃣ Pro Claude Code (CLI)

1. Přidání MCP serveru jedním příkazem:

claude mcp add freelo-mcp \
  --env FREELO_EMAIL=vas@email.cz \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 (vas@email.cz)" \
  -- npx -y freelo-mcp

DŮLEŽITÉ: -- separátor odděluje Claude CLI options od příkazu MCP serveru!

2. Refresh připojení:

/mcp

3. Ověření:

Zkuste v Claude Code: "Zobraz moje Freelo projekty"

Alternativní instalace - Git clone

Pro vývoj nebo pokud chcete upravovat kód:

# Klonování repozitáře
git clone https://github.com/karlost/FreeloMCP.git
cd FreeloMCP

# Instalace závislostí
npm install

# Vytvoření .env souboru
cat > .env << EOF
FREELO_EMAIL=vas@email.cz
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0 (vas@email.cz)
EOF

# Spuštění MCP serveru
node mcp-server.js

Claude Desktop konfigurace s lokální instalací:

{
  "mcpServers": {
    "freelo": {
      "command": "node",
      "args": ["/absolutni/cesta/k/FreeloMCP/mcp-server.js"],
      "env": {
        "FREELO_EMAIL": "vas@email.cz",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 (vas@email.cz)"
      }
    }
  }
}

Claude Code konfigurace s lokální instalací:

claude mcp add freelo-mcp \
  --env FREELO_EMAIL=vas@email.cz \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 (vas@email.cz)" \
  -- node /absolutni/cesta/k/FreeloMCP/mcp-server.js

🚀 Transport Options

Freelo MCP Server podporuje tři transportní protokoly:

1. Stdio Transport (Default - CLI nástroje)

Pro Claude Desktop, Claude Code, Cline a další CLI-based MCP klienty.

Použití:

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "vas@email.cz",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0"
      }
    }
  }
}

2. Streamable HTTP Transport (⭐ Doporučeno pro HTTP klienty)

Moderní MCP-compliant HTTP transport pro webové aplikace, n8n, ElevenLabs Agents a vzdálený přístup.

Spuštění HTTP serveru:

# Základní použití
npm run mcp:http

# S vlastním portem
PORT=8080 npm run mcp:http

# Nebo přes npx
PORT=8080 npx -y freelo-mcp-http

Endpoint: http://localhost:3000/mcp/v1/endpoint

Požadované HTTP headery:

• MCP-Protocol-Version: 2025-03-26

• Accept: text/event-stream (pro GET requesty)

• Mcp-Session-Id: <session-id> (po inicializaci)

Health check: GET http://localhost:3000/health

Konfigurace prostředí:

PORT=3000
FREELO_EMAIL=vas@email.cz
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0

3. SSE Transport (⚠️ Deprecated)

Legacy Server-Sent Events transport. Používejte Streamable HTTP místo toho.

npm run mcp:sse

Endpoint: http://localhost:3000/sse

⚠️ Upozornění: SSE transport je deprecated od MCP specifikace 2025-03-26. Migrujte na Streamable HTTP transport. Viz MIGRATION_HTTP.md.

📡 Srovnání transportů

Konfigurace pro další MCP klienty

3️⃣ Cline (VS Code Extension)

1. Otevřete VS Code s nainstalovaným Cline

2. Otevřete MCP Settings v Cline (ikona hamburgeru → MCP Settings)

3. Upravte konfigurační soubor:

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "vas@email.cz",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 (vas@email.cz)"
      }
    }
  }
}

4. Restart VS Code nebo reload window (Cmd/Ctrl + Shift + P → "Reload Window")

5. Ověření: V Cline chat zkuste "Zobraz moje Freelo projekty"

4️⃣ Windsurf (Codeium)

Windsurf podporuje MCP přes stejný formát jako Claude Desktop:

1. Najděte konfigurační soubor:

   • macOS: ~/Library/Application Support/Windsurf/settings/mcp_config.json

   • Windows: %APPDATA%\Windsurf\settings\mcp_config.json

   • Linux: ~/.config/Windsurf/settings/mcp_config.json

2. Přidejte konfiguraci:

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "vas@email.cz",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 (vas@email.cz)"
      }
    }
  }
}

3. Restartujte Windsurf

5️⃣ Zed Editor

1. Otevřete Zed Settings (Cmd/Ctrl + ,)

2. Přejděte na "Language Models" → "Configure MCP Servers"

3. Přidejte konfiguraci:

{
  "freelo": {
    "command": "npx",
    "args": ["-y", "freelo-mcp"],
    "env": {
      "FREELO_EMAIL": "vas@email.cz",
      "FREELO_API_KEY": "VAS_API_KLIC",
      "FREELO_USER_AGENT": "FreeloMCP/3.0.0 (vas@email.cz)"
    }
  }
}

4. Restart Zed

6️⃣ Continue.dev (VS Code/JetBrains)

1. Otevřete Continue config soubor:

   • VS Code: .continue/config.json v home directory

   • JetBrains: stejné umístění

2. Přidejte MCP server:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "freelo",
        "command": "npx",
        "args": ["-y", "freelo-mcp"],
        "env": {
          "FREELO_EMAIL": "vas@email.cz",
          "FREELO_API_KEY": "VAS_API_KLIC",
          "FREELO_USER_AGENT": "FreeloMCP/3.0.0 (vas@email.cz)"
        }
      }
    ]
  }
}

3. Restart IDE

7️⃣ LibreChat

V LibreChat (self-hosted ChatGPT alternative):

1. Upravte librechat.yaml:

mcpServers:
  - name: freelo
    command: npx
    args:
      - "-y"
      - "freelo-mcp"
    env:
      FREELO_EMAIL: vas@email.cz
      FREELO_API_KEY: VAS_API_KLIC
      FREELO_USER_AGENT: "FreeloMCP/3.0.0 (vas@email.cz)"

2. Restart LibreChat kontejneru

8️⃣ n8n (Workflow Automation)

n8n vyžaduje SSE (Server-Sent Events) transport místo stdio. Freelo MCP poskytuje dedikovaný SSE server:

1. Spuštění SSE serveru:

Lokálně přes npx:

npx -y freelo-mcp-sse

Nebo pomocí npm scriptu po git clone:

npm run mcp:sse

Nebo s vlastním portem:

PORT=8080 npx -y freelo-mcp-sse

2. Konfigurace v n8n:

1. V n8n workflow přidejte MCP Client Tool node

2. V nastavení MCP Client vytvořte nové credentials:

   • Transport Type: SSE

   • SSE Endpoint URL: http://localhost:3000/sse

   • Message Endpoint URL: http://localhost:3000/message

3. Po připojení budete mít přístup ke všem 104 Freelo tools

3. Health check:

Ověřte, že server běží:

curl http://localhost:3000/health

Odpověď:

{
  "status": "ok",
  "service": "freelo-mcp-sse",
  "version": "3.0.0",
  "activeConnections": 0,
  "endpoints": {
    "sse": "/sse",
    "messages": "/message",
    "health": "/health"
  }
}

4. Docker deployment:

Pro production použití můžete vytvořit Docker kontejner:

FROM node:18-alpine
WORKDIR /app
RUN npm install -g freelo-mcp
ENV FREELO_EMAIL=vas@email.cz
ENV FREELO_API_KEY=VAS_API_KLIC
ENV FREELO_USER_AGENT="FreeloMCP/3.0.0 (vas@email.cz)"
ENV PORT=3000
EXPOSE 3000
CMD ["freelo-mcp-sse"]

docker build -t freelo-mcp-sse .
docker run -p 3000:3000 freelo-mcp-sse

Poznámky:

• SSE server podporuje multiple concurrent connections

• Každé připojení má vlastní session ID

• Session se automaticky vyčistí při odpojení klienta

• CORS je povoleno pro všechny origins

📚 Dostupné MCP Tools

Přehled podle kategorií (104 tools)

🔥 Nejpoužívanější tools

• get_projects - Získání vlastních aktivních projektů

• get_all_projects - Všechny projekty (vlastní i sdílené) s pagination

• get_project_details - Detail projektu včetně workers a tasklists

• get_invited_projects - Projekty, kam jsem byl pozván

• get_archived_projects - Archivované projekty

• get_template_projects - Šablonové projekty s filtry

• get_user_projects - Projekty konkrétního uživatele

• get_project_workers - Seznam pracovníků na projektu

• get_project_manager_of - Projekty kde jsem PM

• get_project_tasklists - Všechny tasklisty v projektu

• create_project - Vytvoření nového projektu

• create_project_from_template - Vytvoření z šablony

• archive_project - Archivace projektu

• activate_project - Aktivace projektu

• delete_project - Smazání projektu

• invite_users_by_email - Pozvání uživatelů emailem

• invite_users_by_ids - Pozvání uživatelů podle ID

• remove_workers - Odstranění pracovníků z projektu

Listing & Details:

• get_all_tasks - Všechny úkoly s 14 filtry:

  • search_query - Fulltext vyhledávání

  • state_id - Podle stavu (active, finished)

  • projects_ids - Filtrace podle projektů (array)

  • tasklists_ids - Podle tasklistů (array)

  • order_by - Řazení (priority, name, date_add, date_edited_at)

  • order - Směr (asc, desc)

  • with_label / without_label - Podle štítků

  • no_due_date - Bez termínu

  • due_date_range - Rozsah termínů

  • finished_overdue - Dokončeno po termínu

  • finished_date_range - Rozsah dokončení

  • worker_id - Podle pracovníka

  • p - Stránkování (od 0)

• get_tasklist_tasks - Úkoly v konkrétním tasklistu

• get_finished_tasks - Dokončené úkoly

• get_task_details - Kompletní detail úkolu

• get_task_description - Popis úkolu

CRUD Operations:

• create_task - Vytvoření úkolu

• create_task_from_template - Z šablony

• edit_task - Úprava úkolu

• update_task_description - Aktualizace popisu

• move_task - Přesun do jiného tasklistu

• finish_task - Dokončení

• activate_task - Aktivace

• delete_task - Smazání

Advanced Features:

• create_task_reminder - Připomínka (✅ opraveno)

• delete_task_reminder - Smazání připomínky

• get_public_link - Veřejný odkaz

• delete_public_link - Smazání odkazu

• set_total_time_estimate - Odhad času (Premium - netestováno)

• delete_total_time_estimate - Smazání odhadu (Premium - netestováno)

• set_user_time_estimate - Odhad pro uživatele (Premium - netestováno)

• delete_user_time_estimate - Smazání odhadu uživatele (Premium - netestováno)

• get_all_files - Listing souborů s filtry:

  • projects_ids - Podle projektů

  • type - Typ (directory, link, file, document)

  • p - Pagination

• upload_file - Upload souboru (max 100MB)

  • Parametr filePath - Cesta k lokálnímu souboru (preferováno pro velké soubory)

  • Parametr fileData - Base64 encoded file (pro malé soubory / data v paměti)

  • Parametr fileName - Název souboru (povinný při fileData, volitelný při filePath)

• download_file - Stažení souboru podle UUID

Time Tracking:

• start_time_tracking - Spuštění trackingu

• stop_time_tracking - Zastavení trackingu

• edit_time_tracking - Úprava aktivního trackingu

Work Reports:

• get_work_reports - Získání work reports s filtry:

  • projects_ids - Podle projektů

  • users_ids - Podle uživatelů

  • tasks_labels - Podle štítků

  • date_reported_range - Rozsah dat

• create_work_report - Vytvoření reportu

• update_work_report - Aktualizace reportu

• delete_work_report - Smazání reportu

⚠️ Poznámka: Custom Fields jsou premium funkce Freelo (402 Payment Required). Tyto nástroje nejsou plně testované kvůli omezení tarifu.

• get_custom_field_types - Typy polí (text, number, date, bool, enum, link)

• get_custom_fields_by_project - Pole v projektu

• create_custom_field - Vytvoření pole (✅ opraveno - enum validation)

• rename_custom_field - Přejmenování

• delete_custom_field - Smazání

• restore_custom_field - Obnovení

• add_or_edit_field_value - Hodnota pole

• add_or_edit_enum_value - Enum hodnota

• delete_field_value - Smazání hodnoty

• get_enum_options - Enum možnosti

• create_enum_option - Nová enum možnost

Tasklists (5):

• get_project_tasklists, get_tasklist_details, get_assignable_workers

• create_tasklist, create_tasklist_from_template (✅ opraveno)

Users (6):

• get_users, get_out_of_office, set_out_of_office (✅ opraveno)

• delete_out_of_office, invite_users_by_email, invite_users_by_ids (✅ opraveno)

Subtasks (2):

• create_subtask, get_subtasks

Comments (3):

• create_comment, edit_comment, get_all_comments (s filtry + pagination)

Labels (9):

• create_task_labels, add_labels_to_task, remove_labels_from_task, find_available_labels

• edit_label, delete_label, add_label_to_project, remove_label_from_project

Invoices (4):

• get_issued_invoices, get_invoice_detail, download_invoice_reports, mark_as_invoiced

Notifications (3):

• get_all_notifications (s pagination), mark_notification_read, mark_notification_unread

Notes (4):

• create_note, get_note, update_note, delete_note

Pinned Items (3):

• get_pinned_items, pin_item (✅ opraveno), delete_pinned_item

Events (1):

• get_events - Historie s pokročilými filtry (7 parametrů + pagination)

Filters (3):

• get_custom_filters, get_tasks_by_filter_uuid, get_tasks_by_filter_name

States (1):

• get_all_states - Získání všech stavů (active, archived, template, finished)

Search (1):

• search_elasticsearch - Fulltext search napříč entitami

🤖 AI Agent Guide

Pro efektivní použití Freelo MCP s AI agenty (Claude, ChatGPT, atd.) si přečtěte AI_GUIDE.md.

Průvodce obsahuje:

• ✅ Quick Start Workflows - Nejčastější pracovní postupy

• 🔄 Data Flow Patterns - Jak správně propojit tools

• 🎯 Tool Selection Guide - Kdy použít který tool

• 💡 Best Practices - Optimalizace a tipy pro AI agenty

• 📊 Common Workflows - Hotové šablony pro časté úkoly

• ⚠️ Error Handling - Řešení běžných problémů

Pro AI agenty: AI_GUIDE.md poskytuje strukturované instrukce, příklady kódu a workflow patterns pro maximální efektivitu práce s Freelo API přes MCP.

🔧 Opravené bugy a vylepšení

Verze 2.0.0 - Kompletní validation a fixes

Token Limit Fixes (4 tools):

• ✅ get_all_tasks - Přidáno 14 filter parametrů + pagination

• ✅ get_events - Přidáno 7 filter parametrů + pagination

• ✅ get_all_comments - Přidáno 5 filter parametrů + pagination

• ✅ get_all_files - Přidáno 3 filter parametry + pagination

API Integration Fixes (16 bugů opraveno):

1. ✅ create_task_reminder - Transformace date → remind_at

2. ✅ invite_users_by_ids - Změna project_id → projects_ids (array)

3. ✅ set_out_of_office - Data wrapped v {out_of_office: {...}}

4. ✅ pin_item - Default link hodnota '#' místo null

5. ✅ create_tasklist_from_template - Flat struktura místo nested object

6. ✅ upload_file - Přidán import FormData z 'form-data' package

7. ✅ create_custom_field - is_required jako enum('yes','no') místo boolean

8. ✅ create_comment - Oprava parametru 'description' → 'content'

9. ✅ edit_comment - Správná struktura dat pro API

10. ✅ create_subtask - Oprava assignedTo parametru

11. ✅ create_task - Kompletní validace parametrů

Nové opravy ve v3.0.0: 12. ✅ add_labels_to_task - API používá { id } místo { uuid } 13. ✅ remove_labels_from_task - Stejný fix 14. ✅ create_comment - Přílohy přes files: [{ uuid }] místo attachments 15. ✅ edit_comment - Přílohy přes files: [{ uuid }] místo { download_url } 16. ✅ remove_workers - users_ids jako integer array + users_emails klíč

💡 Příklady použití

Základní operace s projekty

// Získání všech projektů
await get_all_projects()

// Detail konkrétního projektu
await get_project_details({ projectId: "197352" })

// Vytvoření nového projektu
await create_project({
  projectData: {
    name: "Nový projekt",
    currency_iso: "CZK"
  }
})

Práce s úkoly a filtry

// Všechny aktivní úkoly v projektu
await get_all_tasks({
  filters: {
    projects_ids: [197352],
    state_id: 1,
    order_by: "priority",
    order: "desc",
    p: 0
  }
})

// Hledání úkolů s konkrétním štítkem
await get_all_tasks({
  filters: {
    with_label: "urgent",
    no_due_date: false,
    p: 0
  }
})

// Úkoly dokončené po termínu
await get_all_tasks({
  filters: {
    finished_overdue: true,
    finished_date_range: {
      date_from: "2025-10-01",
      date_to: "2025-10-09"
    }
  }
})

Time Tracking workflow

// 1. Spustit tracking na úkolu
await start_time_tracking({ taskId: "25368707" })

// 2. Upravit popis
await edit_time_tracking({
  trackingData: {
    description: "Práce na feature XYZ"
  }
})

// 3. Zastavit a vytvořit work report
await stop_time_tracking()

Soubory

// Upload souboru z disku (preferováno pro velké soubory)
await upload_file({
  filePath: "/cesta/k/dokument.pdf"
})

// Upload souboru z base64 (pro malé soubory / data v paměti)
const base64Data = Buffer.from("obsah souboru").toString('base64')
await upload_file({
  fileName: "dokument.pdf",
  fileData: base64Data
})

// Listing souborů v projektu
await get_all_files({
  filters: {
    projects_ids: [197352],
    type: "file",
    p: 0
  }
})

🔒 Autentizace

Získání API klíče

1. Přihlaste se do Freelo

2. Přejděte do Nastavení → API

3. Vygenerujte nový API klíč

4. Zkopírujte klíč a uložte bezpečně

Bezpečnost

• ⚠️ Nikdy nesdílejte svůj API klíč veřejně

• ⚠️ Necommitujte .env soubor do gitu

• ✅ Používejte .gitignore pro ochranu credentials

• ✅ Pro production použijte environment variables

🧪 Testování

Unit testy

# Spuštění všech testů (207 testů, 7 test suites)
npm test

# Konkrétní test suite
npm test -- tests/mcp-tools-simple.test.js

# S code coverage
npm test -- --coverage

Real API testy

Kompletní test proti Freelo API pokrývající všech 104 tools:

FREELO_EMAIL=vas@email.cz \
FREELO_API_KEY=VAS_API_KLIC \
FREELO_USER_AGENT=freelo-mcp \
node tests/real-api-full-test.js

Výsledky: 82 passed, 0 failed, 33 skipped (skips = premium funkce, chybějící data)

🐛 Troubleshooting

MCP server se nepřipojí

Řešení:

1. Zkontrolujte, že Node.js verze ≥ 18.0.0: node --version

2. Ověřte env variables v konfiguraci

3. Restartujte Claude Code: /mcp

4. Zkontrolujte logy: ps aux | grep mcp-server

Chyba "Payment required (402)"

Některé funkce jsou premium:

• Custom Fields operace

• Time estimates (set/delete)

Řešení: Upgrade Freelo plánu nebo použití jiných tools.

Token limit exceeded

Pro velké datasety použijte pagination:

// Místo
await get_all_tasks()

// Použijte
await get_all_tasks({
  filters: {
    projects_ids: [specificProjectId],
    p: 0  // první stránka
  }
})

Server se restartuje pořád

Důvod: ES6 moduly jsou cachovány v Node.js procesu.

Řešení:

# Najděte proces
ps aux | grep "[n]ode.*mcp-server.js"

# Zabijte proces (nahraďte PID)
kill -9 PID

# Refresh v Claude Code
/mcp

📖 Další zdroje

• Freelo API Dokumentace

• Model Context Protocol Spec

• Claude Code Docs

🤝 Přispívání

Příspěvky jsou vítány!

1. Forkněte repozitář

2. Vytvořte feature branch (git checkout -b feature/AmazingFeature)

3. Commitněte změny (git commit -m 'Add AmazingFeature')

4. Pushněte branch (git push origin feature/AmazingFeature)

5. Otevřete Pull Request

📝 Changelog

v3.0.0 (2026-03-09) - Major Refactor & Complete Real API Validation! 🎯🧪

Modulární architektura:

• 🧩 19 tool modulů - Tools refaktorovány z monolitického mcp-server.js do samostatných modulů v tools/

• 📁 Nová struktura: tools/tasks.js, tools/projects.js, tools/labels.js, tools/comments.js, atd.

• 🔧 Sdílené utility: registerToolWithMetadata.js, paginationHelper.js, errorHandler.js

Nové tools (98 → 104):

• ➕ get_note - Získání detailu poznámky

• ➕ change_enum_option - Editace enum option

• ➕ force_delete_enum_option - Force smazání enum option

• ➕ get_invoice_reports_json - Invoice reporty v JSON

• ➕ get_assignable_workers - Přiřaditelní pracovníci na tasklist

• ➕ edit_label / delete_label / add_label_to_project / remove_label_from_project - Kompletní správa štítků

Bug fixy z real API testování (5 nových oprav):

• 🐛 add_labels_to_task - API používá { id } ne { uuid } pro štítky

• 🐛 remove_labels_from_task - Stejný fix jako add_labels_to_task

• 🐛 create_comment - Přílohy přes files: [{ uuid }] ne attachments

• 🐛 edit_comment - Přílohy přes files: [{ uuid }] ne { download_url }

• 🐛 remove_workers - users_ids jako integer array + users_emails klíč

Testování:

• ✅ 207 unit testů v 7 test suites (205 passed, 2 skipped)

• ✅ 82 real API testů proti živému Freelo API (0 failures)

• 🧪 Nový tests/real-api-full-test.js - kompletní real API test všech 104 tools

• 🔄 Retry logika pro API rate limiting (429)

• ⏭️ Auto-skip pro premium features (402)

v2.3.0 (2025-10-12) - Complete MCP Metadata Implementation! 🏷️📊

• ✨ NOVÁ FUNKCE: Implementovány MCP tool annotations + outputSchema pro všech 98 tools

• 🏷️ Behavioral Hints: Každý tool má automatické anotace:

  • readOnlyHint: true - 41 tools jen čtou data (bezpečné bez potvrzení)

  • destructiveHint: true - 14 tools mohou smazat data (vyžadují potvrzení)

  • idempotentHint: true - 18 tools lze bezpečně opakovat

  • openWorldHint: false - všechny tools používají jen Freelo API

• 📊 OutputSchema: Všech 98 tools má definované Zod schemas pro validaci výstupů

  • Založeno na oficiální freelo.apib API dokumentaci

  • Lepší pochopení struktury dat pro AI agenty

  • Type validation pro všechny API odpovědi

• 📝 Auto-generated Titles: Každý tool má lidsky čitelný název (e.g., "Get All Tasks")

• 🔧 Centralizovaná správa:

  • Nový utils/toolAnnotations.js pro behavioral hints

  • Nový utils/schemas.js pro kompletní Zod schemas knihovnu

  • Nový utils/registerToolWithMetadata.js pro automatické application

• ✅ 100% pokrytí: Všechny tools refaktorovány, žádné syntax errory

• 🧪 Kompletně otestováno: Nový test-annotations.js ověřuje správnost implementace

• 📚 Dokumentace: Nové soubory ANNOTATIONS_IMPLEMENTATION.md a TOOL_DESCRIPTIONS_ANALYSIS.md

• 🎯 Výhody pro uživatele:

  • Lepší UX v Claude Desktop (varování pro destructive operace)

  • Bezpečnější automatic retries pro idempotent tools

  • Rychlejší workflow (read-only tools bez extra potvrzení)

  • Přesnější parsování odpovědí pomocí schemas

v2.2.0 (2025-10-11) - AI Usability Upgrade! 🤖

• ✨ VÝZNAMNÁ AKTUALIZACE: Všech 98 tools vylepšeno pro lepší použití s AI agenty

• 📝 Tool Descriptions: Každý tool má nově detailní popis včetně:

  • Co tool dělá a kdy ho použít

  • Souvislosti s jinými tools (workflow návaznosti)

  • Varování pro destruktivní operace

  • Premium feature označení

• 🔧 Parameter Descriptions: Všechny parametry mají vylepšené popisy s:

  • Formáty a příklady hodnot (e.g., "197352", "2025-10-11")

  • Odkazy na source tools (odkud získat potřebná ID)

  • Rozlišení required vs optional parametrů

• 📚 Nový AI_GUIDE.md: Kompletní průvodce pro AI agenty obsahující:

  • Quick Start Workflows pro časté úkoly

  • Data Flow Patterns (jak správně řetězit tools)

  • Tool Selection Guide (kdy použít který tool)

  • Common Workflows s příklady kódu

  • Best Practices a Performance Tips

  • FAQ a Troubleshooting

• 🎯 Výsledek: AI agenti nyní mnohem lépe rozumí, jak a kdy použít jednotlivé tools

• ✅ Pokrytí: 100% tools upgradováno (Projects, Tasks, Custom Fields, Time Tracking, atd.)

v2.1.0 (2025-10-09) - SSE Transport pro n8n! 🚀

• ✨ NOVÁ FUNKCE: Přidán SSE (Server-Sent Events) transport pro n8n a jiné HTTP klienty

• 🌐 Nový bin příkaz: freelo-mcp-sse pro spuštění HTTP serveru

• 📡 SSE endpoints: /sse, /message, /health

• 🔄 Podpora multiple concurrent connections s session management

• 🐳 Docker-ready deployment s environment variables

• 🔧 Refaktoring mcp-server.js - export initializeMcpServer() funkce

• 📚 Rozšířená dokumentace o n8n setup a Docker deployment

• ✅ Kompletně otestováno - SSE server běží stabilně

v2.0.5 (2025-10-09) - NPX instalace funguje! 🎉

• 🐛 KRITICKÁ OPRAVA: Odstraněn isMainModule check který bránil npx spuštění

• ✅ NPX instalace plně funkční: npx -y freelo-mcp

• ✅ Bin soubor zjednodušen (611B → 144B)

• ✅ Odstraněny všechny console.log/warn z MCP serveru (porušovaly stdio protokol)

• ✅ Automatické spuštění při načtení modulu

• ✅ Funguje jak přes npx tak přímým spuštěním

• 📝 Aktualizovaná dokumentace s -- separátorem pro Claude Code

v2.0.0-2.0.4 (2025-10-09)

• ✅ Kompletní testování 98 MCP tools

• ✅ Opraveno 11 bugů v API integraci

• ✅ Přidány token limit fixes (4 tools s pagination)

• ✅ FormData fix pro upload_file

• ✅ Custom fields enum validation fix

• ✅ Tasklist from template fix

• ✅ 97%+ coverage všech funkcí

• ✅ Production-ready release

• 📚 Rozšířená dokumentace pro 7 MCP klientů

v1.0.0

• 🎉 Iniciální release

• 📦 98 MCP tools

• 🔧 REST API server

• 📚 Základní dokumentace

📄 Licence

Tento projekt je licencován pod MIT licencí.

👤 Autor

Chodeec (karlost)

• GitHub: @karlost

• NPM: freelo-mcp

⚠️ Disclaimer

Tento projekt není oficiálně podporován společností Freelo. Je to komunitní projekt vytvořený pro integraci Freelo s AI asistenty přes Model Context Protocol.

🌟 Podpora projektu

Pokud vám tento projekt pomohl, zvažte:

• ⭐ Přidání hvězdičky na GitHubu

• 🐛 Nahlášení bugů

• 💡 Návrhy na vylepšení

• 🤝 Pull requesty s novými features