informer-mcp

Informer 회계 API(v2)용 Model Context Protocol 서버입니다. 모든 MCP 클라이언트가 거래처, 매출·매입 송장, 견적서, 주문서, 영수증, 제품, 재무 보고서에 직접 접근할 수 있게 해줍니다.

모든 도구는 Informer 자체 OpenAPI 문서(api.informer.eu/docs/v2)에서 파생되었습니다. 서버에는 사본이 포함되어 있어 오프라인에서도 작동하며, 최신 상태를 유지합니다 — API 변경사항 추적 참조.

비공식 프로젝트입니다. Informer와 제휴하거나 보증하지 않습니다.

빠른 시작

MCP 서버를 설치할 수 있는 모든 AI 어시스턴트에 다음을 붙여넣으세요:

Install the following MCP server: https://github.com/vladxyz/informer-mcp and run the local setup screen for the API keys.

저장소를 클론하고, 빌드하고, 클라이언트에 서버를 등록한 다음 informer-mcp setup을 실행합니다 — 그러면 브라우저에서 127.0.0.1 페이지가 열립니다. 그 페이지에서 API 자격 증명을 입력합니다. 채팅에서 아무것도 요구하지 않으며, 어떤 키도 대화에 붙여넣지 않습니다.

페이지에서 볼 수 있는 것

관리(administration)당 카드 하나씩, 그리고 여러 개를 관리하는 경우 관리 추가 버튼이 표시됩니다:

┌─ Administration ────────────────────────────── Remove ─┐
│  ALIAS                        COMPANY NAME             │
│  [ acme                ]      [ ACME BV           ]    │
│  Short handle you use         Optional, shown in       │
│  in prompts.                  tool descriptions.       │
│                                                        │
│  API KEY                      SECURITY CODE            │
│  [ •••••••••••••••••  ]      [ •••••••••••••••  ]     │
│                                                        │
│  ACCESS                                                │
│  [ Read and write   ▾ ]                                │
│  Read only hides every tool that changes this          │
│  client's books.                                       │
└────────────────────────────────────────────────────────┘

  [ Add administration ]   [ Verify & save ]   ☐ Save without verifying

두 자격 증명은 모두 하나의 관리에 속하므로, 회계사는 클라이언트마다 카드를 하나씩 추가합니다. 여러 클라이언트 관리 참조.

"확인 및 저장"을 누르면 일어나는 일

1. 각 키/보안 코드 쌍이 API에 대해 검증되고, 페이지에 실제로 속한 회사 이름이 표시됩니다 — 잘못된 행에 붙여넣은 키는 저장되기 전에 명확히 드러납니다.

2. 쌍이 거부되면 아무것도 저장되지 않고 실패한 행이 표시됩니다. 오프라인일 때처럼 그래도 저장하려면 검증 없이 저장을 체크하세요.

3. 성공하면 자격 증명이 0600 권한으로 ~/.informer-mcp.json에 기록됩니다. open_setup으로 열면 실행 중인 서버가 즉시 변경사항을 감지합니다 — 새 관리가 바로 다음 메시지에서 선택 가능합니다. 터미널에서 열었다면 클라이언트를 다시 시작하세요.

*"어떤 관리에 접근할 수 있나요?"*라고 물어 확인하세요 — list_administrations를 호출하여 각 별칭과 회사를 나열합니다.

Related MCP server: billingo-mcp

제공되는 것

• 49개 문서화된 엔드포인트를 모두 다루는 68개 도구 — 읽기 및 쓰기.

• 브라우저에서 설정. 어시스턴트에게 설정 페이지를 열어달라고 하거나 informer-mcp setup을 실행하세요. 모든 키를 API에 대해 검증하고, 설정 파일을 작성하며, 재시작 없이 변경사항이 적용됩니다.

• API를 따릅니다. Informer가 새 엔드포인트를 게시하면 서버가 이를 감지하고 클라이언트가 연결된 상태에서 도구를 추가합니다 — 재설치나 재시작 불필요.

