Freedcamp MCP-Server

Ein Model Context Protocol-Server, der die Freedcamp REST-API kapselt. Er ermöglicht es jedem MCP-kompatiblen LLM-Client (Claude Code, Claude Desktop usw.), Freedcamp-Projekte, Aufgaben, Benutzer und Kommentare mittels natürlicher Sprache zu verwalten.

Funktionen

• 17 Tools für Projekte, Aufgaben, Benutzer, Kommentare und Gesundheitsprüfungen

• HMAC-SHA1-Authentifizierung — das API-Geheimnis verlässt niemals den Server; pro Anfrage wird nur ein signierter Hash gesendet

• Namensauflösung — übergeben Sie Benutzernamen, E-Mails oder Projektnamen anstelle von rohen numerischen IDs; der Server löst diese automatisch mit TTL-basiertem Caching auf

• Feldbegrenzung — fordern Sie nur die benötigten Felder mit Punktnotation (id,title,comments.created_ts) an, um die Antwortgröße zu reduzieren

• Status-Label-Mapping — akzeptiert menschenlesbare Zeichenfolgen wie "in progress" anstelle von numerischen Codes

• Antwortfilterung — interne API-Felder werden automatisch aus den Antworten entfernt

• Graceful Shutdown — laufende Anfragen werden vor dem Beenden abgeschlossen

• Wiederholung + Backoff — Wiederholungsversuche bei 429 und 5xx mit exponentiellem Backoff

• Kein Build-Schritt — führt TypeScript direkt über tsx aus

Related MCP server: toggl-mcp

Voraussetzungen

• Node.js >= 18

• Ein Freedcamp-Konto mit API-Anmeldedaten (Einstellungen → API)

Installation

git clone https://github.com/mahrukh-n8n/freedcampMCP.git
cd freedcampMCP
npm install

Konfiguration

Option A: .env-Datei

cp .env.example .env
# Edit .env with your Freedcamp API key and secret

Option B: Claude Code MCP-Einstellungen

Keine .env-Datei erforderlich — übergeben Sie Anmeldedaten als Umgebungsvariablen:

claude mcp add freedcamp npx tsx /path/to/freedcampMCP/scripts/mcp-server.ts \
  -e FREEDCAMP_API_KEY=your_key \
  -e FREEDCAMP_API_SECRET=your_secret

Umgebungsvariablen

Ausführung

Mit Claude Code (empfohlen)

Nachdem Sie den MCP-Server mit claude mcp add hinzugefügt haben, starten Sie einfach eine Konversation. Claude ruft die Tools bei Bedarf automatisch auf.

Mit MCP Inspector

npx @modelcontextprotocol/inspector npx tsx scripts/mcp-server.ts

Öffnet eine Browser-Benutzeroberfläche, in der Sie jedes Tool aufrufen und Antworten untersuchen können.

Direkt (stdio)

npx tsx scripts/mcp-server.ts

Der Server lauscht auf stdin/stdout unter Verwendung des MCP-stdio-Transports. Der Host-Prozess (Claude Code, Claude Desktop) verwaltet seinen Lebenszyklus.

Tools

Gesundheit

Projekte

Aufgaben

Benutzer

Kommentare

Namensauflösung

Die meisten ID-Parameter akzeptieren Namen, E-Mails oder numerische IDs. Beispiele:

• project_id: "Marketing" — wird in die numerische ID des Projekts aufgelöst

• assigned_to_id: "alice@example.com" — wird in die numerische ID des Benutzers aufgelöst

• assigned_to_id: ["Alice", 42] — gemischte Listen werden akzeptiert

Auflösungsergebnisse werden mit einer konfigurierbaren TTL (CACHE_TTL_MS) zwischengespeichert.

Status-Mapping

Der Aufgabenstatus akzeptiert sowohl numerische Codes als auch String-Labels:

Beispiel: status: "in progress" entspricht status: 1.

Feldbegrenzung

Alle Listen- und Abruf-Tools akzeptieren einen fields-Parameter mit Pfaden in Punktnotation:

fields="id,title,priority,comments.created_ts"

Dies reduziert die Antwortgröße und fokussiert das LLM auf relevante Daten. Verschachtelte Arrays bleiben erhalten — comments.created_ts bei [{created_ts: 1}] ergibt [{created_ts: 1}], keine flache Liste.

App-ID-Konstanten (für Kommentare)

Authentifizierung

Der Server verwendet HMAC-SHA1-Authentifizierung. Bei jeder Anfrage:

1. Ein Unix-Zeitstempel wird generiert

2. Ein Hash wird berechnet: HMAC-SHA1(secret, apiKey + timestamp)

3. Auth-Parameter werden als Query-String gesendet: ?api_key=...&timestamp=...&hash=...

Das Geheimnis wird niemals übertragen. Beim Start validiert der Server die Anmeldedaten mit GET /api_key/check.

Fehlercodes

Entwicklung

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Watch mode
npx vitest

# Run server in dev mode
npm run dev

Testen

Die Test-Suite verwendet Vitest mit gemockten API-Antworten:

npx vitest run           # Single run
npx vitest               # Watch mode
npx vitest --coverage    # With coverage

Projektstruktur

scripts/mcp-server.ts              Entry point
src/lib/freedcamp/
  api-client.ts                    HTTP client with HMAC auth, retry, filtering
  register-tools.ts                Wire all tools to the MCP registry
  auth/hmac.ts                     HMAC-SHA1 computation
  auth/hmac-validator.ts           Boot-time credential validation
  tools/
    health.ts                      health.check
    projects.ts                    project.list/get/create/update
    tasks.ts                       task.list/get/create/update/delete/assign
    users.ts                       user.list/get/current/create/update_current
    comments.ts                    comment.add/update/delete
  utils/
    name-resolver.ts               Name/email → ID resolution with caching
    response-filter.ts             Strip internal fields from API responses
    field-limiter.ts               Dot-notation field extraction
    date-utils.ts                  Date validation and formatting
    resolution-cache.ts            TTL-based LRU cache
    logger.ts                      Structured logging with verbose mode
    validation.ts                  Input validation helpers
src/modules/mcp/
  registry/tool-registry.ts        MCP tool registry
  services/create-mcp-server.ts    MCP server factory
  services/stdio-transport.ts      Stdio transport
  types.ts                         MCP result types
  utils/serialize.ts               Result envelope helpers (dataResult, commitResult, etc.)

Lizenz

MIT