@findtime/mcp-server

@findtime/mcp-server는 https://time-api.findtime.io의 프로덕션 findtime.io Time API를 감싸는 가벼운 stdio MCP 래퍼입니다.

이 패키지는 시간 로직을 로컬에서 다시 구현하는 대신 프로덕션 API를 의도적으로 프록시합니다. 현재 시간, DST, 변환, 겹침, 회의 검색, 위치 해석은 라이브 API와 일관성을 유지해야 합니다.

배포처:

• npm: @findtime/mcp-server

• GitHub: https://github.com/hkchao/findtime-mcp-server

• 공식 MCP 레지스트리: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

• MCP 레지스트리 이름: io.github.hkchao/findtime-mcp-server

도구 목록

• answer_time_question

• get_findtime_help

• time_snapshot

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• search_timezones

• get_location_by_id

"오후 3시 PST를 런던 시간으로", "샌프란시스코의 IANA 시간대는 무엇인가요?", "SF, 베를린, 도쿄의 업무 시간이 겹치는 시간은?", "CST는 무슨 뜻인가요?" 같은 비정형 자연어 프롬프트에는 answer_time_question을 우선 사용하세요. 이 도구는 findtime.io의 도메인 로직을 통해 프롬프트를 분류하고, 결정적 Time API 동작으로 디스패치하며, 실제로 모호한 경우에는 구조화된 모호성 또는 명확화 정보를 반환합니다.

Related MCP server: Time MCP Server

MCP 클라이언트에 설치

npx를 통해 게시된 패키지를 사용하세요:

npx -y @findtime/mcp-server

에이전트 작성자는 MCP 구성과 함께 SKILL.md를 포함하세요. 이 파일은 Claude, Codex, Cursor, Cline, Windsurf, 맞춤형 회사 봇 및 기타 LLM 에이전트에게 언제 findtime.io MCP를 우선할지, 어떤 도구를 호출할지, 모호함이나 폴백을 처리하는 방법에 대한 운영 규칙을 제공합니다.

필수 런타임:

• Node 20+

• FINDTIME_TIME_API_KEY: https://findtime.io/developers/keys/에서 발급받은 유효한 findtime.io 개발자 키

선택적 환경 변수:

• FINDTIME_TIME_API_BASE_URL

• TIME_API_BASE_URL

• TIME_API_TIMEOUT_MS

• FINDTIME_BINDING_TYPE: 선택적 설치/워크스페이스 바인딩 컨텍스트용. 지원 값: slack_team, workspace_id, install_id.

• FINDTIME_BINDING_VALUE: 선택한 바인딩 유형과 일치하는 설치/워크스페이스 식별자용.

• FINDTIME_BINDING_HEADER: 맞춤형 엔터프라이즈 환경에서 헤더 이름을 직접 재정의하려면 사용합니다.

• FINDTIME_MCP_CLIENT_ID 또는 FINDTIME_MCP_INSTALL_ID: 안정적인 클라이언트 식별자를 제공하려면 사용합니다. 생략하면 서버가 사용자의 상태 디렉터리 아래에 로컬로 하나를 생성합니다. 값이 있으면 MCP 래퍼는 이를 X-Findtime-User-ID로 time-api에 전달하여 엔터프라이즈 사용량 귀속에 사용합니다.

• FINDTIME_MCP_CLIENT_TYPE

• FINDTIME_MCP_TOOL_MODE=answer-only: 모든 자연어 요청을 answer API를 통해 라우팅해야 하는 엔터프라이즈 봇을 위해 answer_time_question, get_findtime_help, get_api_diagnostics만 노출하려면 사용합니다.

• FINDTIME_MCP_INSTRUMENTATION_ENABLED=false: 익명 사용량 텔레메트리를 거부(opt out)하려면 사용합니다.

• FINDTIME_MCP_USAGE_TELEMETRY_URL: 기본 텔레메트리 엔드포인트를 재정의하려면 사용합니다.

호출별 최종 사용자 귀속

Slack, Discord, Teams 봇과 같은 다중 사용자 MCP 호스트는 장기 실행되는 @findtime/mcp-server 하위 프로세스 하나를 실행하면서도 각 Time API 호출을 해당 호출을 트리거한 최종 사용자에게 귀속시킬 수 있습니다. MCP 도구 호출 arguments 객체 안에 선택적 _endUserId 필드를 추가하세요. 서버는 _endUserId를 도구 매개변수에서 제거하고 업스트림 X-Findtime-End-User-ID HTTP 헤더로만 전달합니다.

await client.callTool({
  name: "get_current_time",
  arguments: {
    city: "Tokyo",
    _endUserId: "a3f2c1d4e5b6c7d8"
  }
});

