HQbird MCP AI 어시스턴트
인간의 통제 아래 있는 AI 어시스턴트
HQbird MCP는 Firebird를 AI 어시스턴트에 연결합니다. 평범한 말로 작성하면 어시스턴트가 스스로 도구를 선택합니다. 읽기는 자유롭게 수행됩니다. 모든 변경은 여러분의 "예"를 기다리며, 위험한 변경은 서버 자체에서 승인을 기다립니다.
- 122개 도구
- 56개 읽기 전용
- Firebird 2.5–5 Windows 및 Linux
- 승인을 위한 2개 채널
- 해시 체인이 적용된 감사 로그
예시
어시스턴트와의 대화
사용자들이 데이터베이스가 느리다고 불평합니다. 어시스턴트가 데이터를 읽고 원인을 찾아 조치를 제안한 뒤 여러분의 결정을 기다립니다. 예시의 이름과 숫자는 임의로 만든 것입니다.
Claude Desktop, Claude Code, Cursor, Codex, ZCode 등 모든 MCP 클라이언트가 작동합니다.
정책 · 승인
네 가지 위험 레벨
각 도구에는 레벨이 있습니다. MCP 서버는 호출이 실행되기 전에 레벨과 조건을 직접 확인합니다. 무언가를 변경하는 호출은 결과 대신 승인 요청을 반환합니다. 어시스턴트는 이 검사를 우회할 수 없습니다.
도구를 선택하면 해당 호출이 어떤 경로를 거치는지 확인할 수 있습니다.
| 레벨 | 도구 | 예시 | 승인 방법 |
|---|---|---|---|
| 0 · 읽기 | 51 | 세션, 트랜잭션, 쿼리 계획, gstat, firebird.log, 에이전트 보고서 | 필요 없음. 읽기 전용 트랜잭션. |
| 1 · 변경 | 31 | DML 및 DDL, 백업, 테스트 복원, sweep, 사용자 및 권한 부여, 세션 종료 | 채팅에서: 요청 번호와 토큰, 그다음 fb_confirm. |
| 2 · 위험한 작업 | 14 | 백업으로 데이터베이스 교체, firebird.conf 편집, Firebird 중지 및 재시작 | 서버에서만: fbmcp ctl approve 명령. Windows에서는 트레이 창을 설치할 수도 있습니다. |
| 3 · 비활성화 | 1 | 데이터베이스 삭제 | 절대 실행되지 않음. |
- 미리보기승인이 필요한 각 도구는
mode: preview를 받습니다. 수행될 작업을 보여주고 아무것도 하지 않습니다. - 레벨 2의 조건각 레벨 2 작업에는 해당 데이터베이스에 열린 유지보수 윈도우가 필요합니다. 백업으로 데이터베이스를 교체하는 경우, 배타적 윈도우와 위험한 SQL에도 24시간 이내에 검증된 백업이 필요합니다. 거부 시 무엇이 부족한지 알려줍니다.
- 허용된 도구만클라이언트는 사용이 허용된 도구만 목록에서 볼 수 있습니다. 레벨 3과 해당 키의 최대 레벨을 초과하는 레벨은 표시되지 않습니다. 숨겨진 도구를 직접 호출하면 거부됩니다.
- 요청 유효 시간 15분잘못된 채널을 통해 승인을 시도해도 요청이 소모되지 않습니다.
fb_cancel은 요청을 삭제합니다. - 승인 페이지 없음앞으로도 없을 것입니다. 모델이 접근할 수 있는 페이지는 보호를 무력화할 것이기 때문입니다. 서버에 있는 사람만 승인합니다.
fbmcp ctl approve명령 또는 설치된 경우 트레이 창에서 승인합니다.
읽기는 읽기 전용 트랜잭션에서 실행됩니다. Firebird 자체가 쓰기를 차단합니다. 추가 보호 계층을 위해 쓰기 권한이 없는 별도의 읽기 전용 사용자를 설정하십시오.
모니터링 · 백업 · 권한 부여
DBA용
어시스턴트는 DBA가 직접 하는 작업을 수행합니다. 세션과 트랜잭션을 확인하고, 로그를 읽고, 백업을 만들고 복원으로 검증하며, 사용자를 관리합니다. 데이터베이스는 파일 경로가 아닌 id로 지정합니다.
| 작업 | 도구 | 레벨 |
|---|---|---|
| 모든 것이 정상 작동하는지 | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| 세션 및 장기 트랜잭션 | fb_sessions, fb_transactions; 세션 종료 — fb_session_kill | 0 · 1 |
| 로그 및 통계 | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| 백업 및 검증 | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| 오래된 백업 | fb_retention_run: 먼저 드라이 런; 자체 카탈로그의 검증된 백업만 삭제 | 1 |
| Sweep 및 데이터베이스 검증 | fb_sweep, fb_validate (발견 사항만, 복구 없음) | 1 |
| 사용자 및 권한 부여 | fb_user_create, fb_grant, fb_revoke; SYSDBA 및 자체 계정은 삭제할 수 없음 | 1 |
| 트레이스 | fb_trace_start는 템플릿만 사용: audit-lite, performance, errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff; 편집 — fb_config_set, Firebird는 재시작되지 않음 | 0 · 2 |
| 서비스 및 데이터베이스 교체 | fb_service_restart; fb_restore_replace, 이전 파일은 .pre-restore로 유지됨 | 2 |
야간 백업 검사
일정은 생성 시 한 번만 승인됩니다. 그 이후에는 사람 없이 실행됩니다. 매일 밤 검증된 백업을 받게 됩니다. 예를 들어 백업으로 데이터베이스를 교체하려면 하나가 필요합니다.
- 1일정
fb_schedule_create, 목표nightly_verify; 한 번 승인 - 2백업백업 폴더로 gbak
- 3복원 테스트작업 폴더로; 원본 데이터베이스는 건드리지 않음
- 4✓ 백업 검증됨백업 카탈로그에 표시
백업으로부터의 데이터베이스 교체와 레벨 3 작업은 예약할 수 없습니다.
미리 준비된 시나리오
시나리오는 어시스턴트에게 단계 순서를 제안합니다. 스스로 변경을 적용하지는 않습니다.
쿼리 · 인덱스 · 마이그레이션
개발자를 위해
Cursor 또는 Claude Code의 어시스턴트는 스키마를 알고, 쿼리를 실행 전에 검사하며, 결과를 채팅창에 바로 표로 보여줍니다.
- 1작업필요한 것을 한 문장으로
- 2사실
fb_schema_list,fb_describe: 존재하는 테이블과 컬럼만 - 3초안ORDER BY가 있는 SELECT 하나
- 4검사
fb_query_check: 실행 없이 컴파일 - 5✓ 채팅창의 표
fb_query: 행, 계획 및 통계
결과를 표로
MCP Apps를 지원하는 클라이언트에서는 fb_query 결과가 정렬 가능한 표로 표시됩니다. 다른 클라이언트는 동일한 데이터를 텍스트로 받습니다.
기본 100행, 최대 1000행. 표는 30분 동안 메모리에 유지되며, 요청한 사람만 볼 수 있습니다. 열 머리글을 클릭하면 정렬됩니다.
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
인덱스 조언
전체 테이블 스캔을 찾아내고 이점 추정치와 함께 CREATE INDEX를 제안합니다. 인덱스 자체를 생성하지는 않습니다: 승인과 함께 fb_write가 생성합니다. 인덱스가 생성된 후에는 계획을 다시 확인합니다.
데이터베이스 비교
두 데이터베이스의 스키마, 또는 데이터베이스와 그 스냅샷의 스키마: 생성, 변경, 삭제할 항목. 데이터는 기본 키로 비교되며, 큰 테이블(기본적으로 100,000행 초과)은 비교하지 않습니다.
마이그레이션
계획은 각 문의 레벨을 보여줍니다. 모든 마이그레이션은 한 번의 승인 후 적용되며, 파일이 변경되면 새 요청이 필요합니다. 롤백 계획은 마이그레이션 적용 시 기록된 내용을 바탕으로 작성됩니다.
fb_write는 스크립트에서 각 문의 레벨을 찾습니다. 서로 다른 레벨의 문이 섞인 스크립트는 거부됩니다.
fbagent · 로컬 API · 127.0.0.1
fbagent 데이터
fbagent 에이전트는 이미 HQbird 서버에서 실행 중입니다. MCP를 통해 어시스턴트는 에이전트가 수집한 모든 것을 얻습니다: 상태 보고서, LWM(Light-weight Monitoring), gstat, 트레이스, 교착 상태, 백업 상태. 또한 동일한 레벨과 승인 아래에서 에이전트 작업을 실행하고 설정을 변경합니다.
| 항목 | 도구 | 레벨 |
|---|---|---|
| 서버 상태 보고서 | fb_agent_status | 0 |
| LWM, gstat, 데이터베이스 지표, 트레이스, 교착 상태 | fb_agent_artifact_get, fb_agent_perf_report | 0 |
| 백업, 스윕 및 복원 설정 | fb_agent_backup_config; 비밀번호와 토큰은 숨겨짐 | 0 |
| 에이전트 작업 실행 | fb_agent_job_run; 백업, 복원 및 SQL 스크립트는 레벨 2 | 1 · 2 |
| 작업 설정 변경 | fb_agent_config_set; 자격 증명, ID 및 명령은 변경할 수 없음 | 2 |
| 에이전트를 통한 Firebird 재시작 | fb_agent_restart, fb_agent_stop, fb_agent_start | 2 |
| 라이선스 및 업데이트 | fb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply | 0 · 1 · 2 |
- 로컬 전용에이전트는 127.0.0.1에서만 요청을 받습니다. 에이전트 주소는 채팅이 아닌 MCP 서버 구성에서 가져옵니다.
- 토큰은 숨겨짐에이전트 토큰은 도구 출력이나 감사 로그에 나타나지 않습니다.
- 에이전트 검색
fb_agent_discover는 Windows 서비스 또는 systemd 유닛으로 서버의 에이전트를 찾습니다. 토큰은 읽지 않습니다. - 클러스터서버에 클러스터 노드가 설치되어 있으면
fb_agent_restart,fb_agent_stop및fb_agent_start는 기본적으로 거부합니다: 노드가 재시작을 제어합니다.fb_service_restart는 이를 확인하지 않으므로 클러스터 노드에서는 사용하지 마십시오.
이중 제어. MCP 서버가 요청을 승인하고, 에이전트 자체는 자체 규칙에 따라 작업을 실행합니다. MCP 로그는 누가 요청했는지 보여주고, 에이전트 로그는 어떻게 수행되었는지 보여줍니다.
HQbird Cluster · RCM
어시스턴트를 통한 복제 클러스터
어시스턴트가 복제 클러스터를 단계별로 구축합니다. RCM을 켜고, 페어링 윈도우를 열고, 호스트를 연결하고, 데이터베이스를 관리 대상으로 등록하고, 복제본용 사본을 만듭니다. 에이전트와 RCM을 통해 작동합니다. 서버에 SSH로 로그인할 필요가 없습니다.
규칙은 어디서나 동일합니다. 읽기에는 확인이 필요하지 않습니다. 변경은 채팅에서 확인됩니다. Firebird 재시작, 복제본으로의 데이터베이스 복사, 클러스터에서 서버 제거, 스위치오버, 페일오버, 이전 마스터의 복귀는 서버에서 확인됩니다.
| 항목 | 도구 | 레벨 |
|---|---|---|
| 서버의 클러스터 상태 | fb_agent_cluster: 여유, 클러스터 내 또는 RCM 소유자; 슬롯 및 포트 | 0 |
| RCM의 클러스터 개요 | fb_cluster_status: 노드, 데이터베이스, 명령, 경고 | 0 |
| 연결 전 호스트 확인 | fb_cluster_probe: 에이전트당 한 행, 인증서 지문 | 0 |
| 마스터와 복제본 비교 | fb_cluster_verify: 각 테이블의 행 수 | 0 |
| 서버에서 RCM 켜기 | fb_agent_cluster_rcm | 1 |
| 페어링 윈도우 | fb_agent_cluster_pairing: 상태, 1–24시간 동안 열기, 닫기 | 0 · 1 |
| 호스트 연결 | fb_cluster_link; 요청에 비교할 지문이 표시됨 | 1 |
| 데이터베이스 및 게시 | fb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication | 1 |
| RCM 비밀번호 | fb_cluster_rcm_password: 새 임의 비밀번호, 채팅에 표시되지 않음 | 1 |
| 복제본으로의 데이터베이스 복사 | fb_cluster_reinit | 2 |
| 노드의 Firebird 재시작 | fb_cluster_firebird_restart | 2 |
| 클러스터에서 서버 제거 | fb_cluster_unlink | 2 |
| 서비스: 마스터 위치 | fb_cluster_service: 마스터, 복제본, 라우터, 문제, 실행 중인 작업 | 0 |
| 서비스 및 규칙 설명 | fb_cluster_service_put, fb_cluster_service_policy: 서비스 설명, 자동 페일오버 규칙 | 1 |
| 작업 재개 및 취소 | fb_cluster_resume, fb_cluster_operation_cancel; 되돌릴 수 없는 지점 이전에만 취소 가능 | 1 |
| 스위치오버 | fb_cluster_switchover: 계획된 마스터 이동, 작업 종료까지 대기 | 2 |
| 페일오버 | fb_cluster_failover: 데이터 손실에 대한 명시적 동의가 있는 경우에만 | 2 |
| 이전 마스터 복귀 | fb_cluster_rejoin | 2 |
| 서비스 삭제 | fb_cluster_service_delete: RCM의 레코드만 삭제됨 | 2 |
- 기성 시나리오"클러스터 구축": 어시스턴트가 단계별로 진행하며 각 단계에서 무엇을 할지 보여줍니다.
- 지문연결 전에 어시스턴트가 각 서버의 인증서 지문을 보여줍니다. 설치 요약의 줄과 비교하세요.
- 드라이 런데이터베이스가 있는 폴더를 관리 대상으로 등록하기 전에, 어시스턴트가 RCM이 찾을 데이터베이스를 보여줍니다.
- 스위치오버 및 페일오버어시스턴트가 마스터 이동을 시작하고 작업 단계를 따릅니다. 서버에 있는 사람이 시작을 확인합니다. 페일오버는 데이터 손실에 대한 명시적 동의도 필요합니다. 클러스터 페이지에서 더 보기.
HTTPS · API 키 · 감사
원격 모드, 설치 및 감사 로그
어시스턴트는 관리자의 PC에서 실행되고, MCP 서버는 데이터베이스 서버에서 실행됩니다. 둘 사이에는 HTTPS와 API 키가 있습니다. 각 사용자는 자신의 키와 자신의 최대 레벨을 가집니다.
- 사용자별 키
fbmcp ctl apikey new <name> --max-tier 2. 값은 한 번만 표시됩니다. 키를 변경하면 이전 키는 몇 초 이내에 작동을 멈춥니다. - 제한키별: 동시 호출, 분당 호출, 열린 세션. 제한을 초과하면 응답은 429입니다.
- 포르투갈어 가이드설치 및 사용에 관한 전체 가이드는 브라질 포르투갈어로도 제공됩니다.
- 자율 에이전트
autonomous프로필: 기본적으로 읽기 전용. 변경은 서버의 운영자를 기다립니다. 에이전트의fb_confirm은 거부됩니다. 분당 10회 호출. 이러한 에이전트는 회사 네트워크 내에서 실행하세요. - 주소키를 주소에 바인딩할 수 있습니다(
allow_from). 다른 주소는 403과 로그 기록을 받습니다.
HQbird에 설치
HQbird 설치 프로그램은 기본적으로 MCP 서버를 설치합니다. 하나의 서버가 머신의 모든 Firebird 라인을 서비스합니다. 하나의 명령으로 모든 것을 설정하며, 다시 실행할 수 있습니다.
- 1HQbird 설치 프로그램Windows 또는 Linux
- 2fbmcp ctl hqbird-install하나의 명령, 수동 YAML 편집 불필요
- 3Firebird 라인각 라인과 해당 에이전트를 찾음
- 4데이터베이스databases.conf 별칭 및 최근 연결된 데이터베이스
- 5✓ 서비스시작, 확인, 클라이언트용 connect.txt 파일
원격 모드는 세 가지 조건이 충족되면 켜집니다: 관리자 주소 목록이 설정되어 있고(--allow-from), 방화벽이 실행 중이며, API 키가 하나 이상 존재할 때입니다. 키는 별도로 생성합니다. 그런 다음 fbmcp ctl hqbird-install을 다시 실행하십시오. 기본 포트는 8650입니다.
해시 체인
각 결정(허용, 대기, 승인, 거부)이 로그에 기록됩니다. 각 항목은 이전 항목과 연결됩니다. 체인 검사를 통해 항목이 변경되거나 삭제되었는지 확인할 수 있습니다.
로그가 잘림 — 서버는 계속 중지 상태
로그가 잘렸거나 끝부분이 제어 항목과 일치하지 않으면 MCP 서버가 시작되지 않습니다. 이는 변조의 징후이므로 반드시 조사해야 합니다. fbmcp ctl verify 명령은 전체 체인을 검사합니다.
에이전트를 통한 업데이트
fbagent가 MCP 서버를 업데이트합니다: 중지, 교체, 시작, 확인, 실패 시 롤백. Linux에서는 서명되지 않은 빌드는 설치되지 않습니다. 구성과 키는 변경되지 않습니다.