대상은 fbmcp를 설치하고 운영하는 사람입니다. 직접 빌드하지 않았습니다. Go나 Firebird 내부 지식은 필요 없습니다. 기준 시점은 2026-11-16이고, 버전은 2027.2.24입니다(로컬 모드와 원격 모드, HQbird 설치, fbagent 브리지, HQbird 클러스터, 결과 그리드).

이 사이트에는 없는 짧은 판: quickstart-en.md, quickstart-ru.md, quickstart-pt.md. 자세한 내용은 영어입니다. remote.md(원격 모드), agent-bridge.md(fbagent), tool-reference.md(모든 도구, 그 Tier와 인수), claude-desktop.md(개발 호스트에서의 클라이언트 연결), ADR은 decisions/에 있습니다.


1. fbmcp란

fbmcp는 Windows와 Linux에서 Firebird 2.5–5.0을 위한 MCP 서버입니다. MCP 클라이언트(Claude Desktop, Claude Code, Cursor, Codex, ZCode, 그 밖)는 이것을 써서 DBA로 일합니다. 모니터링, 백업과 검증된 복원, SQL/DDL/DCL, 인덱스, 사용자와 권한, firebird.conf, 스케줄러, 마이그레이션, HQbird fbagent, HQbird 클러스터입니다. 도구 122개가 있습니다. 읽기 전용 56개(Tier 0), Tier 1이 44개, Tier 2가 21개, Tier 3이 1개(비활성)입니다. fb_demo_write는 서버가 FBMCP_DEMO_TOOLS=1로 동작할 때만 있습니다.

클라이언트가 보는 것은 자신이 쓸 수 있는 도구뿐입니다. 도구 목록이 숨기는 것: Tier 3, 신원 최대 Tier를 넘는 도구, 읽기 전용 신원에 대한 fb_confirm과 fb_cancel, agents:가 비어 있는 동안의 fbagent 도구 (fb_agent_discover와 fb_agent_register는 남음), 어떤 데이터베이스에도 migrations_dir이 없는 동안의 마이그레이션 도구, fbmcp.yaml에 rcm: 섹션이 없는 동안의 클러스터 도구. 구성 다시 읽기로 이 집합이 바뀌면, 클라이언트는 새 목록을 받습니다. 숨긴 도구를 직접 호출하면 분명한 거부가 돌아옵니다.

바이너리 역할
fbmcp 서버입니다. 기본값: stdio 위의 MCP(클라이언트가 시작합니다). -serve: stdio 없이 서비스로 동작합니다(스케줄러, 어태치 소켓, 구성되어 있으면 HTTPS 리스너). fbmcp bridge: 원격 fbmcp용 stdio 클라이언트
fbmcpctl 운영자 CLI: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. fbmcp ctl과 같은 프로그램입니다
fbmcp-tray Windows 트레이: 운영자가 필요한 요청의 승인/거부 팝업

상태 디렉터리마다 커널은 하나입니다. 같은 구성의 두 번째 클라이언트는 두 번째 커널을 시작하지 않습니다. 실행 중인 커널에 붙습니다.

2. 안전 모델

모든 호출은 정책 → 사람의 확인 → 감사되는 실행 순으로 통과합니다.

Tier 내용 확인 방법
0 읽기(엔진이 강제하는 읽기 전용 트랜잭션) 필요 없음
1 일상적인 변경: DML/DDL, 백업, 사용자, 권한 대역 내: 클라이언트가 요청 ID와 토큰을 보여주고, 사람이 동의하고, 클라이언트가 fb_confirm을 호출합니다
2 영향이 큼: 서비스 제어, 복원 교체, firebird.conf, 배타 창, 등록, 에이전트 재시작 대역 외에서만:트레이 또는 fbmcpctl approve. 클라이언트는 결코 승인할 수 없습니다
3 치명적(fb_db_drop) 설계상 비활성
  • Tier 2는 보통 열려 있는 유지 관리 창(같은 db에 대한 fb_window_open)과 24시간보다 새로운 검증된 백업이 필요합니다. 거부 문구에 무엇이 빠졌는지 나옵니다.
  • 대기 중인 요청은 15분 뒤에 만료됩니다. 다른 채널의 시도는 그 요청을 소비하지 않습니다. fb_cancel이 그것을 제거합니다.
  • 게이트된 도구는 모두 mode: preview를 받습니다. 영향을 보여주고 아무것도 하지 않습니다.
  • 모든 결정(허용, 대기, 승인, 거부)은 해시 체인으로 이어진 audit.jsonl에 들어갑니다.
  • 승인 웹 페이지는 없습니다. 있어서도 안 됩니다. 모델이 도달할 수 있는 페이지는 이 설계를 깨뜨립니다.

