spec

Manifest (nesy.yaml)

마도서 한 개를 정의하는 단일 YAML. 메타·실행·주문 세 부분으로 이루어져 있어요. AI가 이 파일을 보고 마도서를 어떻게 부를지 판단하고, 우리는 이 파일을 보고 마도서를 어떻게 실행할지 결정합니다.

두 가지 작성 경로

코드 에디터(권장) — nesy 사이트의 등록 폼이 알아서 nesy.yaml을 만들어줘요. 메이커는 yaml을 직접 안 봐도 됩니다. 한 파일짜리 마도서에 적합.
git 연결 — 자기 GitHub repo 루트에 nesy.yaml을 직접 작성. 여러 파일짜리 마도서·자기 컴퓨터에서 짜는 본격 메이커용.

1. 메타 필드

name마도서 제목. 한국어 OK. 1~80자.
invocation사용자가 외칠 이름. 네시, 환율 ...처럼 부름. 영문/한글 가능, 공백 X. 자세히
price_tokens구매가(마나). 한 번 사면 평생 호출 무제한. 1마나 = 15원.
description한 줄 소개. 마도서 카드·상세 페이지에 노출.
optimized_for(선택) 어느 AI에 최적화됐는지. [claude, chatgpt, cursor, gemini, python, any] 중 다중 선택.

2. 실행 필드

language베타 1차는 ts만 지원.Python(py)은 곧 풀어요.
entry실행 시작 파일 경로. index.ts 권장.export async function run({ input, secrets }) 형태로 함수 export.
secrets(선택) 외부 API 키 등 비밀값 이름 배열. nesy 사이트에서 별도로 값을 등록하면 실행 시 secrets.NAME으로 안전하게 주입돼요.

3. 주문(tools) 정의

AI가 어떤 주문을 언제 부를지 판단하는 부분. 업계 표준 MCP 형식.

name영문 식별자 (snake_case 권장). 영문자로 시작, 영문/숫자/언더바만, 64자 이내.
description가장 중요. AI가 이 주문을 언제 부를지 판단하는 자연어 설명. 1~500자.
inputSchema(선택) 인자가 있는 주문일 때만. JSON Schema의 object 형식.자세히

tools 배열은 1개 이상 필수, 최대 16개.

전체 예시

# === 메타 ===
name: 환율 계산기
invocation: 환율
price_tokens: 100
description: 두 통화 환율을 알려줘요
optimized_for: [claude, chatgpt]

# === 실행 ===
language: ts
entry: index.ts
secrets:
  - EXCHANGE_API_KEY

# === 주문(tools) 정의 ===
tools:
  - name: get_rate
    description: 두 통화 간 현재 환율을 돌려줌. "환율" 류 질문에 부른다.
    inputSchema:
      type: object
      properties:
        from:
          type: string
          description: ISO 4217 통화 코드 (예: USD)
        to:
          type: string
          description: 변환 대상 통화
      required: [from, to]

entry 파일 예시 (index.ts)

// index.ts — entry 파일
export async function run({ input, secrets }: {
  input: { from: string; to: string };
  secrets: { EXCHANGE_API_KEY: string };
}) {
  const url = `https://api.exchangerate.host/convert?from=${input.from}&to=${input.to}`;
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${secrets.EXCHANGE_API_KEY}` },
  });
  const data = await res.json();
  return { rate: data.result };
}

run 함수는 { input, secrets }를 받고, 결과 객체를 반환하면 끝. 마도서가 호출되면 nesy 실행환경(Cloudflare Workers)에서 이 함수가 격리 실행돼요.

검증 정책

language: py 또는 entry가 .py → 등록 거부. "Python은 곧 지원" 안내.
language와 entry 확장자가 안 맞으면 거부.
tools 비어 있으면 거부.
name·invocation·price_tokens·language·entry는 필수.
형식 오류는 어떤 줄·어떤 항목인지 메시지로 알려줘요.

다른 플랫폼이랑 호환되나요?

Claude Desktop · Cursor (MCP) — tools 부분이 그대로 호환. 우리 어댑터가 MCP 프로토콜로 노출.
ChatGPT (GPT Actions) — 우리 어댑터가 OpenAPI 3.0으로 자동 변환. 메이커는 신경 쓸 필요 없어요.
OpenAI Function Calling — parameters라는 다른 키 이름을 쓰지만 의미는 같음. 직접 변환할 일 있으면 inputSchema →parameters.

← 호출 마법언어 주문 잘 적기 →