이 필드는 선택 사항이며 이전 버전과 호환됩니다. _endUserId가 없거나 null 또는 빈 문자열이면 헤더는 생략되고 귀속은 설치 수준의 FINDTIME_MCP_CLIENT_ID 또는 FINDTIME_MCP_INSTALL_ID 동작으로 폴백됩니다.

개인정보 보호 계약: _endUserId는 MCP 호스트가 제공하는 불투명 토큰이어야 하며, 일반적으로 플랫폼 사용자 ID의 SHA-256 해시를 16~32자의 16진수 문자로 자른 값입니다. 원본 이메일 주소, 이름, Slack/Discord/Teams ID 또는 기타 PII(개인 식별 정보)를 보내지 마세요. 이 필드에 PII가 포함되지 않도록 하는 것은 호스트 애플리케이션의 책임입니다.

서버는 _endUserId를 방어적으로 검증합니다. 문자열이어야 하고 최대 256자여야 하며 CR, LF 또는 기타 제어 문자를 포함해서는 안 됩니다. 서버는 원본 값을 절대 로깅하지 않습니다.

Cursor

{
  "mcpServers": {
    "findtime": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_MCP_CLIENT_TYPE": "cursor",
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
      }
    }
  }
}

Codex

[mcp_servers.findtime]
command = "npx"
args = ["-y", "@findtime/mcp-server"]
enabled = true

[mcp_servers.findtime.env]
FINDTIME_MCP_CLIENT_TYPE = "codex"
FINDTIME_TIME_API_BASE_URL = "https://time-api.findtime.io"
FINDTIME_TIME_API_KEY = "YOUR_FINDTIME_SECRET_KEY"
# Optional enterprise install binding:
# FINDTIME_BINDING_TYPE = "workspace_id"
# FINDTIME_BINDING_VALUE = "YOUR_WORKSPACE_ID"

Claude Desktop

{
  "preferences": {
    "...": "keep your existing preferences here"
  },
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
        "env": {
          "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
          "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
        }
      }
    }
  }

Claude CLI / Claude Code

다음과 같이 findtime.io를 추가하세요:

claude mcp add --transport stdio \
  --env FINDTIME_TIME_API_BASE_URL=https://time-api.findtime.io \
  --env FINDTIME_TIME_API_KEY=YOUR_FINDTIME_SECRET_KEY \
  --env FINDTIME_MCP_CLIENT_TYPE=claude-cli \
  findtime -- npx -y @findtime/mcp-server

Claude CLI에서 JSON 구성을 대신 사용한다면 다음을 추가하세요:

{
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY",
        "FINDTIME_MCP_CLIENT_TYPE": "claude-cli"
      }
    }
  }
}

엔터프라이즈 설치의 경우 최소 자격 증명은 항상 API 키입니다. 설치 환경에 안정적인 워크스페이스 또는 설치 식별자가 있다면 선택적으로 다음을 추가하세요:

FINDTIME_BINDING_TYPE=workspace_id
FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID

Slack 전용 설치의 경우:

FINDTIME_BINDING_TYPE=slack_team
FINDTIME_BINDING_VALUE=T01ABC123

설치 확인

먼저 명시적인 도구 호출 프롬프트를 사용하세요:

Use the findtime.io MCP tool get_api_diagnostics.

그런 다음:

Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".

그 작업이 성공하면 일반 자연어 프롬프트로 다시 전환하세요:

Best meeting time between New York, Sydney, and Mumbai?

로컬 개발

워크스페이스 버전을 직접 실행하세요:

npm run mcp:start

서버는 .env.development.local, .env.development, .env.local, .env를 다음 위치에서 로드하려고 시도합니다:

• 현재 작업 디렉터리

• services/mcp-server

• 저장소 루트

테스트

프로토콜 및 전송 테스트:

npm run test:mcp-server

라이브 프로덕션 동등성 스모크 테스트:

npm run test:mcp-server:smoke

스모크 테스트 스위트는 다음을 확인합니다:

• search_timezones

• answer_time_question

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• get_location_by_id

유지보수자 릴리스 흐름

이 패키지의 공식 공개 소스는 이제 다음 위치에 있습니다:

• GitHub: https://github.com/hkchao/findtime-mcp-server

• npm: @findtime/mcp-server

• 공식 MCP 레지스트리: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

게시 및 버전 업데이트는 이 비공개 앱 저장소가 아닌 해당 공개 저장소에서 수행해야 합니다.

공개 저장소의 표준 게시 흐름:

npm test
npm pack --dry-run
npm publish --access public

이 저장소에서 이에 상응하는 로컬 검증 확인 항목은 다음과 같습니다:

npm run test:mcp-server
npm run mcp:pack

이 저장소는 MCP 패키지를 원래 만들어 낸 구현 소스로 취급하고, 공식 공개 릴리스 소스로는 취급하지 마세요.