3. 구성 선택

구성 fbmcp가 실행되는 곳 쓸 때 절
A. 로컬 stdio 자신의 PC. 클라이언트가 시작함 관리자 한 명. Firebird는 이 PC 또는 LAN 안 §6
B. 로컬 서비스 DB 호스트의 Windows 서비스(-serve) 클라이언트를 열어 두지 않아도 스케줄이 돌아야 함 §7
C. 원격 DB 서버의 서비스. HTTPS와 API 키 관리자가 여러 명, 멀리 있는 서버, 자율 에이전트 §8

구성 A에서 커널은 클라이언트가 실행되는 동안에만 있으므로, 스케줄이 실행되는 것도 그때뿐입니다. 무인 스케줄(nightly_verify)에는 B 또는 C를 쓰십시오.

HQbird 안의 fbmcp. HQbird 2027 설치와 fbagent는 기본적으로 fbmcp를 설치합니다. 모든 Firebird 라인에 대해 서버당 서비스가 하나이고, fbmcp ctl hqbird-install이 설정합니다. 그런 서버에서는 §6–§8을 따르지 말고 hqbird.md(배치, --allow-from이 있는 원격 모드, API 키)를 읽으십시오.

4. 바이너리 받기

요구 사항: Go ≥ 1.26.11(더 오래된 Go 1.21 이상은 첫 빌드에서 go1.26.11을 스스로 받습니다. 여기에는 인터넷이 필요합니다), CGO는 필요 없음, Firebird 2.5–5.0, 에이전트 도구에는 Local API가 있는 fbagent ≥ 2.67 (선택), 클러스터 도구에는 fbagent 3.1.0 이상과 RCM 2027.5.11 이상 (선택).

Command
git clone https://github.com/alexeykovyazin/hqbirdmcp.git
cd hqbirdmcp
$env:CGO_ENABLED = "0"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp.exe ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl.exe ./cmd/fbmcpctl
go build -trimpath -ldflags "-s -w -H=windowsgui" -o dist/fbmcp-tray.exe ./cmd/fbmcp-tray

Linux 바이너리(Windows에서 크로스 빌드하거나, GOOS 없이 Linux에서 빌드):

Command
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl ./cmd/fbmcpctl

