fbmcp: 설치와 사용
대상은 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 이상 (선택).
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-trayLinux 바이너리(Windows에서 크로스 빌드하거나, GOOS 없이 Linux에서 빌드):
$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 구성:
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 키링.
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:
.\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 서버(관리자 권한):
- 바이너리와
fbmcp.yaml을C:\fbmcp\에 둡니다(템플릿: remote.md §3:listen,tls,identities,allowed_origins,secrets.dir). C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp"— 핀sha256:...를 적어 둡니다.- 사람 또는 에이전트마다 키 하나:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(한 번만 출력됨).--config C:\fbmcp\fbmcp.yaml을 주면identities:항목도 추가하고secrets.dir을 씁니다. - 비밀번호와 에이전트 토큰:
fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME. .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf, 그다음-WhatIf없이. 서비스, 방화벽 규칙, 폴더 ACL, Firebird 서비스 권한을 만듭니다.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.- 승인자용 트레이:
.\packaging\windows\install-tray.ps1.
Linux 서버(root): fbmcp, fbmcpctl, packaging/linux/를 복사한 다음
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:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(받은 키).- 아무 stdio 클라이언트(Claude Desktop, Cursor, Codex, ZCode): §6 항목에
다음
args를 씁니다.["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. 핀은 서버 키를 검사하므로, 자체 서명 인증서에는 CA 설정이 필요 없습니다. - Claude Code는 HTTP로 직접 연결할 수도 있습니다(
.mcp.json의"type": "http", 헤더Authorization: Bearer ${FBMCP_KEY_SRV1}, 자체 서명 인증서용NODE_EXTRA_CA_CERTS). 키를claude mcp add --header로 넘기지 마십시오. 평문으로 저장됩니다. - 테스트:
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:에 항목이 생길 때까지 꺼져 있습니다.
- 클라이언트에서 “
fb_agent_discover”. 로컬 에이전트를base_url,instance_id, 제안된 토큰 이름과 함께 나열합니다. 토큰은 결코 읽지 않습니다. - 운영자가 에이전트의
local_api.token을 저장합니다(agent.auth_token이 아님):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. 토큰을 채팅에 입력하지 마십시오. - 클라이언트에서 “그 에이전트에 대한
fb_agent_register” → 트레이에서 승인합니다. fbmcp가agents:항목을 추가하고, 다시 읽어 신원을 확인합니다. - 테스트:
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). 그다음:
fb_cluster_rcm_password: 첫 RCM 비밀번호를 바꿉니다(Tier 1).- 새 클러스터: 각 호스트에서 페어링 창을 열고
(
fb_agent_cluster_pairing), 마스터에서 RCM을 시작하며 (fb_agent_cluster_rcm), 호스트를 연결하고(fb_cluster_link), 복제본을 만들며 (fb_cluster_reinit, Tier 2), 데이터를 비교합니다 (fb_cluster_verify). 절차:prompts/cluster-setup.md. - 클러스터 서비스(스위치오버, 페일오버, 재합류):
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 데이터베이스에 문제가 있을 때
fbmcpctl doctor --config <file>: 구성, 시크릿, Firebird 로그인, 폴더, 포스처, 스케줄. 각 FAIL 줄에는Fix:가 있습니다.fb_db_list→fb_db_health <db>. 인스턴스에는fb_service_status.- attachment 또는 OAT 간격 문제에는
fb_sessions,fb_transactions. 엔진 오류에는fb_firebird_log.
13.2 변조 또는 손상 의심: 감사부터
fbmcpctl verify --config <file>→audit chain OK: N entries또는 이유가 있는BROKEN.- 실패하면: 상태 디렉터리 전체를 보관합니다(그것이 증거입니다). 그다음
조사합니다. 커널을 시작시키려고
audit.jsonl을 지우지 마십시오.
13.3 복원 훈련(매 분기)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ 백업이 검증됩니다.- 그 데이터베이스에 대해
fb_window_open. fb_restore_replace→ 대역 밖에서 승인합니다. 온라인이 될 때까지 가동이 멈춥니다.- 확인:
fb_db_health, 그다음 실제 읽기(fb_schema_list,fb_info). - 이전 파일은 삭제할 때까지
<db>.pre-restore로 남습니다.
13.4 클라이언트가 연결하지 못함
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- 클라이언트의 MCP 로그(stdio) 또는
<state_dir>\fbmcp.log/journalctl -u fbmcp(서비스)를 읽습니다. - “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.