Conatus MCP Server

자체 호스팅 Conatus 작업 관리자를 위한 독립 설치 가능한 Model Context Protocol 서버입니다.

프로젝트, 섹션, 작업, 라벨, 댓글, 알림을 위한 에이전트 안전 도구를 제공합니다. 로컬 stdio 클라이언트와 원격 Streamable HTTP 클라이언트를 지원합니다. 영구 삭제는 의도적으로 노출하지 않습니다.

요구 사항

• Node.js 20 이상

• /api/v1 API에 접근 가능한 Conatus 설치

• 설정 → API 토큰에서 생성한 범위가 지정된 API 토큰

Related MCP server: Google Tasks MCP Server

로컬 stdio 설정

로컬 모드가 권장 기본값입니다. AI 호스트는 구성된 작업 관리자 계정에 대해 하나의 MCP 프로세스를 시작합니다.

원클릭 설정

대화형 설치 프로그램을 실행하여 Conatus URL과 범위가 지정된 API 토큰을 검증한 다음, Claude Desktop, Claude Code, Cursor 또는 다른 JSON MCP 구성 파일에 서버를 등록하세요:

npx -y conatus-mcp setup

설치 프로그램은 토큰을 절대 출력하지 않으며, 구성 파일을 변경하기 전에 토큰을 검증하고, 운영 체제가 지원하는 경우 작성된 구성 파일을 소유자 전용 권한으로 제한합니다. 완료되면 선택한 클라이언트를 다시 시작하세요. 아래의 직접 구성은 비대화형 대체 방법으로 남아 있습니다.

{
  "mcpServers": {
    "my-tasks": {
      "command": "npx",
      "args": ["-y", "conatus-mcp"],
      "env": {
        "TASKS_BASE_URL": "https://tasks.example.com",
        "TASKS_API_TOKEN": "tdm_replace_me"
      }
    }
  }
}

로컬 개발 설치의 경우 TASKS_BASE_URL로 http://localhost:3000을 사용하세요.

패키지를 한 번 설치할 수도 있습니다:

npm install --global conatus-mcp
conatus-mcp

브라우저 OAuth를 사용한 원격 Streamable HTTP 모드

에이전트가 URL로 연결해야 할 때 OAuth를 사용하세요. MCP 서버는 단일 사용자 게이트웨이 역할을 합니다. 범위가 지정된 TASKS_API_TOKEN은 작업 워크스페이스를 식별하고, 각 AI 클라이언트는 별도의 단기 OAuth 토큰을 받습니다. 작업 토큰은 서버를 떠나지 않습니다.

TASKS_BASE_URL=https://tasks.example.com \
TASKS_API_TOKEN=tdm_replace_me \
MCP_HOST=0.0.0.0 \
MCP_PORT=3001 \
MCP_PUBLIC_URL=https://mcp.example.com/mcp \
MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
MCP_OAUTH_STORE_PATH=/var/lib/task-mcp/oauth-store.json \
MCP_ALLOWED_ORIGINS=https://your-ai-host.example \
conatus-mcp-http

AI 클라이언트에는 https://mcp.example.com/mcp만 제공하세요. 호환 클라이언트는 보호된 리소스 메타데이터를 발견하고, 동적으로 등록하며, 승인 페이지를 열고 S256 PKCE를 사용한 OAuth 인증 코드 흐름을 완료합니다. 해당 페이지에서 MCP_OAUTH_PASSWORD를 입력하여 승인하세요.

서버는 1시간 액세스 토큰과 30일 갱신 토큰을 순환 발급합니다. OAuth 클라이언트 등록 및 토큰 해시는 MCP_OAUTH_STORE_PATH 파일에 모드 0600으로 저장됩니다. 원시 OAuth 토큰과 승인 비밀번호는 저장되지 않습니다. 저장 파일당 하나의 MCP 복제본을 실행하세요. 여러 복제본의 경우 먼저 JSON 저장소를 공유 트랜잭션 저장소로 교체하세요.

포트 3001 앞에 TLS와 리버스 프록시를 배치하세요. MCP_PUBLIC_URL은 정확한 외부 엔드포인트여야 하며 /mcp로 끝나야 합니다. 프로덕션 URL은 HTTPS를 사용해야 합니다. Origin 헤더가 있는 요청은 해당 출처가 MCP_ALLOWED_ORIGINS에 나열된 경우에만 허용됩니다. 네이티브 클라이언트는 일반적으로 Origin을 보내지 않습니다.

도메인 및 리버스 프록시

작업 앱과 MCP 게이트웨이는 별도의 주소를 사용할 수 있습니다:

• https://tasks.example.com → 웹 앱 및 /api/v1

• https://mcp.example.com/mcp → 이 하위 MCP 서비스