체크섬: Get-FileHash dist/* 또는 sha256sum dist/*. 그 밖의 대상: packaging/README.md. 바이너리는 전용 폴더에 둡니다 (예는 C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).

fbmcp ctl과 fbmcpctl은 같은 프로그램입니다. fbmcpctl help가 명령을 나열합니다. 구성을 읽는 명령은 --config <file>을 받습니다. 없으면 FBMCP_CONFIG, 다음으로 현재 폴더의 fbmcp.yaml, 다음으로 프로그램 옆, 다음으로 HQbird 기본값(C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml)을 쓰고, using config <path>를 출력합니다.

5. fbmcp.yaml 구성

전체 예: packaging/fbmcp.yaml.example. 최소 Windows 구성:

yaml
state:
  dir: C:\ProgramData\fbmcp\state
# secrets:
#   dir: C:\ProgramData\fbmcp\secrets   # setups B and C
instances:
  - id: fb5
    addr: localhost:3050
    bin_dir: C:\Program Files\Firebird\Firebird_5_0   # folder with gbak, gfix, gstat
    version: "5.0"
    service: FirebirdServerDefaultInstance            # Linux: firebird.opt_fb50
    service_user: SYSDBA                              # instance tools (fb_firebird_log, ...)
    service_secret_env: FBMCP_FB5_SERVICE_PW
databases:
  - id: main                 # tools and chats use the id, never the path
    instance: fb5
    path: D:\Data\main.fdb
    backup_dir: D:\fbmcp\backups
    work_dir: D:\fbmcp\work  # restore tests; Linux: not under /tmp
    ro_user: FBMCP_RO        # a read-only Firebird user
    ro_secret_env: FBMCP_MAIN_RO_PW
    admin_user: SYSDBA
    admin_secret_env: FBMCP_MAIN_ADMIN_PW
notify:
  webhook_url: ""            # optional: a chat webhook for pending requests
retention:
  keep_days: 0               # 0 = never delete backups

시크릿. YAML이 담는 것은 변수 이름뿐입니다. fbmcp는 각 값을 이 순서로 찾습니다. 환경 변수 → 파일 <secrets.dir>/<NAME> → fbmcp를 실행하는 계정의 OS 키링.

Command
C:\fbmcp\fbmcpctl.exe secret set FBMCP_MAIN_RO_PW                                     # keyring of the current user (setup A)
C:\fbmcp\fbmcpctl.exe secret set --dir C:\ProgramData\fbmcp\secrets FBMCP_MAIN_RO_PW  # secrets dir (setups B, C)

값은 stdin에서 읽습니다(입력한 뒤 Ctrl+Z, Enter. Linux에서는 Ctrl+D). 서비스 계정(LocalSystem, NT SERVICE\...)은 당신의 키링을 볼 수 없습니다. 서비스에는 secrets.dir을 쓰십시오. 바뀐 시크릿 파일은 재시작 없이 몇 초 안에 적용됩니다.

읽기 전용 사용자. ro_user용으로 별도의 Firebird 사용자를 만드십시오(SQL은 quickstart-en.md: CREATE USER FBMCP_RO, 모든 테이블에 GRANT SELECT, 그리고 Firebird 4.0 이상에서는 fb_sessions가 모든 연결을 보도록 MONITOR_ANY_ATTACHMENT가 있는 역할). RO 사용자로 SYSDBA를 쓰는 것은 개발 전용입니다. doctor가 경고합니다.

실시간 다시 읽기. fbmcp는 fbmcp.yaml의 변경을 스스로 적용합니다(파일 감시). fb_config_reload로도 적용합니다. 클라이언트나 프로세스를 다시 시작하지 않습니다. 다시 읽기는 변경된 데이터베이스의 작업을 기다린 뒤(30초) 적용합니다. 거부되는 것: state.dir 변경, 중복된 데이터베이스 경로, 안전하지 않은 원격 구성.

확인: C:\fbmcp\fbmcpctl.exe doctor는 doctor: green으로 끝나야 합니다 (원격 모드: doctor --remote, FAIL 줄 없음). 없는 상태 폴더를 만들고, 두 사용자로 각 데이터베이스에 로그인하며, 각 FAIL 줄은 Fix:와 실행할 명령으로 끝납니다.

6. 구성 A — 로컬 stdio

절대 경로를 쓰십시오. listen은 설정하지 마십시오. 구성을 바꾼 뒤에는 클라이언트를 다시 시작하십시오. 클라이언트는 시작할 때만 서버를 불러옵니다.

클라이언트 위치 항목
Claude Desktop Settings → Developer → Edit Config(%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code 명령줄 claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json 또는 프로젝트의 .cursor\mcp.json Claude Desktop과 같은 JSON
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml 또는 %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode 프로젝트의 .zcode\config.json "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

비밀번호는 키링에 있습니다(§5). 그래서 env 블록은 필요 없습니다. 그래도 클라이언트 env 블록에 비밀번호를 넣는다면, 그 파일은 git 밖에 두십시오.

그다음 Tier 2 승인을 위해 트레이를 시작하십시오. C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml(로그온할 때마다: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).

클라이언트에서 동작 확인: “fb_ping 호출”(서버 이름과 최대 Tier가 있는 자신의 신원을 보여 줌), 다음으로 “fb_db_list”, 다음으로 “main에 대한 fb_db_health”.

7. 구성 B — 로컬 Windows 서비스

관리자 권한의 PowerShell:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • 서비스는 fbmcp -serve를 LocalSystem으로 실행하고, 실패하면 다시 시작하며, 서비스 중지 때는 깨끗하게 멈춥니다.
  • 비밀번호에는 secrets.dir을 쓰십시오(§5).
  • 폴더를 잠그십시오. C:\fbmcp에 쓸 수 있는 것은 SYSTEM과 Administrators뿐입니다 (스크립트가 icacls 명령을 출력합니다). C:\ 바로 아래에 만든 폴더는 모든 사용자가 파일을 바꿀 수 있고, 서비스는 그 파일들을 SYSTEM으로 실행합니다.
  • 트레이 사용자와 로컬 stdio 클라이언트에는 상태 디렉터리의 읽기/쓰기가 필요합니다. icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". 같은 구성의 stdio 클라이언트는 그다음 서비스 커널에 붙습니다.
  • 준비 확인: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml.
  • 로그: <state_dir>\fbmcp.log(5 × 10 MiB. 충돌은 fbmcp-crash.log).

관리자가 네트워크로 도달하는 서비스에는 구성 C를 쓰십시오.

8. 구성 C — 원격(HTTPS + API 키)

전체 절차: remote.md. 짧은 형태:

Windows 서버(관리자 권한):

  1. 바이너리와 fbmcp.yaml을 C:\fbmcp\에 둡니다(템플릿: remote.md §3: listen, tls, identities, allowed_origins, secrets.dir).
  2. C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp" — 핀 sha256:...를 적어 둡니다.
  3. 사람 또는 에이전트마다 키 하나: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(한 번만 출력됨). --config C:\fbmcp\fbmcp.yaml을 주면 identities: 항목도 추가하고 secrets.dir을 씁니다.
  4. 비밀번호와 에이전트 토큰: fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME.
  5. .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf, 그다음 -WhatIf 없이. 서비스, 방화벽 규칙, 폴더 ACL, Firebird 서비스 권한을 만듭니다.
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → FAIL 없음. curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok.
  7. 승인자용 트레이: .\packaging\windows\install-tray.ps1.

Linux 서버(root): fbmcp, fbmcpctl, packaging/linux/를 복사한 다음

Command
install -m 0755 fbmcp fbmcpctl /usr/local/bin/
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24 --dry-run
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24

스크립트는 폴더, 인증서, admin 키가 있는 첫 구성 (한 번만 출력됨), systemd 유닛, Firebird 유닛용 sudo 규칙, ufw 규칙을 만든 다음 doctor --remote를 실행합니다. /etc/fbmcp/fbmcp.yaml에 databases:와 agents:를 추가하십시오. Linux에서의 승인 (트레이 없음): sudo -u firebird fbmcpctl approve [id]. 이것은 /etc/fbmcp/fbmcp.yaml을 스스로 찾고, y/N을 물으며(--yes는 묻지 않음), --deny <id> --reason "..."는 거부합니다.

관리자 PC:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(받은 키).
  2. 아무 stdio 클라이언트(Claude Desktop, Cursor, Codex, ZCode): §6 항목에 다음 args를 씁니다. ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. 핀은 서버 키를 검사하므로, 자체 서명 인증서에는 CA 설정이 필요 없습니다.
  3. Claude Code는 HTTP로 직접 연결할 수도 있습니다(.mcp.json의 "type": "http", 헤더 Authorization: Bearer ${FBMCP_KEY_SRV1}, 자체 서명 인증서용 NODE_EXTRA_CA_CERTS). 키를 claude mcp add --header로 넘기지 마십시오. 평문으로 저장됩니다.
  4. 테스트: fb_ping이 서버 이름과 자신의 신원을 보여 줍니다.

자율 에이전트(OpenClaw 등): 별도의 키를 apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32로 만듭니다. 기본값은 읽기 전용입니다. 모든 Tier 1 요청은 운영자를 기다리고, 에이전트의 fb_confirm은 거부됩니다. 제한: remote.md §6–7.

9. fbagent 브리지와 HQbird 클러스터(선택)

에이전트 도구(fb_agent_status, fb_agent_job_run, …)는 같은 호스트의 HQbird fbagent Local API를 씁니다. agents:에 항목이 생길 때까지 꺼져 있습니다.

  1. 클라이언트에서 “fb_agent_discover”. 로컬 에이전트를 base_url, instance_id, 제안된 토큰 이름과 함께 나열합니다. 토큰은 결코 읽지 않습니다.
  2. 운영자가 에이전트의 local_api.token을 저장합니다( agent.auth_token이 아님): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. 토큰을 채팅에 입력하지 마십시오.
  3. 클라이언트에서 “그 에이전트에 대한 fb_agent_register” → 트레이에서 승인합니다. fbmcp가 agents: 항목을 추가하고, 다시 읽어 신원을 확인합니다.
  4. 테스트: fb_agent_status, fb_agent_instances.

fb_agent_config_set(작업 설정 변경: 백업, sweep, …)에는 항목의 config_path, 실행 중인 agent_config.json에 대한 읽기, 그리고 그 폴더에 대한 생성 권한도 필요합니다. 그 파일에는 토큰과 Firebird 자격 증명이 있으므로, 이 권한을 줄지는 운영자의 판단입니다 (agent-bridge.md). 에이전트 확인이 실패하면 도구는 아무것도 쓰지 않습니다.

HQbird 클러스터(RCM).클러스터 도구는 같은 호스트의 HQbird 클러스터 관리자(hqbirdrcm)를 호출합니다. 보이는 것은 fbmcp.yaml에 rcm: 섹션(url, ca_file, user, password_env)이 있을 때뿐입니다. Linux HQbird 서버에서는 fbmcp ctl hqbird-install이 /opt/hqbirdrcm/rcm.json에서 그것을 쓰고, 첫 RCM 비밀번호를 시크릿 FBMCP_RCM_PASSWORD에 저장합니다. 그 밖에는 섹션을 직접 추가합니다 (tool-reference.md). 그다음:

  1. fb_cluster_rcm_password: 첫 RCM 비밀번호를 바꿉니다(Tier 1).
  2. 새 클러스터: 각 호스트에서 페어링 창을 열고 (fb_agent_cluster_pairing), 마스터에서 RCM을 시작하며 (fb_agent_cluster_rcm), 호스트를 연결하고(fb_cluster_link), 복제본을 만들며 (fb_cluster_reinit, Tier 2), 데이터를 비교합니다 (fb_cluster_verify). 절차: prompts/cluster-setup.md.
  3. 클러스터 서비스(스위치오버, 페일오버, 재합류): fb_cluster_service가 그것들과 검사를 보여 줍니다. 이동은 Tier 2입니다. 절차: prompts/cluster-services.md.

10. 일상적인 사용

클라이언트에게는 평범한 말로 부탁하십시오. 도구는 클라이언트가 고릅니다. 예:

작업 도구
모두 떠 있는가 fb_ping, fb_db_list, fb_db_health, fb_service_status
데이터 읽기 fb_query(읽기 전용. 행 + 플랜 + 테이블별 통계. MCP-Apps 클라이언트에서는 그리드). 초안은 fb_query_check로 확인
세션, 긴 트랜잭션 fb_sessions, fb_transactions, fb_session_kill(Tier 1)
느린 쿼리 fb_analyze_query, fb_index_advice → fb_write로 적용. fb_agent_perf_report
백업 fb_backup_start → 작업 ID → fb_job_status
백업 검증 fb_restore_test(work_dir에 복원하고, 그 백업을 검증됨으로 표시)
야간 백업 + 검증 target=nightly_verify가 있는 fb_schedule_create(확인은 한 번. 구성 B 또는 C)
스키마 / DDL fb_schema_list, fb_describe, fb_write(각 문은 분류되고 Tier가 매겨짐), fb_diff_schema
마이그레이션 fb_migration_status, fb_migration_plan, fb_migration_apply
서버 구성 fb_config_get, fb_config_diff, fb_config_set(Tier 2)
로그 fb_firebird_log
용량 fb_trends, fb_gstat, fb_index_stats
클러스터 상태 fb_cluster_status, fb_cluster_service
마스터 이동 fb_cluster_switchover(데이터 손실 없음) 또는 fb_cluster_failover(마스터를 잃었을 때), 그다음 fb_cluster_rejoin(Tier 2)

작업은 비동기입니다. 제출 → fb_job_status. 한 데이터베이스의 작업은 한 번에 하나만 실행됩니다. 작업이 fbmcp 재시작 뒤에 남는 것은 interrupted로만입니다. 아직 필요하면 다시 제출하십시오.

fb_config_set이 바꾸는 것은 firebird.conf의 자기 줄뿐입니다(주석, 들여쓰기, 줄 끝은 유지됩니다). 이전 파일은 firebird.conf.prev로 남기고, Firebird를 다시 시작하지 않습니다. 재시작은 fb_service_restart(Tier 2)로 합니다. 서비스가 멈췄다가 다시 실행될 때까지 기다립니다.

11. 운영자 작업

작업 명령
요청 나열 / 승인 / 거부 fbmcpctl approve, fbmcpctl approve <id>, fbmcpctl approve --deny <id> --reason "..."(또는 트레이)
키 교체 fbmcpctl apikey rotate alice --config <fbmcp.yaml>(이전 키는 몇 초 안에 멈춤)
키 나열 fbmcpctl apikey list(이름, 출처, Tier. 값은 나오지 않음)
사람 제거 identities: 항목을 지운 다음 fbmcpctl secret drop --dir <dir> NAME
인증서 갱신 fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ...(핀은 그대로, 재시작 없음)
감사 체인 확인 fbmcpctl verify
커널이 살아 있는가 fbmcpctl ping, fbmcpctl status(상태의 오프라인 읽기)
서비스 제어 허용 packaging/posture/verify.ps1 또는 verify.sh, 그다음 fbmcpctl setup --write-posture
업그레이드 서비스(또는 클라이언트)를 멈추고, 바이너리를 바꾸고, 시작한 다음 doctor
제거 Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. 소유자가 달리 말하지 않는 한 상태 디렉터리(감사)는 남김

개발 호스트에서만: .\packaging\rebuild-install.ps1 -Force는 dist\를 다시 빌드하고, 실행 중인 바이너리를 멈추고 바꾸며(이전 파일은 *.exe~로 남음), 클라이언트 구성을 병합하고 doctor를 실행합니다.

12. 충돌과 재시작 복구

카오스 하네스(internal/killharness)로 검증했습니다.

충돌 또는 강제 종료 이후 재시작 시 운영자 조치
작업이 실행 중이었거나 큐에 있었음 interrupted로 표시됨. 재개하지 않음 필요하면 다시 제출
대기 중인 요청, 미확인 state.json에서 복원됨(TTL은 그대로 적용) 확인하거나 만료되도록 둠
fb_restore_replace 진행 중 끝냄: 복원, 검증, 데이터베이스 온라인. <db>.pre-restore는 남음 fb_db_health 확인. .pre-restore는 나중에 삭제
fb_shutdown_window 진행 중 gfix -online 단계를 끝냄 온라인인지 확인
낡은 instance.lock 자동으로 인수됨 없음
state.json이 손상됨 커널이 시작을 거부함. 복사본은 state.json.corrupt-<ts>로 남음 살펴봄. 의도적으로 state.json을 고치거나 제거함(fbmcpctl repair가 감사에서 스케줄 허가를 다시 만듦)
audit.jsonl이 손상되었거나 잘림 커널이 시작을 거부함 §13.2: 변조 신호로 취급
시계가 뒤로 옮겨짐 스케줄러는 건너뜀. 두 번 실행하지 않음 없음
Windows 서비스 프로세스가 강제 종료됨 SCM이 약 5초 안에 다시 시작함 없음

커널은 온전함을 증명할 수 없는 것에 대해 페일 클로즈합니다. 재시작 루프는 발견 사항입니다. 로그를 읽으십시오.

13. 장애 대응 절차

13.1 데이터베이스에 문제가 있을 때

  1. fbmcpctl doctor --config <file>: 구성, 시크릿, Firebird 로그인, 폴더, 포스처, 스케줄. 각 FAIL 줄에는 Fix:가 있습니다.
  2. fb_db_list → fb_db_health <db>. 인스턴스에는 fb_service_status.
  3. attachment 또는 OAT 간격 문제에는 fb_sessions, fb_transactions. 엔진 오류에는 fb_firebird_log.

13.2 변조 또는 손상 의심: 감사부터

  1. fbmcpctl verify --config <file> → audit chain OK: N entries 또는 이유가 있는 BROKEN.
  2. 실패하면: 상태 디렉터리 전체를 보관합니다(그것이 증거입니다). 그다음 조사합니다. 커널을 시작시키려고 audit.jsonl을 지우지 마십시오.

13.3 복원 훈련(매 분기)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → 백업이 검증됩니다.
  3. 그 데이터베이스에 대해 fb_window_open.
  4. fb_restore_replace → 대역 밖에서 승인합니다. 온라인이 될 때까지 가동이 멈춥니다.
  5. 확인: fb_db_health, 그다음 실제 읽기(fb_schema_list, fb_info).
  6. 이전 파일은 삭제할 때까지 <db>.pre-restore로 남습니다.

13.4 클라이언트가 연결하지 못함

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. 클라이언트의 MCP 로그(stdio) 또는 <state_dir>\fbmcp.log / journalctl -u fbmcp(서비스)를 읽습니다.
  3. “another fbmcp instance is active”: 상태 디렉터리마다 커널은 하나입니다. 파이프로 연결된 클라이언트는 스스로 붙습니다. 두 번째 커널이 바로 실패하는 것은 설계입니다.

위 명령에서는 §4의 찾기가 그 파일을 찾으면 --config를 생략할 수 있습니다.

14. 문제 해결

증상 의미 / 조치
도구가 나타나지 않음 JSON 구문, 절대 경로, 클라이언트의 완전한 재시작. 클라이언트의 MCP 로그
목록에서 도구가 하나 빠짐 일부러 숨김(§1): 자신의 최대 Tier를 넘음, agents: 항목 없음, migrations_dir 없음, 또는 rcm: 섹션 없음
서버가 곧바로 종료됨 fbmcpctl doctor. 없는 시크릿. 서비스는 당신의 키링을 읽을 수 없음(secrets.dir 사용)
Tier 2 “confirmation rejected: channel policy” 채팅에서는 예상된 동작입니다. 트레이 또는 fbmcpctl approve로 승인
Tier 2 “no open maintenance window” 도구에 넘기는 것과 같은 db에 대한 fb_window_open
fb_restore_replace 거부: 사전 조건 24시간 미만의 검증된 백업이 필요함: fb_backup_start + fb_restore_test, 그리고 창
서비스 제어 거부 posture.verified 없음(fbmcpctl setup --write-posture) 또는 그 계정에 Firebird 서비스 권한이 없음
fb_config_set: 쓸 수 없음 그 계정은 그 파일을 바꾸지 못할 수 있음(Linux 유닛 ProtectSystem=strict, Windows ACL). 직접 편집하거나 remote.md §8을 봄
트레이에 아무것도 안 나옴 운영자가 필요한 요청만 보여 줍니다. 상태 디렉터리에 대한 트레이 사용자의 권한과 그곳의 tray.log를 확인
401(원격) 키가 틀렸거나, 서버가 그 키를 불러오지 않음: apikey list, doctor --remote
403(원격) 출발지 IP가 allow_from / 방화벽에 없음, 또는 Origin 헤더가 allowed_origins에 없음
429(원격) 제한. Retry-After를 기다림
핀 불일치 서버 키가 바뀜. 새 핀은 서버 관리자에게 받음
agent-unreachable 에이전트 서비스가 내려가 있음, local_api.enabled: false, 또는 base_url이 틀림(기본값 127.0.0.1:(10000 + firebird port))
agent-auth 저장한 토큰이 에이전트의 local_api.token이 아님. 다시 설정
재시작 시 agent-timeout agents[].timeout_seconds(130)는 에이전트의 restart_timeout_seconds(120)보다 커야 함
어태치 시 Error loading plugin MySQLEngine … HQbird에서는 보통 데이터베이스 파일이 없다는 뜻입니다. 경로를 확인
fb_write 안의 단독 DROP INDEX에는 창이 필요 거기서는 Tier 2입니다. fb_index_drop을 씀(Tier 1. 제약 인덱스는 거부)
새 인덱스가 쓰이지 않음 통계를 실행(fb_index_rebuild action=statistics). ORDER BY … DESC에는 DESCENDING 인덱스가 필요
한 데이터베이스에서만 도구가 실패 오프라인임(fb_db_health). 도구는 데이터베이스마다 저하됨

15. 상태 디렉터리 참조

경로 의미
state.json(+ .tmp, .corrupt-*) 대기 중인 요청, 작업, 백업 카탈로그, 워크플로, 스케줄. 손상 ⇒ 시작을 거부함
audit.jsonl(+ .head) 해시 체인 감사 로그. .head는 잘림을 감지함
events.jsonl 작업 이벤트(메시지가 있는 job.succeeded, job.failed)
approvals\, denials\ 대역 외 결정(트레이 / fbmcpctl approve). 약 2초 안에 쓰임
instance.lock 커널을 하나로 유지하는 잠금
attach.addr, attach.token 추가 stdio 클라이언트용 어태치 끝점
fbmcp.log, fbmcp-crash.log 서비스 로그(순환)와 충돌 출력
query-log.jsonl 모든 fb_query 호출
trends\ fb_trends용 샘플러 이력
config-journal\ fb_config_set 이력(이전 값과 새 값)
posture.verified 서비스 제어를 허용하는 표시
tray.log 트레이 오류

16. 워크스루 상태

미완(M1): 이 가이드만으로 깨끗한 Windows 호스트에서 하는 워크스루. 발견 사항은 이 파일로 되돌립니다. 원격 모드의 랩 결과(Linux 호스트, 깨끗한 VM, Windows 서비스): findings/phase12-lab-2026-11-03.md.