KF

karlost/freelomcp

Developer tools
10 stars 3 forks Quality 86 Trend 32MIT

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

Overview

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ů. - 🚀 pokrývajících 100% Freelo API v1 - ✅ - 207 unit testů + 82 real API testů - 🔧 - Všechny známé bugy opraveny - 📊 - Podpora pro pagination a advanced filters - 🔒 - HTTP Basic Authentication s API klíčem - 🎯 - Token limit fixes pro velké datasety - 📝 - Detailní popis všech tools - 🏷️ - Automatické behavioral hints (readOnly, destructive, idempotent) - 📋 - Zod schemas pro validaci všech API odpovědí - 🧩 - Tools organizovány v 19 modulech Nejjednodušší způsob jak začít používat Freelo MCP je přes npx - není potřeba nic instalovat! 1. - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json 4.

README

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

📊 Stav projektu

Metrika Hodnota
Celkem MCP tools 104
Funkčních tools 100%
Opravené bugy 16/16 (100%)
API pokrytí 100% Freelo API v1
Unit testy 207 (205 passed, 2 skipped)
Real API testy 82 passed, 0 failed
Testováno ✅ Kompletní validation

🚀 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": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}
  1. Restartujte Claude Desktop

  2. 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 [email protected] \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])" \
  -- npx -y freelo-mcp

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

  1. Refresh připojení:
/mcp
  1. 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
[email protected]
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0 ([email protected])
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": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

Claude Code konfigurace s lokální instalací:

claude mcp add freelo-mcp \
  --env [email protected] \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])" \
  -- 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": "[email protected]",
        "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: (po inicializaci)

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

Konfigurace prostředí:

PORT=3000
[email protected]
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ů

Feature Stdio Streamable HTTP SSE (Legacy)
Use Case CLI tools HTTP/web clients Legacy podpora
Status ✅ Aktivní ✅ Doporučeno ⚠️ Deprecated
Session Mgmt N/A ✅ Ano ✅ Ano
MCP Standard ✅ Ano ✅ Ano (2025-03-26) ❌ Starší spec
Endpoint stdio /mcp/v1/endpoint /sse
Protokol stdin/stdout HTTP GET/POST Server-Sent Events
Vhodné pro Desktop aplikace n8n, web apps, remote Migrace z legacy

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": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}
  1. Restart VS Code nebo reload window (Cmd/Ctrl + Shift + P → “Reload Window”)
  2. 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": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}
  1. 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": "[email protected]",
      "FREELO_API_KEY": "VAS_API_KLIC",
      "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
    }
  }
}
  1. 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": "[email protected]",
          "FREELO_API_KEY": "VAS_API_KLIC",
          "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
        }
      }
    ]
  }
}
  1. 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: [email protected]
      FREELO_API_KEY: VAS_API_KLIC
      FREELO_USER_AGENT: "FreeloMCP/3.0.0 ([email protected])"
  1. 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 [email protected]
ENV FREELO_API_KEY=VAS_API_KLIC
ENV FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])"
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)

Kategorie Počet Popis
Tasks 22 CRUD úkolů, reminders, public links, estimates
Projects 13 Správa projektů, šablony, archivace
Custom Fields 14 Vlastní pole, enum options, values
Labels 9 Vytváření, editace a správa štítků
Users 9 Správa uživatelů, out-of-office, invite
Invoices 6 Fakturace, reporty, označování
Tasklists 6 Správa tasklistů, workers, templates
Work Reports 5 CRUD work reports
Notes 5 CRUD poznámek v projektech
Time Tracking 4 Start/stop tracking, edit
Files 3 Upload, download, listing souborů
Comments 3 Komentáře na úkolech a souborech
Notifications 3 Získání a správa notifikací
Pinned Items 3 Připnuté položky v projektech
Subtasks 3 Vytváření a správa podúkolů
Filters 3 Custom filtry pro úkoly
Search 1 Elasticsearch fulltext
Events 1 Historie událostí
States 1 Získání stavů (active, archived, atd.)

🔥 Nejpoužívanější tools

🤖 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:

[email protected] \
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

🤝 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)

⚠️ 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

Made with ❤️ for Freelo community

Created and maintained with assistance from Claude Code by Anthropic

View the full README on GitHub

Install

npx -y freelo-mcp
New to MCP? Start with the mcpskill.org guide →

Configuration

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