Morit Plugin1. 시작과 개발 흐름

시작하기와 개발 흐름

먼저 개발 방식을 고르기

요구사항	권장 방식
텍스트 요약·템플릿처럼 단순한 Tool	앱의 Plugin Builder
화면, Search Provider, 알림, 외부 API	공식 `@morit/cli` 프로젝트
AI 에이전트가 파일 작성과 검증을 수행	Local 또는 Remote Plugin MCP
Python 데이터 처리	`sandbox_python`을 포함한 고급 프로젝트

세 방식은 결국 같은 manifest.json, fragment, .mplg 계약을 사용합니다. Builder로 시작한 뒤 고급 요구가 생기면 소스 프로젝트로 전환할 수 있습니다.

준비 사항

Node.js 20.12 이상
앱에서 사용할 Morit 계정
Cloud Project를 배포할 경우 developers.moring.co에서 접근 가능한 조직
저장소 내부 Python 도구를 직접 사용할 경우 Python 3.11 이상

개인 키, OAuth client secret, API token은 프로젝트 파일에 기록하지 않습니다. CLI 로그인 정보는 운영체제 보안 저장소에 두고, Cloud 비밀 값은 Developer Platform의 Secrets에 둡니다.

첫 프로젝트 만들기

빈 디렉터리에서 실행합니다.

bash

npx -y @morit/cli plugin setup . \
  --id com.example.study \
  --name "Study" \
  --publisher example

이미 유효한 manifest.json이 있으면 --id, --name, --publisher 없이 setup을 실행할 수 있습니다. 명령은 로컬 연결 정보 파일 morit-plugin.json도 생성합니다. 이 파일에는 Project ID와 revision만 있으며 인증 정보는 들어가지 않습니다.

다음 최소 manifest로 시작할 수 있습니다.

json

{
  "schema_version": 2,
  "id": "com.example.study",
  "name": "Study",
  "description": "오늘 할 일을 정리합니다.",
  "publisher": "example",
  "version": "1.0.0",
  "min_morit_version": "1.7.12",
  "max_morit_version": "1.999.999",
  "permissions": [],
  "capabilities": [
    {
      "id": "com.example.study.summary",
      "kind": "tool",
      "title": "할 일 요약",
      "description": "입력한 할 일을 짧게 정리합니다.",
      "permissions": [],
      "runtime": {
        "adapter": "text_template",
        "template": "오늘 할 일을 정리합니다: {query}"
      }
    }
  ],
  "ui_extensions": [],
  "credentials": [],
  "slash_commands": [],
  "connectors": [],
  "dependencies": [],
  "data_policy": "purge"
}

플러그인은 capability나 UI extension을 하나 이상 선언해야 합니다. 큰 배열을 manifest 한 파일에 넣기보다 tools/*.json, ui/*.json 같은 fragment로 나누는 편이 충돌과 리뷰 오류를 줄입니다.

구현 순서

사용자가 달성할 작업과 첫 화면의 한 가지 목표를 정합니다.
프로젝트 구조에 맞춰 capability와 UI fragment를 만듭니다.
Manifest에 필요한 권한, 연결, 데이터 삭제 정책을 선언합니다.
화면과 내비게이션을 먼저 나눈 뒤 컴포넌트를 배치합니다.
외부 서비스는 Connector와 인증을 통해 연결합니다.
validate로 참조·권한·파일·서명 전 조건을 확인합니다.
UI가 있으면 preview로 정보 구조와 binding을 점검합니다.
signed .mplg를 build하고 다시 열어 서명과 manifest를 확인합니다.
앱에 설치해 첫 설치, 활성화, 권한 거부, 빈 데이터, 오류, 재시도, 삭제를 실사용합니다.
Cloud Project에 동기화하고 private 배포 후 필요한 경우 public으로 공개합니다.

로컬 검증과 빌드

bash

npx -y @morit/cli plugin validate .
npx -y @morit/cli plugin build . --output ./dist/study-1.0.0.mplg

UI preview가 필요하면 AI 에이전트에서 morit_project_preview를 호출하거나 저장소에서 다음을 실행합니다.

bash

python tools/morit_plugin.py preview . --output ./dist/preview.html

preview는 HTML 안에서 임의 스크립트를 실행하지 않으며, 실제 앱의 Material 3 렌더링·스크롤·포커스· 접근성을 보장하지 않습니다. 반드시 앱에서 이어서 확인합니다.

Cloud 연결과 배포

bash

npx -y @morit/cli login
npx -y @morit/cli plugin add .
npx -y @morit/cli plugin sync .
npx -y @morit/cli plugin deploy . --visibility private

plugin add는 현재 조직에 Cloud Project를 만들고 로컬 프로젝트를 연결합니다. 이후 기본 sync는 로컬 파일을 Cloud로 올립니다. sync --pull은 Cloud 파일을 가져오며 로컬 변경이 있으면 중단합니다. 정말 Cloud 사본으로 교체할 때만 --force를 함께 사용합니다.

완료 조건

경로를 출력했다는 사실만으로 완료하지 않습니다.

source 파일이 존재하고 다시 읽힌다.
validate가 성공한다.
UI가 있으면 preview가 생성되고 정보 구조를 확인했다.
.mplg가 0바이트가 아니며 ZIP과 embedded Ed25519 signature를 다시 검증했다.
실제 앱에서 설치·활성화·기능 실행·오류 복구·삭제를 확인했다.
배포 요청이라면 고유 deployment_id, artifact SHA-256, visibility를 확인했다.

다음은 프로젝트 구조와 fragment입니다.