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)
-
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 -
Přidejte Freelo MCP server do konfigurace:```json
{
"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:**```bash
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!
- Refresh připojení:```bash
/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:```bash
# 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í:```json
{
"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í:**```bash
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í:```json
{
"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:**```bash
# 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í:```bash
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.**```bash
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)
- Otevřete VS Code s nainstalovaným Cline
- Otevřete MCP Settings v Cline (ikona hamburgeru → MCP Settings)
- Upravte konfigurační soubor:```json
{
"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:**```json
{
"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)"
}
}
}
}
- Restartujte Windsurf
5️⃣ Zed Editor
- Otevřete Zed Settings (Cmd/Ctrl + ,)
- Přejděte na "Language Models" → "Configure MCP Servers"
- Přidejte konfiguraci:```json
{
"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:**```json
{
"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)"
}
}
]
}
}
- Restart IDE
7️⃣ LibreChat
V LibreChat (self-hosted ChatGPT alternative):
- Upravte
librechat.yaml:```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:```bash
npx -y freelo-mcp-sse
Nebo pomocí npm scriptu po git clone:```bash
npm run mcp:sse
Nebo s vlastním portem:```bash
PORT=8080 npx -y freelo-mcp-sse
2. Konfigurace v n8n:
- V n8n workflow přidejte MCP Client Tool node
-
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 -
Po připojení budete mít přístup ke všem 104 Freelo tools
3. Health check:
Ověřte, že server běží:```bash
curl http://localhost:3000/health
Odpověď:```json
{
"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:```dockerfile
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"]
``````bash
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
Projects (18 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
Tasks (19 tools) - s pokročilými filtry
**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)
Files (3 tools) - Upload & Download
- `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 & Work Reports (7 tools)
**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
Custom Fields (11 tools) - Premium Feature
> ⚠️ **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
Ostatní kategorie
**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```javascript
// 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```javascript
// 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```javascript
// 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```javascript
// 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```bash
# 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:```bash
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:```javascript
// 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í:```bash
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!
- Forkněte repozitář
- Vytvořte feature branch (
git checkout -b feature/AmazingFeature) - Commitněte změny (
git commit -m 'Add AmazingFeature') - Pushněte branch (
git push origin feature/AmazingFeature) - 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ě opakovatopenWorldHint: 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.jspro behavioral hints - Nový
utils/schemas.jspro kompletní Zod schemas knihovnu - Nový
utils/registerToolWithMetadata.jspro 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-ssepro 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
isMainModulecheck 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
Made with ❤️ for Freelo community
Created and maintained with assistance from Claude Code by Anthropic
