goalslot-mcp

GoalSlot용 MCP 서버입니다. AI 어시스턴트에게 목표, 작업, 주간 일정 템플릿, 시간 추적, 공유 타이머, 보고서, 메모, 저널을 자신의 GoalSlot 계정으로 다룰 수 있는 도구를 제공합니다.

stdio로 실행되므로 모든 MCP 호스트가 실행할 수 있습니다. 모델이 도구를 잘 사용하는 방법을 가르치는 네 가지 스킬이 포함되어 있습니다.

설치

먼저 goalslot CLI에 로그인해야 합니다. 이 서버는 CLI가 작성한 자격 증명을 읽기 때문입니다. 자체적으로 로그인 흐름을 실행하지 않습니다.

npm install -g goalslot-cli
goalslot login

그런 다음 Claude Code에 MCP 서버를 추가합니다:

claude mcp add goalslot -- npx -y goalslot-mcp

Claude Desktop 또는 JSON 구성을 사용하는 모든 호스트의 경우:

{
  "mcpServers": {
    "goalslot": {
      "command": "npx",
      "args": ["-y", "goalslot-mcp"]
    }
  }
}

작동하는지 확인합니다:

npx -y goalslot-mcp --list-tools

이 패키지는 아직 npm에 게시되지 않았습니다. 게시될 때까지 소스에서 설치하세요: 저장소를 클론하고 npm install && npm run build를 실행한 다음 호스트를 node /path/to/goalslot-mcp/dist/cli.js로 지정하세요.

Related MCP server: GoHighLevel MCP Server

인증 작동 방식

이 서버에는 로그인 흐름이 없습니다. stdio가 프로토콜 채널이므로 서버는 어떤 것도 프롬프트할 수 없으며, 모델에게 토큰을 처리하도록 요청하는 것은 더 나쁩니다. 이미 머신에 존재하는 자격 증명을 읽습니다.

해결 순서:

1. 환경 변수 GOALSLOT_ACCESS_TOKEN (설정되어 있고 비어 있지 않은 경우).

2. $GOALSLOT_CONFIG_DIR/credentials.json.

3. Windows의 %APPDATA%\goalslot\credentials.json.

4. $XDG_CONFIG_HOME/goalslot/credentials.json, 그 외에는 ~/.config/goalslot/credentials.json.

이 파일은 goalslot login이 작성하며 CLI와 공유됩니다. 형태는 다음과 같습니다:

{
  "version": 1,
  "apiBaseUrl": "https://api.goalslot.io/api",
  "apiUrl": "https://api.goalslot.io/api",
  "accessToken": "<jwt>",
  "refreshToken": "gsl_rt_...",
  "accessTokenExpiresAt": "2026-08-25T12:00:00.000Z",
  "refreshTokenExpiresAt": "2026-11-23T00:00:00.000Z",
  "tokenId": "<uuid>",
  "scopes": ["full"],
  "user": { "id": "...", "email": "..." },
  "defaultTimezone": "Asia/Karachi",
  "weekStartsOn": 1
}

apiBaseUrl과 apiUrl은 모두 읽고 동일한 값으로 작성되므로 CLI와 이 서버가 서로 덮어쓰지 않습니다. 알 수 없는 키는 다시 쓰기 후에도 유지됩니다.

CLI 토큰은 typ: "cli" 및 cid 클레임(해지 가능한 토큰 행을 나타냄)을 포함하는 일반 Bearer JWT이며, 모든 일반 API 경로가 이를 허용합니다. 액세스 토큰은 1시간 동안 유효합니다. 401이 발생하면 이 서버는 POST /api/auth/cli/token/refresh에 대해 리프레시 토큰을 회전시키고, 새 쌍을 사용하기 전에 디스크에 원자적으로 기록한 다음 원래 요청을 한 번 재생합니다. 회전은 단일 실행(single-flight)입니다: 리프레시 토큰은 일회용이며, 회전된 토큰을 재생하면 전체 자격 증명이 해지되므로 동시에 두 번의 리프레시가 발생하면 영구 로그아웃이 됩니다.

어떤 수준의 로그에도 토큰, 헤더 또는 Authorization 줄이 기록되지 않습니다.

자격 증명이 없거나 만료된 경우, 모든 도구는 구조화된 NOT_AUTHENTICATED 또는 SESSION_EXPIRED를 반환하여 모델에게 goalslot login을 실행하도록 안내합니다. 토큰을 붙여넣도록 요청하지 않습니다.

헤드리스 및 CI

GOALSLOT_ACCESS_TOKEN은 파일을 완전히 대체합니다. 리프레시가 작동하도록 하려면 GOALSLOT_REFRESH_TOKEN과 함께 사용하세요. 리프레시 토큰이 없으면 리프레시가 비활성화되고 1시간 액세스 토큰이 만료되면 세션이 종료됩니다. 장기 실행 작업의 경우 GOALSLOT_CONFIG_DIR을 설정하고 서버가 파일을 관리하도록 하세요.

도구