• 하나의 서버에서 여러 클라이언트 관리. 회계사는 하나의 연결로 모든 클라이언트의 장부에 접근할 수 있으며, 둘 이상이 설정된 경우 administration 인자가 필수입니다.

• 포트폴리오 전체에 걸친 단일 질문. 읽기 전용 도구는 별칭 목록 또는 "all"을 받아 동시에 조회하고, 클라이언트별로 키가 지정된 결과를 반환합니다.

• 전체 요청 스키마. 생성/업데이트 도구는 페이로드에 대한 완전한 JSON Schema를 광고하므로, 모델이 아무것도 보내기 전에 어떤 필드가 있고 어떤 것이 필수인지 알 수 있습니다.

• 읽기 전용 또는 읽기-쓰기, 선택 사항. --read-only 플래그는 변경하는 모든 도구를 숨기며, 개별 클라이언트는 나머지가 쓰기 가능한 동안 읽기 전용으로 고정할 수 있습니다. 허용/거부 목록으로 표면을 더 좁힐 수 있습니다.

• PDF 및 첨부 파일은 base64에서 디코딩되어 디스크에 직접 쓸 수 있습니다.

• 탄력적인 HTTP. 타임아웃, Retry-After 지원 재시도, Informer의 네덜란드어 검증 오류를 그대로 표시(HTTP 422: invoice_date: ongeldig).

요구 사항

• Node.js 20 이상

• API 접근이 가능한 InformerOnline 계정

자격 증명 설정

대화에서 그냥 물어보세요:

"Informer 관리 구성을 변경하고 싶어요" "Informer에 새 클라이언트를 추가해줘" "Informer API 키가 변경되었어요"

어시스턴트가 open_setup 도구를 호출하면 페이지가 열립니다. 찾을 설정 파일도, 손으로 편집할 것도 없습니다. 페이지가 브라우저 양식이므로 API 키를 채팅에 입력할 필요가 전혀 없습니다.

터미널에서도 같은 페이지를 열 수 있습니다:

npm run setup          # or: informer-mcp setup

어느 쪽이든 브라우저에 http://127.0.0.1:<port>가 열리고, 각 관리에 대한 양식이 표시됩니다: 별칭, 회사 이름, API 키, 보안 코드, 쓰기 가능 여부. 저장하면 모든 쌍이 API에 대해 검증됩니다 — 잘못 입력한 키는 즉시 잡히고, 각 키가 실제로 속한 회사 이름이 표시됩니다 — 그런 다음 ~/.informer-mcp.json을 0600 권한으로 기록합니다.

자격 증명 없이 서버를 시작하면 정확히 그 순간이 필요하므로 같은 페이지가 자동으로 열립니다. INFORMER_AUTO_SETUP=false로 끄거나, 헤드리스 머신에서 INFORMER_OPEN_BROWSER=false로 URL만 출력할 수 있습니다. 어떻게 열었든 페이지는 하나뿐입니다: 다시 요청하면 같은 URL이 반환됩니다.

페이지가 의도적으로 하는 몇 가지:

• 127.0.0.1에만 바인딩하며, 실행마다 URL과 저장 요청에 있어야 하는 임의 토큰을 생성하므로 브라우저의 다른 사이트가 게시할 수 없습니다.

• 저장된 키를 페이지로 다시 보내지 않습니다 — 기존 관리의 자격 증명은 비워 표시되며, 새 값을 입력하지 않는 한 유지됩니다.

• API가 거부하는 자격 증명은 검증 없이 저장을 체크하지 않는 한 저장을 거부합니다.

파일이나 환경 변수를 직접 작성하는 것을 막는 것은 없습니다. 페이지는 편의일 뿐 필수는 아닙니다.

키는 어디서 오는가

API는 두 개의 헤더로 인증하며, 둘 다 필수입니다:

둘 다 하나의 관리에 범위가 지정됩니다: API 키는 생성된 관리에 속하며(GET /administration은 "이 API 키에 연결된 관리"를 반환), 보안 코드는 그 회사를 식별합니다. 관리 목록을 나열하거나 전환하는 엔드포인트는 없습니다.

