MCP Tool Reference

AI-ERD MCP 서버에는 60개 tool이 정의되어 있습니다. 아래 이름은 서버가 내보내는 이름, 즉 tools/call 에 실어 보내는 값입니다.

MCP 클라이언트는 여기에 자기 prefix 를 한 번 더 붙입니다. 등록한 서버 이름이 ai-erd 라면 list_documents 는 어시스턴트에서 mcp__ai-erd__list_documents 로 보입니다. 바뀌는 것은 클라이언트가 붙이는 앞부분뿐이고, 이 페이지의 이름은 그대로입니다.

카탈로그는 네 그룹으로 나뉩니다.

그룹	개수	범위
Generic backbone	38	workspace, project, folder, document, version, share, attachment, search, identity
ERD	10	ERD content 조회(table, ref, table group, enum), 일괄 적용 1개, auto layout
Diagram	10	diagram node, edge, group, 일괄 적용 1개, LLM request handoff
Markdown	2	Markdown append와 AI generation helper

그룹은 단계적으로 열리므로, 사용 중인 서버의 tools/list 에 아직 모든 그룹이 보이지 않을 수 있습니다. 실제로 쓸 수 있는 tool 과 JSON Schema 는 MCP tools/list 응답이 단일 진실원이고, 이 문서는 같은 카탈로그를 prompt 작성과 수동 확인에 맞게 요약합니다.

---

이름 규칙

• tool 이름은 prefix 없는 snake_case 입니다.
• 문서 타입은 erd, diagram, markdown, openapi 입니다. MCP 로 만들 수 있는 타입은 create_documents 의 type enum 에 나옵니다.
• 최상위 group 용어는 workspace로 통일되었습니다. workspaceUuid / workspaceId를 사용하며 workspace에 groupUuid를 쓰지 않습니다.
• 모든 타입의 문서 자체 생성/목록/수정/삭제는 generic document tool을 사용합니다: create_documents, list_documents, get_document, update_documents, delete_documents.
• ERD content tool은 부모 ERD 문서를 documentUuid로 받습니다.
• Diagram content tool은 부모 diagram 문서를 diagramUuid로 받습니다.
• public share는 enable_shares(targetType=project|folder|document, targetUuids)와 disable_shares(...)로 통합되었습니다.

---

Generic Backbone Tools (38)

Tool	주요 input shape	목적
list_workspaces	없음	접근 가능한 workspace 목록
get_workspace	uuid	workspace 단건 조회
create_workspaces	items[]	workspace 생성
update_workspaces	items[].uuid	workspace 이름/속성 수정
delete_workspaces	uuids[]	workspace archive
unarchive_workspaces	uuids[]	archive된 workspace 복원
list_projects	workspaceUuid?	project 목록
get_project	uuid	project 단건 조회
create_projects	items[].workspaceUuid, items[].name	project 생성
update_projects	items[].uuid	project 수정
delete_projects	uuids[]	project archive
unarchive_projects	uuids[]	archive된 project 복원
list_folders	projectUuid?, parentUuid?	folder 목록
create_folders	items[].projectUuid, items[].name	folder 생성
update_folders	items[].uuid	folder 이름 수정
move_folders	items[].uuid, items[].parentUuid?	folder 이동
delete_folders	uuids[]	folder archive
unarchive_folders	uuids[]	archive된 folder 복원
list_documents	projectUuid?, folderUuid?, type?, q?, limit?	document 목록 또는 검색
get_document	uuid	document 단건 조회
create_documents	items[].projectUuid, items[].type, items[].title, items[].typePayload?	ERD, diagram, Markdown, OpenAPI document 생성
update_documents	items[].uuid, items[].title?, items[].typePayload?	document metadata 또는 type payload 수정
move_documents	items[].uuid, items[].folderUuid?	document 이동
delete_documents	uuids[]	document archive
unarchive_documents	uuids[]	archive된 document 복원
list_trash	선택 filter	archive된 resource 조회
list_versions	documentUuid	document version 목록
get_version	documentUuid, version	version snapshot 조회
restore_versions	items[].documentUuid, items[].version	이전 version 복원
enable_shares	targetType, targetUuids[]	project/folder/document public share 활성화
disable_shares	targetType, targetUuids[]	public share 비활성화
list_attachments	projectUuid?, documentUuid?	attachment 목록
get_attachment	uuid	attachment metadata 조회
upload_attachments	items[]	attachment 업로드
delete_attachments	uuids[]	attachment 삭제/archive
request_upload_token	purpose, scopeJson?, maxBytes?, ttlSeconds?	upload 또는 one-shot MCP call token 발급
search_documents	q, type?, projectUuid?, limit?, offset?	document full-text search
identity_get_self	없음	로그인한 사용자 정보