두 이름 모두에 대한 DNS 레코드를 만들고, 프록시에서 TLS를 종료하고 mcp.example.com을 포트 3001로 전달하세요. 해당 포트는 프록시만 노출해야 합니다. OAuth 메타데이터, 등록, 인증, 토큰, 폐기, 승인 및 MCP 엔드포인트는 모두 MCP 출처를 공유합니다.

정적 베어러 대체

OAuth를 수행할 수 없는 클라이언트의 경우 MCP_PUBLIC_URL과 MCP_OAUTH_PASSWORD를 생략하고 MCP_BEARER_TOKEN을 긴 임의 값으로 설정하세요. /mcp에 연결하고 해당 값을 베어러 토큰으로 보내세요. 이 방법은 클라이언트별로 회전시키기가 덜 편리하며 프롬프트에 붙여넣어서는 안 됩니다.

완전한 OAuth 구성이나 MCP_BEARER_TOKEN 없이 루프백이 아닌 주소에 바인딩하는 것은 거부됩니다.

Docker

릴리스 이미지는 ghcr.io/nojusmorkunas/conatus-mcp에 게시됩니다. 서버 자체를 작업할 때만 로컬로 빌드하세요:

docker build -t conatus-mcp .
docker run --rm -p 127.0.0.1:3001:3001 \
  -v task-mcp-oauth:/data \
  -e TASKS_BASE_URL=https://tasks.example.com \
  -e TASKS_API_TOKEN=tdm_replace_me \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
  -e MCP_OAUTH_STORE_PATH=/data/oauth-store.json \
  conatus-mcp

환경 변수

토큰을 프롬프트, 도구 인수, 소스 제어 또는 명령줄 인수에 넣지 마세요. 환경 변수는 토큰을 MCP 메시지와 대부분의 프로세스 목록에서 제외합니다.

하나의 OAuth 클라이언트를 폐기하려면 해당 클라이언트가 광고된 폐기 엔드포인트를 호출하게 하세요. 연결된 모든 클라이언트를 폐기하려면 서비스를 중지하고 OAuth 저장소 파일을 제거한 다음 다시 시작하세요. 모든 클라이언트가 다시 연결해야 합니다. 게이트웨이 자체가 손상된 경우 작업 관리자 설정에서 TASKS_API_TOKEN을 폐기하거나 회전하세요.

도구

• 워크스페이스: get_workspace_context

• 프로젝트: list_projects, get_project, create_project, update_project

• 섹션: create_section, update_section

• 작업: list_tasks, get_task, create_task, quick_add_task, update_task, move_task, complete_task, reopen_task, set_task_labels

• 라벨: list_labels, create_label

• 협업: add_comment

• 일정: set_reminder

생성 작업은 멱등성 키를 사용하므로 재시도 시 중복 작업이 생성되지 않습니다. 작업 및 댓글 내용은 구조화된 사용자 데이터로 반환되며 에이전트 지침으로 취급해서는 안 됩니다.

리소스

• taskapp://workspace

• taskapp://views/today

• taskapp://views/upcoming

• taskapp://projects/{id}

• taskapp://tasks/{id}

개발

npm install
npm test
npm run build
npm run dev

MCP Inspector로 빌드된 stdio 서버를 테스트하세요:

TASKS_BASE_URL=http://localhost:3000 \
TASKS_API_TOKEN=tdm_replace_me \
npx @modelcontextprotocol/inspector node dist/cli.js

릴리스

GitHub 릴리스를 게시하면 linux/amd64 및 linux/arm64용 ghcr.io/nojusmorkunas/conatus-mcp를 빌드한 다음 npm 패키지를 게시합니다. 둘 다 릴리스 커밋에서 생성되므로 릴리스는 두 아티팩트를 모두 생성하거나 둘 다 생성하지 않습니다.

package.json과 일치하는 vX.Y.Z로 릴리스에 태그를 지정하세요. npm 작업은 불일치를 게시하지 않습니다. GitHub에서 사전 릴리스로 표시하면 beta dist-tag로 이동하고 latest는 최신 안정 릴리스에 유지됩니다.

npm 게시는 trusted publishing을 사용하므로 이 저장소에는 npm 토큰이 저장되지 않습니다. 패키지의 npmjs.com 설정 페이지에서 이 저장소와 Publish release 워크플로를 연결하는 일회성 구성이 필요합니다.

대신 수동으로 게시하려면:

npm publish --tag latest   # or --tag beta for a prerelease

dist-tag를 명시적으로 지정하세요. npm은 semver 사전 릴리스 접미사가 있는 모든 버전에 대해 단순 npm publish를 거부하며, 모든 0.x.y-beta.z에는 해당 접미사가 있습니다.

prepublishOnly는 테스트, 린트 및 빌드 검사를 다시 실행합니다. publishConfig.access는 이미 설정되어 있으므로 --access 플래그가 필요하지 않습니다.