Codex Canvas MCP

호환 클라이언트가 Canvas를 읽고, 여러 독립적인 안전 검사를 거친 후에만 일반적인 과정 콘텐츠를 작성할 수 있게 해주는 휴대용 로컬 MCP 서버입니다.

안전 모델

• 로컬 자격 증명 설정 후 기본적으로 Canvas 읽기가 가능합니다.

• 쓰기는 기본적으로 비활성화되어 있습니다.

• 모든 콘텐츠 쓰기에는 활성화된 로컬 정책, 과정별 정확한 허용 목록 일치, 정확한 확인 텍스트, 그리고 MCP 클라이언트의 승인이 필요합니다.

• 이미지 업로드에는 페이로드 게이트가 추가됩니다. 구성된 신뢰 폴더 안에 있는 로컬 소유의 PNG, JPEG 또는 WebP 파일만, 10 MiB 이하만 보낼 수 있습니다.

• 일반적인 Canvas 쓰기 도구는 없습니다.

• 자격 증명은 1Password와 선택적으로 macOS Keychain에 유지됩니다. 이 저장소나 클라이언트 구성에 포함되지 않습니다.

모든 콘텐츠 도구는 변경 및 파괴적 작업으로 표시되어 호환 클라이언트가 승인을 요구할 수 있습니다. 로컬 서버는 또한 요청된 작업과 정확히 일치하는 확인 문구가 없으면 호출을 거부합니다. 예: APPROVE CANVAS MODULE WRITE course <course_id>.

루브릭 생성은 동일 출처의 Canvas 과제 URL, 과제 모듈 항목 URL, 또는 assignment_id 쿼리 매개변수를 포함한 과정 URL을 허용합니다. 과정과 과제가 확인된 후에는 쿼리 문자열과 조각이 무시됩니다. URL은 과정 정책을 우회하지 않습니다. 해당 과정 ID는 여전히 명시적으로 허용 목록에 있어야 하며, 루브릭 생성에는 APPROVE CANVAS RUBRIC WRITE course <course_id>가 필요합니다. 이 도구는 기존 과제 루브릭을 교체하는 것을 거부하며, 모든 기준과 등급에 대한 설명을 요구하고, 채점 루브릭 점수가 과제 점수와 일치해야 합니다.

Related MCP server: CoursePack Local MCP Server

포함 내용

새 Mac 설정

필수 조건: Python 3.11 이상, 1Password CLI, 의도한 Canvas 자격 증명 항목만 읽을 수 있는 1Password 서비스 계정, 그리고 작업에 실용적인 최소 권한의 Canvas API 토큰.

1. 격리된 환경에 복제하고 설치합니다:

   git clone https://github.com/mrchris-ai/codex_canvas_mcp.git
   cd codex_canvas_mcp
   python3 -m venv .venv
   . .venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -e .

2. 숨겨진 필드에 Canvas API 토큰이 포함된 1Password 항목을 만듭니다. 서비스 계정에 해당 볼트/항목에 대한 읽기 권한만 부여합니다. 볼트 이름, 항목 이름 또는 ID, 숨겨진 필드 레이블을 기록하되, 그 값은 이 저장소에 넣지 마십시오.

3. 서비스 계정 토큰 전달 방법을 하나 선택합니다:

   • 단기 셸 세션의 경우 로컬 비밀 실행기를 통해 MCP 서버 프로세스에 OP_SERVICE_ACCOUNT_TOKEN을 제공합니다.

   • macOS에서는 해당 토큰을 Keychain에 저장하고 비밀 아닌 조회 레이블을 구성합니다. 예시 명령(안전하게 프롬프트하며 토큰을 명령줄에 넣지 마십시오):

     security add-generic-password -U -s "your-service-label" -a "your-account-label" -w