Document CUD Schema

복수형 document CUD tool을 사용합니다. items[] 각 원소는 document type과 선택적인 typePayload를 가집니다.

{
  "items": [
    {
      "projectUuid": "<project-uuid>",
      "folderUuid": "<optional-folder-uuid>",
      "type": "erd",
      "title": "Production schema",
      "typePayload": {}
    }
  ]
}

타입별 payload:

Type	typePayload
erd	생성 시 보통 비워 둠. ERD 내용은 erd_* tool로 관리
diagram	diagramSource?, sourceLanguage?, edgeStyle?, isModule?, metadata?
markdown	body
openapi	content — OpenAPI / Swagger 원문(YAML 또는 JSON). 쓴 그대로 저장

본문이 크면 request_upload_token을 purpose=document.create, document.update, document.append로 발급받아 chat prompt 대신 직접 업로드하세요.

---

ERD Tools (10)

ERD 문서 lifecycle은 generic tool을 사용합니다. list_documents(type=erd)로 ERD 문서를 찾은 뒤 그 UUID를 documentUuid로 넘기세요.

Tool	주요 input shape	목적
erd_apply_changes	documentUuid, description, operations[], arrangeNewTables?	ERD 내용 생성/수정/삭제의 유일한 경로
erd_arrange_tables	documentUuid, full?	새 table 자동 배치, full=true 면 전체 재배치
erd_list_tables	documentUuid	table 목록
erd_get_table	documentUuid, tableUuid	table 단건(컬럼·인덱스 포함)
erd_list_refs	documentUuid	relationship 목록
erd_get_ref	documentUuid, refUuid	relationship 단건
erd_list_table_groups	documentUuid	table group 목록
erd_get_table_group	documentUuid, tableGroupUuid	table group 단건
erd_list_enums	documentUuid	enum 목록
erd_get_enum	documentUuid, enumUuid	enum 단건

erd_apply_changes.operations[] 원소는 {op: create|update|delete, type, uuid?, data?} 입니다.

• type: table, column, index, index_column, ref, ref_column, enum, enum_value, table_group, table_group_table, table_group_note, filter, note.
• data 필드 이름은 snake_case 입니다(table_uuid, is_pk, from_table_uuid …).
• 생성할 때 data.uuid 를 직접 정해 넣으면 같은 배치의 뒤 operation 이 그 값을 참조할 수 있습니다. operation 의 uuid 는 수정/삭제 대상일 때만 씁니다.
• ref.relationship 은 >, <, - 입니다. FK 컬럼은 ref_column operation 으로 명시하고, enum 값은 별도 enum_value operation 으로 만듭니다.

---

Diagram Tools (10)

Diagram 문서 lifecycle도 generic입니다. 문서 자체는 create_documents(type=diagram) 또는 list_documents(type=diagram)로 다루고, 그 UUID를 diagramUuid로 넘기세요.

