ainoteAI 가 직접 다루는 노트

30초 정리 ​

ainote 는 AI 가 직접 호출하는 노트·태스크·메모리·다중 디바이스 동기화 백엔드다. 같은 26개 도구를 두 가지 프로토콜로 동시 노출한다:

• MCP JSON-RPC (https://api.ainote.dev/api/mcp) — Claude Desktop · Claude Code · Cursor · Windsurf
• OpenAPI 3.1 (https://api.ainote.dev/api/mcp/openapi.json) — OpenAI Custom GPT Actions · LangChain remote tools · AutoGen · 기타 HTTP-first 에이전트

두 surface 가 하나의 tool registry 를 공유하므로 (Api::McpController#apply_tool_annotations!) 정의가 갈라질 일이 없다. 한 번 추가한 도구가 모든 에이전트 진영에서 즉시 보인다.

Backend Completeness — 우리의 설계 철학 ​

"백엔드는 철저하게, 사용자는 간단하게."

ainote 의 모든 결정은 이 한 줄을 따른다.

이 분리가 어떻게 에이전트 친화성으로 이어지는가:

• handoff_list 가 호출될 때 백엔드는 7일 초과 핸드오프를 알아서 purge 한다. 에이전트는 단지 목록을 받을 뿐 cleanup 을 모른다 — 그러나 annotations 으로 destructiveHint: true 를 advertise 해서 자율 에이전트가 destructive call 임을 인식 가능
• vault_sync(action: push) 가 호출되면 백엔드가 conflict 를 감지·해결한다. 에이전트는 conflictResolution: merge|overwrite|abort 한 번 결정만
• login_and_get_key 는 MCP key 가 없으면 백엔드에서 자동 생성한다. 에이전트는 그냥 "key 받기" 만 요청

→ Backend Completeness Principle 전문 보기

26개 도구 매트릭스 ​

범례: 🔒 read-only · ⚠️ destructive · ♻️ idempotent · 🌐 open-world (외부 시스템 호출)

handoff_list / handoff_get 가 destructive 인 이유: 호출 시 7-day stale purge 가 같이 돈다. 자율 에이전트가 cleanup 의도 없이 destructive 호출을 피하도록 마킹.

→ 전체 annotations 매핑 + 판단 기준

Surface 매트릭스 — 어디서든 같은 도구 ​

Dual-protocol 게이트웨이 — 어떻게 동작하나 ​

같은 코드 한 곳에서 두 surface 가 갈라진다:

# app/controllers/api/mcp_controller.rb
class Api::McpController < ApplicationController
  MCP_TOOL_ANNOTATIONS = {
    "list_tasks"   => { readOnlyHint: true, idempotentHint: true, ... },
    "delete_task"  => { destructiveHint: true, idempotentHint: true, ... },
    # ... 26개 전체
  }.freeze

  def self.apply_tool_annotations!(tools)
    tools.each { |t| t[:annotations] = MCP_TOOL_ANNOTATIONS[t[:name]] }
    tools
  end
end

# app/controllers/api/mcp/openapi_controller.rb
class Api::Mcp::OpenapiController < ApplicationController
  def mcp_tools
    Api::McpController.apply_tool_annotations!(
      Api::McpController.build_tools_array
    )
  end
end

→ MCP tools/list 는 annotations 를 그대로 emit, OpenAPI mirror 는 동일 annotations 를 x-mcp-annotations extension 으로 노출. 두 surface 가 갈라질 수 없는 구조.

→ 코드 상세

Quickstart — 한 진영씩 ​

Claude Code (HTTP, 권장) ​

{
  "mcpServers": {
    "ainote": {
      "type": "http",
      "url": "https://api.ainote.dev/api/mcp",
      "headers": { "Authorization": "McpKey <YOUR_MCP_KEY>" }
    }
  }
}

→ 전체 가이드 · MCP key 발급은 Claude 에 "ainote 가입시켜줘" 한 줄.

Claude Desktop (stdio, npm) ​

{
  "mcpServers": {
    "ainote": {
      "command": "npx",
      "args": ["-y", "@ainote/mcp"],
      "env": {
        "AINOTE_API_URL": "https://api.ainote.dev",
        "AINOTE_API_KEY": "<YOUR_KEY>"
      }
    }
  }
}

→ 전체 가이드

OpenAI Custom GPT Actions ​

1. ChatGPT → Create a GPT → Configure → Actions → Create new action
2. Schema → Import from URL: https://api.ainote.dev/api/mcp/openapi.json
3. Authentication → API Key → Auth Type: Custom, Header: Authorization, Value: McpKey <YOUR_KEY>

→ 전체 가이드

Multi-device 시나리오 ​

[MacBook · Claude Code]
   handoff_save({project:"logi", topic:"phase4", time:"1555", content:"..."})
   → vault 에 handoffs/logi-phase4-1555-2026-05-14.txt 저장

(다른 디바이스 / 다른 세션)

[Mac mini · Claude Code]
   handoff_get({project:"logi", topic:"phase4"})
   → 동일 핸드오프 회수 → 작업 재개

(iPhone)
   ainote 앱 → 같은 vault → 같은 데이터

같은 패턴이 태스크 / dev-doc / sync_push / vault_sync 전부에 적용. 모든 device 가 같은 백엔드를 본다.

Security & Open Source ​

• MIT License — 자체 호스팅 가능 (Docker / Render / Fly.io)
• age E2E encryption — mcp category (mcpServers + API keys) 는 클라이언트에서 age 로 암호화 후 업로드. 서버는 평문 모름
• OS Keychain integration — 디바이스별 age identity 가 macOS Keychain / libsecret / Credential Manager 에 저장
• 데이터 위치 — Render Singapore PostgreSQL + git vault (사용자 소유 GitHub repo)
• RFC 8628 device flow — CLI 로그인 시 PKCE (S256) 강제
• 삭제 권리 — delete_task · delete_dev_doc 등 모든 destructive 도구 사용자 임의 호출 가능. 30일 trash window 후 영구 삭제

→ Privacy Policy · Terms of Service · Security disclosure

자주 묻는 질문 ​

Q. 계정 없이 바로 써볼 수 있나요? — 네. MCP 등록 후 Claude 에 "ainote 가입 시켜줘" 한 줄이면 signup_and_get_key 가 호출돼서 키가 발급됩니다.

Q. Obsidian 사용자인데 마이그레이션 가능한가요? — vault_create 로 vault 만든 뒤 git remote 로 기존 Obsidian vault 를 붙이면 됩니다. 마크다운이라 wikilinks [[...]] 그대로 호환.

Q. OpenAI Custom GPT Store 에 공개 가능한가요? — Yes. api.ainote.dev/api/mcp/openapi.json 가 OpenAPI 3.1 spec, privacy policy URL (ainote.dev/legal/privacy) 의 root domain 이 일치 → verified domain DNS TXT 인증 완료 시 Public 배포 가능.

Q. 데이터 어디 저장되나요? — 호스팅: Render(Singapore) PostgreSQL + 사용자 GitHub repo (vault). 셀프호스팅: 자체 인스턴스 가능. 데이터 내보내기 언제든 가능.

Q. AI 가 모든 노트 다 보나요? — MCP 도구 호출할 때만. 호출 단위는 너가 직접 승인 가능 (Claude Code 에서). 권한 모델: API key 단위로 read/write 분리 가능.

Q. Anthropic / OpenAI / Google A2A 다음 어디까지 지원? — MCP (지금) → OpenAPI (지금) → A2A AgentCard (Phase 4 진행 중) → AGNTCY / Letta (모니터링). 전체 로드맵

Q. Pricing? — 자체 호스팅 무료 (MIT). 호스팅 plan TBD.

→ 전체 FAQ

AI/LLM 에게 통째로 던지기 ​

llms.txt 표준 으로 전체 문서를 LLM 친화 형식으로 제공:

• 📥 /llms.txt — 페이지 색인 + 1줄 요약
• 📥 /llms-full.txt — 모든 본문 한 파일로

ChatGPT/Claude 에 붙여넣고 "ainote 가 뭐고 어떻게 붙이는지 알려줘" 한마디면 끝.

Privacy · Terms · Security · Contact (Telegram · 카카오 오픈채팅)
MIT License · Built by Dcode Labs · ainote.dev — 너의 노트는 너의 것.