Skip to main content
Glama
deenesjakoruzh
mahrukh-n8n

Freedcamp MCP Server

by mahrukh-n8n
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Freedcamp MCP 서버

Freedcamp REST API를 래핑하는 Model Context Protocol 서버입니다. MCP 호환 LLM 클라이언트(Claude Code, Claude Desktop 등)가 자연어를 통해 Freedcamp 프로젝트, 작업, 사용자 및 댓글을 관리할 수 있게 해줍니다.

기능

  • 17개의 도구: 프로젝트, 작업, 사용자, 댓글 및 상태 확인 지원

  • HMAC-SHA1 인증: API 시크릿은 서버를 떠나지 않으며, 요청당 서명된 해시만 전송됩니다.

  • 이름 확인: 원시 숫자 ID 대신 사용자 이름, 이메일 또는 프로젝트 이름을 전달하면 서버가 TTL 기반 캐싱을 통해 자동으로 확인합니다.

  • 필드 제한: 점 표기법(id,title,comments.created_ts)을 사용하여 필요한 필드만 요청함으로써 응답 크기를 줄입니다.

  • 상태 레이블 매핑: 숫자 코드 대신 "in progress"와 같은 사람이 읽을 수 있는 문자열을 허용합니다.

  • 응답 필터링: 내부 API 필드는 응답에서 자동으로 제거됩니다.

  • 우아한 종료: 종료 전 진행 중인 요청을 완료합니다.

  • 재시도 + 백오프: 429 및 5xx 오류 발생 시 지수 백오프를 사용하여 재시도합니다.

  • 빌드 단계 없음: tsx를 통해 TypeScript를 직접 실행합니다.

Related MCP server: toggl-mcp

사전 요구 사항

  • Node.js >= 18

  • API 자격 증명이 있는 Freedcamp 계정 (설정 → API)

설치

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

구성

옵션 A: .env 파일

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

옵션 B: Claude Code MCP 설정

.env 파일이 필요하지 않으며, 자격 증명을 환경 변수로 전달합니다:

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

환경 변수

변수

필수

기본값

설명

FREEDCAMP_API_KEY

예

—

Freedcamp API 키

FREEDCAMP_API_SECRET

예

—

Freedcamp API 시크릿

FREEDCAMP_API_URL

아니요

https://freedcamp.com

기본 URL (자체 호스팅용)

LOG_LEVEL

아니요

info

로그 레벨: debug, info, warn, error

REQUEST_TIMEOUT_MS

아니요

30000

HTTP 요청 타임아웃 (ms)

CACHE_TTL_MS

아니요

60000

이름 확인 캐시 TTL (ms)

MAX_CONCURRENT_REQUESTS

아니요

6

최대 동시 API 요청 수

실행

Claude Code 사용 (권장)

claude mcp add로 MCP 서버를 추가한 후 대화를 시작하세요. Claude가 필요할 때 자동으로 도구를 호출합니다.

MCP Inspector 사용

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

각 도구를 호출하고 응답을 검사할 수 있는 브라우저 UI를 엽니다.

직접 실행 (stdio)

npx tsx scripts/mcp-server.ts

서버는 MCP stdio 전송을 사용하여 stdin/stdout에서 수신 대기합니다. 호스트 프로세스(Claude Code, Claude Desktop)가 수명 주기를 관리합니다.

도구

상태 확인

도구

설명

health.check

API 자격 증명 및 연결 상태 확인

프로젝트

도구

쓰기

설명

project.list

프로젝트 목록 (페이지네이션, 정렬, 필드 제한 가능)

project.get

ID 또는 이름으로 프로젝트 가져오기

project.create

예

프로젝트 생성 (이름, 설명, 색상, 그룹, 멤버)

project.update

예

프로젝트 필드 업데이트 (부분 업데이트)

작업

도구

쓰기

설명

task.list

필터가 적용된 작업 목록 (담당자, 상태, 날짜 범위, 검색, 태그)

task.get

댓글 및 태그 세부 정보와 함께 ID로 작업 가져오기; task_url 주입

task.create

예

작업 생성 (상태 레이블 허용, 파일 첨부)

task.update

예

작업 필드 업데이트 (부분 업데이트, 파일 첨부)

task.delete

예

작업 삭제

task.assign

예

작업에 사용자 할당

사용자

도구

쓰기

설명

user.list

사용자 목록 (프로젝트별 필터링 가능)

user.get

ID, 이메일 또는 이름으로 사용자 가져오기

user.current

인증된 사용자의 프로필 가져오기

user.create

예

사용자 생성 (이메일, 비밀번호, 이름, OAuth)

user.update_current

예

인증된 사용자의 프로필 업데이트

댓글

도구

쓰기

설명

comment.add

예

댓글 추가 (item_id + app_id 필요)

comment.update

예

댓글 텍스트 업데이트

comment.delete

예

댓글 삭제

이름 확인

대부분의 ID 매개변수는 이름, 이메일 또는 숫자 ID를 허용합니다. 예시:

  • project_id: "Marketing" — 프로젝트의 숫자 ID로 확인됨

  • assigned_to_id: "alice@example.com" — 사용자의 숫자 ID로 확인됨

  • assigned_to_id: ["Alice", 42] — 혼합 목록 허용

확인 결과는 구성 가능한 TTL(CACHE_TTL_MS)로 캐시됩니다.

상태 매핑

작업 상태는 숫자 코드와 문자열 레이블을 모두 허용합니다:

코드

레이블

0

not started

1

in progress

2

completed

예시: status: "in progress"는 status: 1과 동일합니다.

필드 제한

모든 목록 및 가져오기 도구는 점 표기법 경로가 포함된 fields 매개변수를 허용합니다:

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

이는 응답 크기를 줄이고 LLM이 관련 데이터에 집중하도록 합니다. 중첩된 배열은 유지됩니다 — [{created_ts: 1}]에서 comments.created_ts는 평면 목록이 아닌 [{created_ts: 1}]을 반환합니다.

앱 ID 상수 (댓글용)

앱

ID

tasks

2

milestones

3

discussions

5

files

6

time

8

issue_tracker

9

인증

서버는 HMAC-SHA1 인증을 사용합니다. 모든 요청 시:

  1. Unix 타임스탬프가 생성됩니다.

  2. 해시가 계산됩니다: HMAC-SHA1(secret, apiKey + timestamp)

  3. 인증 매개변수가 쿼리 문자열로 전송됩니다: ?api_key=...&timestamp=...&hash=...

시크릿은 네트워크를 통해 전송되지 않습니다. 부팅 시 서버는 GET /api_key/check를 통해 자격 증명을 검증합니다.

오류 코드

코드

의미

PERMISSION_DENIED

잘못된 API 키/시크릿 또는 권한 부족

NOT_FOUND

요청된 리소스 또는 이름 확인 대상이 존재하지 않음

VALIDATION_ERROR

잘못된 입력 매개변수

CONFLICT

리소스가 이미 존재함

INTERNAL_ERROR

서버 오류, 속도 제한 또는 네트워크 실패

개발

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Watch mode
npx vitest

# Run server in dev mode
npm run dev

테스트

테스트 제품군은 모의 API 응답과 함께 Vitest를 사용합니다:

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

프로젝트 구조

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

라이선스

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers