Freelo MCP (Karlost)

MCPAI代理

提供方 未标注

AI代理 HTTP · 远程 未标注 社区 / 第三方
查看接入方式

全面解析FreelomcpMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器,Freelomcp能让AI助手访问实时数据、执行操作,为您提供更智能的工作体验和自动化解决方案。

一句话选型结论

按资料字段整理

Freelo MCP (Karlost) 属于AI代理类 MCP 服务器,HTTP · 远程,鉴权方式未标注,有可直接复制的远程端点配置。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式HTTP · 远程 鉴权未标注 部署方式远程部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

安装与配置

HTTP · 远程 未标注
连远程 HTTPS 端点,通常为 Streamable HTTP
npm install freelo-mcp\",

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • 远程端点依赖网络与服务方可用性,注意密钥与调用额度。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Freelo MCP (Karlost)当前 未标注 HTTP · 远程 远程部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类AI代理本站按上游分类展示
连接方式HTTP · 远程连远程 HTTPS 端点,通常为 Streamable HTTP
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Node.js本地安装时用到的包标识与运行时
部署类型远程部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

30.3 KB
来自项目仓库与上游目录的原文,未做删改

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:```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!

  1. 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)

  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:```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)"
      }
    }
  }
}
  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:```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)"
        }
      }
    ]
  }
}
  1. Restart IDE

7️⃣ LibreChat

V LibreChat (self-hosted ChatGPT alternative):

  1. 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:

  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ěží:```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!

  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


Made with ❤️ for Freelo community

Created and maintained with assistance from Claude Code by Anthropic

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Freelo MCP (Karlost) 怎么安装?

在客户端按下面的安装命令接入:npm install freelo-mcp\",。装完在客户端配置里引用同一个包或端点。

Freelo MCP (Karlost) 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Freelo MCP (Karlost) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Freelo MCP (Karlost) 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

Freelo MCP (Karlost) 能提供哪些能力?

资料显示能力标签包括 API代理、任务管理、JavaScript、项目管理、HTTP。具体工具清单以官方文档为准。

Freelo MCP (Karlost) 需要什么运行环境?

运行时为 Node.js;属于远程端点,不需要在本地装运行时。

Freelo MCP (Karlost) 是本地还是远程?

它是远程端点,连服务地址即可。传输方式为HTTP · 远程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。