4. 서버 프로세스를 다음 비밀 아닌 값으로 구성합니다:

   변수	용도
   CANVAS_BASE_URL	Canvas HTTPS 원본(예: https://school.instructure.com)
   CANVAS_OP_VAULT	1Password 볼트 이름 또는 ID
   CANVAS_OP_ITEM	Canvas 자격 증명 항목 이름 또는 ID
   CANVAS_OP_FIELD	숨겨진 토큰 필드 레이블; 기본값은 credential
   CANVAS_KEYCHAIN_SERVICE	OP_SERVICE_ACCOUNT_TOKEN을 사용하지 않을 때의 macOS Keychain 서비스 레이블
   CANVAS_KEYCHAIN_ACCOUNT	OP_SERVICE_ACCOUNT_TOKEN을 사용하지 않을 때의 macOS Keychain 계정 레이블
   CANVAS_IMAGE_UPLOAD_ROOT	이미지 업로드가 허용되는 유일한 로컬 폴더의 절대 경로

5. Canvas에 접촉하거나 자격 증명을 읽지 않고 프로토콜 및 보안 게이트만 테스트합니다:

   python -m unittest discover -s tests -v
   printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python -m canvas_mcp

6. stdio 서버를 Codex에 추가합니다. 프로젝트 수준 형식은 다음과 같습니다:

   [mcp_servers.canvas]
   command = "/absolute/path/to/codex_canvas_mcp/.venv/bin/python"
   args = ["-m", "canvas_mcp"]
   
   [mcp_servers.canvas.env]
   CANVAS_BASE_URL = "https://school.instructure.com"
   CANVAS_OP_VAULT = "your-vault"
   CANVAS_OP_ITEM = "your-item"
   CANVAS_OP_FIELD = "credential"
   CANVAS_KEYCHAIN_SERVICE = "your-service-label"
   CANVAS_KEYCHAIN_ACCOUNT = "your-account-label"
   CANVAS_IMAGE_UPLOAD_ROOT = "/absolute/path/to/reviewed/canvas-images"

   신뢰하는 프로젝트의 .codex/config.toml 또는 개인 Codex 구성에 넣습니다. 비밀 값을 추가하지 마십시오. MCP 구성을 변경한 후 클라이언트를 다시 시작하거나 새 작업을 열고, Canvas 데이터를 요청하기 전에 나열된 도구를 확인하십시오.

ChatGPT 호환성

이 저장소는 Codex 및 로컬 stdio MCP를 지원하는 다른 클라이언트를 위한 로컬 stdio MCP 서버를 구현합니다. 현재 ChatGPT 사용자 지정 앱은 로컬 stdio 서버에 직접 연결하지 않습니다. OpenAI의 현재 지침은 Secure MCP Tunnel을 통해 비공개 로컬 MCP를 노출하거나(또는 검토된 원격 MCP 엔드포인트를 배포) 플랜 및 작업공간 관리자 가용성에 따라 달라집니다. 이 프로세스를 공개 인터넷에 직접 노출하지 마십시오.

ChatGPT 설정을 시도하기 전에 ChatGPT의 개발자 모드 및 MCP 앱을 참조하십시오. 가용성 및 승인 동작은 변경될 수 있습니다.

콘텐츠 작성 도구 활성화

특정 작업에 필요하지 않는 한 쓰기를 비활성화 상태로 유지하십시오.

1. config/write-policy.example.json을 저장소 외부의 위치로 복사합니다.

2. 콘텐츠 작성이 승인된 정확한 Canvas 과정 ID만 추가합니다.

3. enabled를 true로 설정하고 파일을 제한합니다:

   chmod 600 /absolute/private/path/write-policy.json

4. MCP 서버 환경에 CANVAS_WRITE_POLICY=/absolute/private/path/write-policy.json을 추가합니다.

5. 클라이언트를 다시 시작하고 canvas_get_write_policy를 호출하여 적용된 정책을 확인합니다.

6. 각 콘텐츠 쓰기에 대해 정확한 대상과 페이로드를 검토합니다. 작업별 확인 문구를 제공하고 클라이언트에서 변경 작업을 승인합니다.

7. 작업이 완료되면 정책을 다시 비활성화합니다.

변수가 없거나, 파일이 없거나, 권한이 0600보다 넓거나, 쓰기가 비활성화되었거나, 과정이 허용 목록에 없으면 서버는 쓰기를 거부합니다.

이미지 업로드 활성화

이미지 업로드는 동일한 로컬 쓰기 정책과 정확한 과정 허용 목록, 그리고 CANVAS_IMAGE_UPLOAD_ROOT를 사용합니다. 이 도구는 상대 경로, 심볼릭 링크, 해당 루트 밖의 파일, 현재 사용자가 소유하지 않은 파일, 지원되지 않는 이미지 유형, 확장자와 이진 서명이 일치하지 않는 파일, 10 MiB보다 큰 파일을 거부합니다. 정확한 확인 문구는 APPROVE CANVAS IMAGE UPLOAD course <course_id>입니다.

Canvas는 문서화된 3단계 업로드 교환을 사용합니다: 인증된 API를 통해 과정 파일을 초기화하고, Canvas 액세스 토큰 없이 이미지를 Canvas가 반환한 HTTPS 스토리지 URL로 보내고, 반환된 동일 출처의 Canvas 완료 위치를 인증합니다. 그런 다음 도구는 /api/v1/courses/<course_id>/files/<file_id>를 읽고 MIME 유형과 크기를 확인한 후 영구적인 과정 미리보기 경로를 반환합니다. 스토리지 서명이나 파일 다운로드 검증자 URL은 절대 반환하지 않습니다.

현재 작성 경계

이 프로젝트는 이 Mac의 지원되는 채팅에서 사용되는 공유 로컬 Canvas MCP의 소스입니다. 일반적인 정책 및 승인 게이트를 거친 후 Pages, Modules 및 모듈 항목, Assignments 및 과제 Rubrics, Discussions, 그리고 질문이 있는 Classic Quizzes를 작성할 수 있습니다. 또한 Pages, Assignments, Discussions, Classic Quizzes 및 Modules에 대한 리소스별 삭제 도구를 제공합니다. Module을 삭제하면 해당 항목 배치는 제거되지만 기본 과정 콘텐츠는 제거되지 않습니다. 유일한 로컬 파일 기능은 위에서 설명한 페이로드 게이트 이미지 업로더입니다. 일반 파일 업로드, New Quizzes 및 계정/과정 관리 기능은 지원되지 않습니다.

구현 및 종단 간 검증 기록은 docs/2026-08-06-content-authoring-extension.md를 참조하십시오. 이미지 업로드 위협 모델 및 검증 기록은 docs/2026-08-16-image-upload-extension.md를 참조하십시오.

개발

python -m pip install -e .
python -m unittest discover -s tests -v
python -m compileall -q src tests

테스트는 네트워크 및 자격 증명 경계를 모의합니다. 기여자가 유지해야 하는 불변 조건은 AGENTS.md를 참조하고, 의도적으로 연기된 관리 기능은 ROADMAP.md를 참조하십시오.