Tool	주요 input shape	목적
diagram_apply_changes	diagramUuid, description, nodes?, edges?, groups?	node/edge/group 생성·수정·삭제의 유일한 경로
diagram_list_nodes	diagramUuid	node 목록
diagram_get_node	nodeUuid	node 단건
diagram_list_edges	diagramUuid	edge 목록
diagram_get_edge	edgeUuid	edge 단건
diagram_list_groups	diagramUuid	group 목록
diagram_get_group	groupUuid	group 단건
diagram_get_pending_llm_requests	없음	대기 중인 LLM handoff request 목록
diagram_submit_llm_result	uuid, result, token 수	LLM handoff 결과 제출
diagram_update_llm_request_status	uuid, status=FAILED, errorMessage?	LLM handoff request 실패 처리

diagram_apply_changes는 node/edge/group item마다 action: create|update|delete를 씁니다. node 필드는 text, shape, x, y, width, height, groupUuid, fillColor, strokeColor, textColor 등이고, edge 필드는 fromUuid, toUuid, label, lineStyle, strokeColor, strokeWidth 등, group 필드는 name, color, parentGroupUuid, width, height 등입니다.

---

Markdown Tools (2)

Markdown document의 full-body create/update는 generic tool을 사용합니다. create_documents(type=markdown) 또는 update_documents에서 typePayload.body를 넘기세요.

Tool	주요 input shape	목적
markdown_append_document	document append payload	기존 Markdown document에 markdown append
markdown_generate_document	prompt/project payload	AI로 Markdown document 생성

CLI command path도 같은 public surface를 사용합니다: documents create, documents update, markdown append-document, markdown generate-document.

---

예시

ERD document 찾기

{
  "name": "list_documents",
  "arguments": {
    "type": "erd",
    "q": "production schema",
    "limit": 10
  }
}

ERD document 생성

{
  "name": "create_documents",
  "arguments": {
    "items": [
      {
        "projectUuid": "<project-uuid>",
        "type": "erd",
        "title": "Billing schema"
      }
    ]
  }
}

table 과 외래 키를 한 번에 생성

{
  "name": "erd_apply_changes",
  "arguments": {
    "documentUuid": "<erd-document-uuid>",
    "description": "Add notifications with a FK to users",
    "operations": [
      {"op": "create", "type": "table", "data": {"uuid": "tbl_notifications", "name": "notifications"}},
      {"op": "create", "type": "column", "data": {"uuid": "col_n_id", "table_uuid": "tbl_notifications", "name": "id", "type": "bigint", "is_pk": true, "is_not_null": true}},
      {"op": "create", "type": "column", "data": {"uuid": "col_n_user_id", "table_uuid": "tbl_notifications", "name": "user_id", "type": "bigint", "is_not_null": true}},
      {"op": "create", "type": "ref", "data": {"uuid": "ref_n_user", "from_table_uuid": "tbl_notifications", "to_table_uuid": "<users-table-uuid>", "relationship": ">", "on_delete": "CASCADE"}},
      {"op": "create", "type": "ref_column", "data": {"ref_uuid": "ref_n_user", "from_column_uuid": "col_n_user_id", "to_column_uuid": "<users-id-column-uuid>"}}
    ]
  }
}

기존 table·column UUID 는 erd_get_table 로 얻습니다.

Markdown document 생성

{
  "name": "create_documents",
  "arguments": {
    "items": [
      {
        "projectUuid": "<project-uuid>",
        "type": "markdown",
        "title": "API notes",
        "typePayload": {
          "body": "# API notes\n\nInitial draft."
        }
      }
    ]
  }
}

document 공유 활성화

{
  "name": "enable_shares",
  "arguments": {
    "targetType": "document",
    "targetUuids": ["<document-uuid>"]
  }
}

---

오류 처리

tool은 표준 JSON-RPC error response를 반환합니다.

Error	원인
401 Unauthorized	token 누락 또는 만료. 재인증 필요
403 Forbidden	view/edit 권한 없음
404 Not Found	workspace, project, folder, document 또는 entity UUID 오류
409 Conflict	동시 편집 충돌. 현재 상태를 다시 읽고 재시도
429 Too Many Requests	rate limit. backoff 후 재시도