Servidor MCP de Freedcamp

Un servidor del Protocolo de Contexto de Modelo (MCP) que envuelve la API REST de Freedcamp. Permite que cualquier cliente LLM compatible con MCP (Claude Code, Claude Desktop, etc.) gestione proyectos, tareas, usuarios y comentarios de Freedcamp mediante lenguaje natural.

Características

• 17 herramientas que cubren proyectos, tareas, usuarios, comentarios y comprobaciones de estado

• Autenticación HMAC-SHA1: el secreto de la API nunca sale del servidor; solo se envía un hash firmado por solicitud

• Resolución de nombres: pase nombres de usuario, correos electrónicos o nombres de proyectos en lugar de IDs numéricos sin procesar; el servidor los resuelve automáticamente con almacenamiento en caché basado en TTL

• Limitación de campos: solicite solo los campos que necesite con notación de puntos (id,title,comments.created_ts) para reducir el tamaño de la respuesta

• Mapeo de etiquetas de estado: acepta cadenas legibles por humanos como "in progress" en lugar de códigos numéricos

• Filtrado de respuestas: los campos internos de la API se eliminan automáticamente de las respuestas

• Apagado elegante: finaliza las solicitudes en curso antes de salir

• Reintento + retroceso: reintenta en errores 429 y 5xx con retroceso exponencial

• Sin paso de compilación: ejecuta TypeScript directamente a través de tsx

Related MCP server: toggl-mcp

Requisitos previos

• Node.js >= 18

• Una cuenta de Freedcamp con credenciales de API (Configuración → API)

Instalación

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

Configuración

Opción A: archivo .env

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

Opción B: configuración de MCP para Claude Code

No se necesita archivo .env: pase las credenciales como variables de entorno:

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

Variables de entorno

Ejecución

Con Claude Code (recomendado)

Después de agregar el servidor MCP con claude mcp add, simplemente inicie una conversación. Claude llamará a las herramientas automáticamente cuando sea necesario.

Con el Inspector MCP

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

Abre una interfaz de navegador donde puede llamar a cada herramienta e inspeccionar las respuestas.

Directo (stdio)

npx tsx scripts/mcp-server.ts

El servidor escucha en stdin/stdout usando el transporte stdio de MCP. El proceso anfitrión (Claude Code, Claude Desktop) gestiona su ciclo de vida.

Herramientas

Salud

Proyectos

Tareas

Usuarios

Comentarios

Resolución de nombres

La mayoría de los parámetros de ID aceptan nombres, correos electrónicos o IDs numéricos. Ejemplos:

• project_id: "Marketing" — se resuelve al ID numérico del proyecto

• assigned_to_id: "alice@example.com" — se resuelve al ID numérico del usuario

• assigned_to_id: ["Alice", 42] — se aceptan listas mixtas

Los resultados de la resolución se almacenan en caché con un TTL configurable (CACHE_TTL_MS).

Mapeo de estados

El estado de la tarea acepta tanto códigos numéricos como etiquetas de cadena:

Ejemplo: status: "in progress" es equivalente a status: 1.

Limitación de campos

Todas las herramientas de lista y obtención aceptan un parámetro fields con rutas de notación de puntos:

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

Esto reduce el tamaño de la respuesta y enfoca al LLM en los datos relevantes. Las matrices anidadas se conservan: comments.created_ts en [{created_ts: 1}] produce [{created_ts: 1}], no una lista plana.

Constantes de ID de aplicación (para comentarios)

Autenticación

El servidor utiliza autenticación HMAC-SHA1. En cada solicitud:

1. Se genera una marca de tiempo Unix

2. Se calcula un hash: HMAC-SHA1(secret, apiKey + timestamp)

3. Los parámetros de autenticación se envían como cadena de consulta: ?api_key=...&timestamp=...&hash=...

El secreto nunca viaja por la red. Al arrancar, el servidor valida las credenciales con GET /api_key/check.

Códigos de error

Desarrollo

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Watch mode
npx vitest

# Run server in dev mode
npm run dev

Pruebas

El conjunto de pruebas utiliza Vitest con respuestas de API simuladas:

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

Estructura del proyecto

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

Licencia

MIT