읽기 도구 9개와 쓰기 도구 9개. 읽기 도구는 자유롭게 호출해도 안전하며 readOnlyHint로 주석 처리되어 있습니다. 모든 쓰기 도구의 설명은 WRITES.로 시작하며, 여기에 노출된 어떤 것도 사용자 데이터를 삭제하지 않습니다.

읽기

쓰기

의도적으로 도구로 만들지 않은 것

목표, 작업 및 시간 항목 삭제; 전체 일정 지우기; 공개 또는 다른 사람과 공유; AI 코치 채팅 엔드포인트; 청구 및 계정 설정; 템플릿 가져오기. 연쇄 효과가 있는 삭제 및 개인 데이터를 게시하는 모든 것은 에이전트가 루프에서 호출할 수 있는 곳이 아니라 사람이 직접 입력하는 곳에 속합니다. GoalSlot 앱 또는 CLI를 사용하세요.

도구가 적용하는 규칙

• 기간은 정수 분이며, 항상 durationMinutes로 명명되고 절대 duration으로 명명되지 않습니다. 읽기에서도 durationHours를 표시용 부동 소수점으로 반환합니다. 목표의 targetHours는 유일한 예외입니다.

• 날짜는 YYYY-MM-DD 형식이며 시간이 포함되면 경계에서 거부됩니다. "오늘"은 UTC ISO 조각이 아닌 사용자 시간대에서 계산됩니다.

• 일정은 반복되는 주간 템플릿이며 날짜가 있는 이벤트가 아닙니다. 관련 도구 설명마다 명시되어 있습니다.

• dayOfWeek는 일요일 우선(0 = 일요일)이며, 주간 보고서가 사용하는 월요일 우선 순서와 다릅니다. 둘 다 인라인으로 표시되고 모든 응답에는 dayName이 포함됩니다.

• 주간 버킷은 API의 저장된 dayOfWeek 열(API 서버 시간대에서 파생되어 하루 차이가 날 수 있음)이 아닌 항목 날짜에서 다시 계산됩니다.

오류

실패는 isError: true와 함께 하나의 JSON 객체로 반환됩니다:

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "You've reached your FREE plan limit for goals.",
    "httpStatus": 403,
    "retryable": false,
    "remedy": "The account is at its goal limit. Ask the user to pause a goal with update_goal (status PAUSED), delete one from the CLI, or upgrade. Do not retry.",
    "details": { "plan": "FREE", "limitType": "goals" }
  }
}

remedy는 모델을 위한 명령형으로 작성됩니다. 코드: NOT_AUTHENTICATED, SESSION_EXPIRED, PLAN_LIMIT, FORBIDDEN, SCHEDULE_CONFLICT, INVALID_INPUT, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, WRITE_BUDGET_EXCEEDED, READ_ONLY_MODE, TIMER_ALREADY_RUNNING, NO_TIMER_RUNNING.

스킬

skills/에 네 가지 스킬이 포함되어 있습니다. 도구 설명이 담을 수 없는 판단을 제공합니다: 호출 순서, 쓰기 전에 확인할 사항, 말하지 말아야 할 것.

Claude Code에 설치하려면 디렉터리를 스킬 폴더로 복사하세요:

# macOS and Linux
cp -r "$(npm root -g)/goalslot-mcp/skills/"* ~/.claude/skills/

# Windows PowerShell
Copy-Item "$(npm root -g)\goalslot-mcp\skills\*" "$env:USERPROFILE\.claude\skills\" -Recurse

클론에서 복사하는 경우 저장소의 skills/*를 복사하세요. 프로젝트 범위도 작동합니다: 저장소 내 .claude/skills/에 넣으세요.

구성

HTTP 전송

선택 사항이며 플래그 뒤에 있습니다:

npx -y goalslot-mcp --http --port 7801

동일한 도구 레지스트리를 http://127.0.0.1:7801/mcp에서 스트리밍 가능한 HTTP 전송으로 무상태로 제공합니다.

이것은 단일 사용자 및 로컬 전용입니다. 모든 요청은 이 머신의 GoalSlot 자격 증명으로 처리됩니다. 호출자별 인증, OAuth 및 토큰 보관이 없으므로 포트에 도달할 수 있는 사람은 누구나 계정을 읽고 쓸 수 있습니다. 루프백에 바인딩되며 그 상태를 유지해야 합니다. goal-slot-api#55에서 추적되는 호스팅된 다중 테넌트 MCP 서버가 아닙니다. 그 서버는 실제 OAuth 흐름과 사용자별 토큰 저장이 필요하며, 이는 별도의 작업입니다.

stdio가 지원되는 경로입니다.

개발

npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --list-tools

TypeScript strict, ESM, Node 20 이상. 테스트는 스텁된 fetch를 사용하는 vitest이며, 스위트의 어떤 것도 실제 API에 접촉하지 않습니다. CI는 Ubuntu와 Windows에서 Node 20 및 22에 대해 typecheck, 테스트 및 빌드를 실행합니다.

라이선스

MIT