키는 해당 관리의 장부에 대한 전체 접근 권한을 부여합니다. 비밀번호처럼 취급하세요: 환경, 비밀 관리자, 또는 저장소 외부의 설정 파일에 보관하세요.

여러 클라이언트 관리

여러 클라이언트를 가진 회계사는 클라이언트 관리당 하나의 키/보안 코드 쌍이 필요합니다 — 관리에 접근할 수 있는 회계사 사용자는 설정에서 생성할 수 있습니다. 설정 페이지에서 추가하거나, ~/.informer-mcp.json(또는 INFORMER_CONFIG_FILE이 지정하는 파일)을 직접 작성하세요:

{
  "administrations": {
    "acme":     { "label": "ACME BV",         "api_key": "...", "security_code": "..." },
    "bakkerij": { "label": "Bakkerij de Bol", "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

둘 이상의 관리가 설정된 경우 모든 도구는 administration 인자를 요구하며, 별칭의 enum으로 광고됩니다:

list_sales_invoices({ "administration": "acme", "filter": "open" })

의도적으로 기본값이 없습니다. 잘못된 클라이언트의 원장에 송세를 기입하는 것은 조용히 일어나서는 안 되는 유일한 실수이므로, 인자 없이 호출하면 HTTP 요청 전에 스키마 검증에서 거부됩니다 — 설정하지 않은 별칭도 마찬가지입니다.

list_administrations는 설정된 별칭을 표시합니다. verify: true를 전달하면 API에서 각 회사 이름을 가져와 자격 증명이 작동하는지와 모든 별칭이 생각하는 회사를 가리키는지 확인합니다.

여러 클라이언트를 한 번에 조회

읽기 전용 도구는 별칭 목록 또는 "all"도 허용합니다:

list_sales_invoices({ "administration": "all", "filter": "open", "records": 50 })
list_sales_invoices({ "administration": ["acme", "bakkerij"], "filter": "open" })

관리들은 동시에 조회되고(INFORMER_FANOUT_CONCURRENCY, 기본 4개씩) 답변은 별칭으로 키가 지정됩니다:

{
  "administrations": ["acme", "bakkerij"],
  "results": {
    "acme": { "pagination": { "total": 3 }, "invoices": [ ... ] },
    "bakkerij": { "error": "[bakkerij] HTTP 401: Authentication failed" }
  }
}

알아두면 좋은 세 가지 속성:

• 한 클라이언트가 실패해도 조회가 무너지지 않습니다. 해당 항목에 error가 표시되고 나머지는 여전히 데이터를 반환합니다.

• 응답 예산은 균등하게 분할됩니다. 각 관리에 INFORMER_MAX_RESPONSE_CHARS / n 문자가 할당되므로, 큰 클라이언트 하나가 다른 것을 밀어내지 못합니다. 할당량을 초과하면 { "truncated": true, "partial": ... }로 반환됩니다.

• 팬아웃은 읽기 전용입니다. 쓰기 도구와 PDF/첨부 다운로드는 단일 별칭만 받습니다 — 스키마에 배열이나 "all"조차 없으며, 핸들러가 두 번째로 거부합니다. 12개 관리에 같은 송세를 만드는 것은 절대 우연으로 가능한 일이 아닙니다.

단일 관리의 경우 — 일반적인 경우 — API 페이로드를 이전과 동일하게 래핑하지 않고 반환합니다.

단일 관리 — 일반적인 경우 — 아무것도 변경되지 않습니다: INFORMER_API_KEY와 INFORMER_SECURITY_CODE를 평소처럼 설정하면 인자는 선택 사항으로 유지됩니다.

설치

git clone https://github.com/vladxyz/informer-mcp.git
cd informer-mcp
npm install          # also builds dist/ via the prepare script
npm run setup        # opens a local page to enter your API credentials

설정 페이지는 127.0.0.1에서 실행되고, 모든 키를 API에 대해 검증하며, ~/.informer-mcp.json을 기록합니다. 자격 증명 설정 참조.

Claude Desktop, 확장으로

가장 친근한 방법: 번들을 빌드하고 열기.

npm run bundle          # writes informer-mcp.mcpb

Claude Desktop에서 **설정 → 확장 → 고급 설정 → 확장 설치…**로 이동하여 .mcpb 파일을 선택하세요. 자체 종속성을 포함하므로 Node.js 20 외에 먼저 설치할 것이 없습니다.

설치 대화 상자에서 API 키, 보안 코드, 읽기 전용 스위치를 제공합니다. 세 개 모두 비워 둘 수 있습니다: 그러면 서버가 처음 시작할 때 설정 페이지를 열며, 둘 이상의 관리를 구성하는 유일한 방법이기도 합니다.

Claude Desktop의 설정 → 커넥터 → 사용자 지정 커넥터 추가는 다른 것입니다: 원격 MCP 서버의 URL을 받습니다. 이 서버는 stdio를 통해 로컬에서 실행되므로 커넥터가 아닌 확장으로 설치됩니다.

Claude Desktop, 수동으로

설정 파일을 직접 편집하세요:

{
  "mcpServers": {
    "informer": {
      "command": "node",
      "args": ["C:\\path\\to\\informer-mcp\\dist\\index.js"]
    }
  }
}

이후 Claude Desktop을 재시작하세요. Windows에서는 JSON의 백슬래시를 두 번 써야 합니다. 슬래시도 작동하며 읽기 쉽습니다.

다른 모든 MCP 클라이언트

서버는 stdio를 통해 MCP를 사용하므로 모든 클라이언트가 동일하게 구성합니다 — 명령과 인자. 위 블록은 Claude Code(claude mcp add), Cursor, Zed 또는 MCP를 말하는 다른 어떤 것에서도 그대로 작동합니다.

자격 증명은 ~/.informer-mcp.json에서 오므로 클라이언트 설정에 반복할 필요가 없습니다. 클라이언트별로 전달하려면 INFORMER_API_KEY와 INFORMER_SECURITY_CODE가 있는 env 블록을 추가하거나 INFORMER_CONFIG_FILE을 다른 곳으로 지정하세요.

args에 "--read-only"를 추가하면 아무것도 변경할 수 없는 서버를 등록할 수 있습니다 — 읽기 전용 또는 읽기/쓰기를 참고하세요. 같은 서버를 두 번 등록하되, 하나는 읽기 전용으로 하나는 읽기/쓰기로 등록하는 것도 잘 작동합니다.

stdout은 프로토콜을 전달하므로 모든 로깅은 stderr로 기록됩니다. 시작 시 한 줄 배너가 등록된 도구 수와 발견한 관리(administrations) 항목을 알려줍니다.

읽기 전용 또는 읽기/쓰기

기본적으로 모든 도구를 사용할 수 있습니다. 쓰기 도구를 완전히 제거하려면 서버를 플래그와 함께 시작하세요:

informer-mcp --read-only     # only the tools that read
informer-mcp --read-write    # the default: create, update and delete too

INFORMER_READ_ONLY=true도 동일하게 작동하며, 플래그가 변수보다 우선합니다. 그래서 한 클라이언트에 같은 서버를 두 번 등록할 수 있습니다. 일상적인 질문을 위한 읽기 전용 세션과, 실제로 무언가를 기록하는 세션을 위한 읽기/쓰기 세션으로 나눠서 등록할 수 있습니다.

읽기 전용 모드에서는 쓰기 도구가 아예 등록되지 않습니다. 도구 목록에 나타나지 않으므로 모델이 사용하려 손댈 수 있는 것이 없습니다.

클라이언트별

개별 관리 항목은 구성 파일에 고정할 수 있습니다. 일부 클라이언트의 장부만 열람해야 하는 경우에 유용한 형태입니다:

{
  "administrations": {
    "acme":     { "api_key": "...", "security_code": "..." },
    "bakkerij": { "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

"read_only": true는 축약 표기로 동작합니다. 가장 제한적인 설정이 우선합니다:

따라서 읽기 전용으로 표시된 클라이언트는 실수로 쓰기 작업이 발생할 일이 없고, --read-only로 시작한 세션은 구성 파일의 내용과 관계없이 그 상태를 유지합니다.

일부 관리 항목만 쓰기 가능한 경우, 쓰기 도구는 등록된 채로 유지되지만 해당 도구의 administration enum에는 쓰기 가능한 항목만 제공됩니다. 읽기 전용 클라이언트에서 인보이스 생성을 요청하면 HTTP 요청이 발생하기 전에 거부됩니다:

Administration(s) bakkerij are configured as read-only, so this tool cannot change them.
Writable: acme, garage.

list_administrations는 각 클라이언트의 유효 모드를 보고하며, 시작 배너에는 read-write: acme, garage처럼 요약이 표시됩니다.

구성

필터는 OpenAPI 태그 또는 도구 이름을 받으며, 대소문자와 구두점을 구분하지 않고 매칭됩니다:

# read-only access to invoicing data
INFORMER_TOOLS="Sales Invoices,Relations" node dist/index.js --read-only

# everything except deleting attachments
INFORMER_EXCLUDE_TOOLS=delete_sales_invoice_attachment node dist/index.js

사용하기

연결된 이후에는 자연어로 질문하세요:

• "2026년의 매출 인보이스 중 아직 결제되지 않은 것은?" → filter와 함께 list_sales_invoices

• "ACME에 대해 시간당 €125로 10시간 컨설팅한 내용의 초안 인보이스를 만들어 주세요." → 유효한 원장/VAT/템플릿 ID를 얻기 위해 get_sales_invoice_options를 호출한 뒤, create_sales_invoice

• "인보이스 12345를 PDF로 바탕 화면에 다운로드해 주세요." → save_path와 함께 get_sales_invoice_pdf

• "2026년 6기의 대차대조표를 보여 주세요." → get_balance_report

알아두면 좋은 규칙

• 관리 항목을 명시적으로 선택하세요. 여러 클라이언트가 구성되어 있으면 모든 도구가 administration: "<alias>"를 받습니다. list_administrations는 별칭을 회사에 매핑하고, 읽기 전용 도구는 목록이나 "all"도 받을 수 있습니다.

• 날짜는 항상 YYYY-MM-DD입니다.

• 목록 도구에는 페이지네이션이 있습니다. page(기본값 1)와 records(기본값 20)를 사용하며, total과 pages를 포함한 pagination 객체를 반환합니다.

• 요청 페이로드는 단일 body 인자로 전달됩니다. 경로 파라미터와 쿼리 파라미터는 최상위에 유지되므로, update_relation은 { "id": 42, "body": { ... } } 형태를 받습니다.

• 문서를 생성할 때는 먼저 *_options 도구를 호출하세요. get_sales_invoice_options, get_quotation_options 및 유사한 도구는 해당 관리 항목에서 유효한 원장, VAT, 템플릿, 통화, 지급 조건 ID를 반환합니다.

• 보고서는 명시적인 범위가 필요합니다. get_balance_report는 year_from, year_to, period를 요구하며, get_column_balance_report는 원장 범위도 요구합니다.

PDF 및 첨부 파일

Informer는 파일을 JSON 안의 base64로 반환합니다. 이 작업을 수행하는 도구(get_*_pdf, download_sales_invoice_attachment)는 선택적 save_path를 받습니다:

• save_path를 지정하면 — 파일이 디코딩되어 해당 경로에 저장되고, 도구는 { saved_to, filename, bytes, mime_type }을 반환합니다.

• save_path 없이 — 파일은 올바른 MIME 유형을 가진 인라인 MCP 리소스로 반환됩니다. 커다란 문서는 컨텍스트에서 비용이 많이 들 수 있습니다.

업로드는 반대 방향입니다: upload_sales_invoice_attachment는 { filename, file }을 받습니다. 여기서 file은 base64로 인코딩된 내용(최대 10MB, PDF, PNG, JPEG, GIF, DOC(X), XLS(X))입니다.

도구 참조

npm run tools는 현재 스펙에서 이 목록을 출력하고, npm run tools -- --md는 아래 표를 다시 생성합니다.

엔드포인트 도구 외에도 서버에서 제공하는 도구 세 가지가 있습니다:

관리

관계

연락처

매출 인보이스

매입 인보이스

정기 인보이스

판매 주문

견적서

매출장

결제 조건

템플릿

VAT

원장

비용

통화

분개

구독 유형

첨부 파일

제품

영수증

메모

보고서

도구 명명 규칙

도구 이름은 문서의 문구가 아니라 HTTP 메서드와 경로에서 파생되므로 스펙 업데이트가 있어도 안정적으로 유지됩니다.

명명 테이블에서 인식하지 못하는 엔드포인트는 <동사>_<경로 slug>로 대체되므로 스펙을 갱신해도 도구가 깨지지 않습니다.

API 변경사항 파악하기

도구는 Informer의 OpenAPI 문서를 기반으로 생성됩니다. 따라서 Informer가 엔드포인트를 추가했을 때 필요한 것은 최신 문서 사본뿐이며, 서버가 스스로 이 문서를 가져올 수 있습니다.

우선순위대로 세 가지 계층이 있습니다:

1. 다운로드된 사본 — ~/.informer-mcp.spec.json에 캐시됩니다.

2. 번들로 포함된 사본 — 서버와 함께 제공되며 오프라인에서도 항상 동작하는 openapi/api-docs.json 파일입니다.

3. 다음 중 하나도 맹목적으로 신뢰하지 않습니다. 다운로드는 OpenAPI 3 문서로 파싱되어야 하며 최소 하나의 작동 가능한 작업이 있어야 합니다. 그렇지 않으면 거부되고 현재 도구가 유지됩니다. 포털 페이지나 유지보수 페이지로 인해 도구가 사라질 수 없습니다.

정기적인 갱신

서버는 시작한 직후 하루에 한 번 배경에서 더 최신 문서를 확인합니다. 시작이 차단되지는 않으며, 갱신 실패는 로그로만 남기고 무시합니다. INFORMER_SPEC_MAX_AGE_HOURS=0으로 비활성화할 수 있습니다.

요청 시 갱신

refresh_api_spec 도구를 요청하면 같은 작업이 수행됩니다. 예상한 엔드포인트가 없거나 인자가 알 수 없는 값으로 거부될 때 특히 유용합니다.

"Informer API 설명을 새로고침하고 어떤 것이 바뀌었는지 알려 주세요."

{
  "adopted": true,
  "api_version": "2.0.0",
  "endpoints": 49,
  "tools": 68,
  "changes": {
    "added":   [{ "tool": "list_projects", "endpoint": "GET /projects" }],
    "removed": [],
    "changed": [{ "tool": "create_sales_invoice", "endpoint": "POST /invoices/sales",
                  "notes": ["body now requires: project_id"] }],
    "unchanged": 66
  },
  "note": "The tool list has been updated; no restart is needed."
}

dry_run을 전달하면 아무것도 적용하지 않고 해당 보고서를 확인할 수 있습니다.

diff는 의도적으로 구체적입니다. 새로 나타나거나 사라진 도구를 지목하고, 변경된 도구에 대해서는 무엇이 바뀌었는지 알려 줍니다 — 새 인자, 삭제된 인자, 이제 필수가 된 항목 등입니다. 단순한 경로 비교로는 놓치기 쉬운 부분이며, 보통 당혹스러운 422 오류로 표면화되곤 합니다.

문서 적용을 반영하면 실행 중인 서버가 바로 업데이트됩니다. 새 도구가 등록되고, 사라진 도구는 제거되며, 변경된 도구는 다시 공개되고, tools/list_changed 알림이 전송되어 클라이언트가 세션 중에 목록을 다시 불러옵니다.

저장소에 있는 사본

npm run update-spec은 bundled 문서를 업데이트하고 어떤 경로가 추가/제거되었는지 보고합니다. 서버를 설치하는 모든 사람에게 변경을 반영하려면 이 명령을 실행하면 됩니다. refresh_api_spec은 사용자 자신의 머신에만 영향을 줍니다.

리소스

서버는 OpenAPI 문서 자체를 informer://openapi.json MCP 리소스로도 노출합니다. 모델이 추측하지 않고 필드 정의를 확인할 필요가 있을 때 유용합니다.

개발

npm install         # install + build
npm run setup       # enter credentials in the browser
npm run bundle      # package as informer-mcp.mcpb for one-click install
npm run dev         # run from source with tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run tools       # print the tool surface
npm run update-spec # re-download openapi/api-docs.json and report added/removed paths

프로젝트 구조

openapi/api-docs.json   vendored OpenAPI 3.0 document — the source of truth
src/openapi.ts          spec → operations: tool names, JSON Schema conversion
src/client.ts           HTTP client: auth headers, retries, error formatting
src/tools.ts            operations → MCP tools, filtering, result formatting
src/server.ts           server assembly (tools + openapi resource)
src/spec.ts             download, validate, cache and diff the OpenAPI document
src/setup.ts            local setup server: verify credentials, write the config file
src/setup-page.ts       the HTML it serves
src/index.ts            stdio entry point and CLI
manifest.json           extension manifest: entry point and install-time settings
scripts/update-spec.mjs refresh the vendored spec
scripts/list-tools.ts   print/regenerate the tool reference
scripts/bundle.mjs      stage production dependencies and pack the .mcpb

엔드포인트를 추가하는 것은 보통 코드 변경이 전혀 아닙니다. 실행 중인 서버가 자동으로 엔드포인트를 불러오고, npm run update-spec이 동일한 변경을 번들 사본에 반영합니다. 실제로 새로운 URL 형태만 src/openapi.ts의 RESOURCES 테이블에 규칙이 필요합니다. 규칙이 없어도 도구로는 등록되며 다만 휴대 이름을 얻게 됩니다.

스키마 변환 방식

OpenAPI 3.0은 JSON Schema와 정확히 같지 않습니다. MCP 도구 정의로 변환되는 과정에서:

• #/components/schemas/X 참조는 #/$defs/X가 되며, 각 작업이 실제로 필요한 전이적 클로저만 인라인됩니다 — 그래서 도구 정의가 작게 유지됩니다.

• nullable: true는 ["type", "null"] 유니언이 됩니다.

• path 및 query 매개변수는 최상위 속성이 되고, request body는 body 아래에 배치되며, additionalProperties: false로 오타가 API에 전달되지 않습니다.

인자는 모든 HTTP 호출 전에 해당 스키마에 대해 검증됩니다.

안전 참고사항

• 이 서버는 실제 부기 기록을 생성, 업데이트, 삭제할 수 있습니다. 보고만 필요한 경우 --read-only로 시작하고, 개별 클라이언트는 "mode": "read-only"로 고정한 다음, MCP 클라이언트가 쓰기 도구에 대한 승인을 요청하도록 하세요.

• 하나의 프로세스에 여러 클라이언트의 자격 증명이 있으면 잘못 라우팅된 호출 하나가 다른 사람의 장부에 닿을 수 있습니다. 필수 administration 인자, 알려진 별칭의 열거형, 팬아웃에 대한 읽기 전용 제한, 모든 오류 메시지의 별칭 접두사 ([acme] HTTP 422: ...)는 모두 이러한 이유로 존재합니다. 구성 파일을 버전 관리에서 제외하고 본인만 읽을 수 있게 유지하세요.

• 도구에는 readOnlyHint, destructiveHint, idempotentHint가 주석으로 표시되어 있어, 이러한 힌트를 사용하는 클라이언트는 위험한 도구를 차단할 수 있습니다.

• stdout에는 아무것도 기록되지 않으며, 자격 증명은 도구 출력에 표시되거나 설정 페이지로 다시 전송되지 않습니다. open_setup은 URL을 반환할 뿐 키를 반환하지 않습니다. 어시스턴트는 사용자의 자격 증명을 읽을 방법이 없으며 채팅에서 이를 요청할 이유도 없습니다.

• API 설명은 자격 증명 없이 다운로드되며, 사용 가능한 OpenAPI 3 파일로 파싱되지 않는 문서는 채택되지 않고 거부됩니다.

라이선스

MIT — LICENSE 참조.