belle-mcp-server

Belle Realty의 실제 부동산 관리 데이터(부동산, 임차인, 임대차 계약, 유지보수 티켓, 임대료 명세)를 도구로 노출하는 참조 Model Context Protocol (MCP) 서버로, Claude Desktop, Cursor 또는 MCP 호환 클라이언트가 직접 호출할 수 있습니다.

여섯 개의 도구가 있습니다. 다섯 개는 엄격히 읽기 전용이고, 하나는 HITL 게이트가 적용된 쓰기 제안입니다. 그 비율은 의도적이며, 이 레포의 핵심입니다.

AI Fluency Program — Level 2의 일부입니다.

존재 이유

대부분의 "AI + 당신의 데이터" 데모는 모델에게 무제한 데이터베이스 접근 권한을 줍니다. 그건 위험천만한 일입니다.

Model Context Protocol은 도구별 인증, 속도 제한, 감사를 갖춘 작고 선별된 표면을 노출하도록 설계되었습니다. 이는 공개 REST API에 적용하는 것과 같은 규율입니다. 이 레포는 실제 도메인(루이지애나의 쇼핑 센터)과 실제 Postgres 스키마, 동작하는 시드, 그리고 하나의 HITL 게이트 쓰기 경로를 사용하여 그것이 어떤 모습인지 보여줍니다.

이 레포를 이해하면, 당신이 운영하는 어떤 비즈니스에 대해서도 같은 것을 만들 수 있습니다.

제공 기능

모든 호출은 속도 제한(기본 60/min)이 적용되고 mcp_audit_log에 감사 로그가 기록됩니다.

빠른 시작

# 1. Clone + install
git clone https://github.com/OrangeOnyx/belle-mcp-server.git
cd belle-mcp-server
npm install

# 2. Configure
cp .env.example .env
# Paste your Supabase URL + service-role key

# 3. Set up the schema (Supabase project)
#    Copy supabase/migrations/0001_init.sql into the SQL editor and run.

# 4. Seed demo data
npm run db:seed

# 5. Build + inspect
npm run build
npm run inspect

MCP Inspector는 도구 목록을 보고, 호출하고, 원시 응답을 확인할 수 있는 UI를 엽니다.

Claude Desktop에 연결하기

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 Windows/Linux의 해당 경로에 추가하세요:

{
  "mcpServers": {
    "belle-realty": {
      "command": "node",
      "args": ["/absolute/path/to/belle-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Claude Desktop을 다시 시작하세요. 이제 belle-realty 도구 세트가 보일 것입니다. 다음과 같이 시도해 보세요:

"On The Boulevard에서 현재 어떤 스위트가 점유 중이고, 월 임대료는 얼마인가요?"

Claude는 get_rent_roll을 호출하고 반환된 데이터로 답변할 것입니다.

HITL 쓰기 패턴

유일한 쓰기 도구(draft_maintenance_response)는 AI를 대면하는 모든 서비스에 복사해야 하는 일반적인 패턴을 보여줍니다:

1. AI가 변경을 제안합니다 — 여기서는 임차인 유지보수 티켓에 대한 답변입니다.

2. 서버는 그것을 approved=false로 저장합니다.

3. 사람이 대역 외에서 승인하기 전에는 어떤 것도 전달, 전송 또는 적용되지 않습니다(일반적으로 부동산 관리자의 관리자 UI에서).

4. MCP 표면은 의도적으로 승인 도구를 노출하지 않습니다. 승인은 사람 전용 작업입니다.

즉, 지나치게 열성적이거나 프롬프트 주입된 에이전트는 임차인에게 조용히 텍스트를 보낼 수 없습니다. 제안할 수는 있고, 크게 제안할 수는 있습니다. 그러나 배포할 수는 없습니다.

더 긴 설명은 docs/hitl-pattern.md를 참조하세요.

개인 사용 워크스루

당신은 주택 3채 또는 작은 상업용 건물 하나를 가진 개인 임대인입니다.

1. Supabase 프로젝트에서 마이그레이션을 실행하세요.

2. 자신의 데이터로 시드하세요 (supabase/seed.ts를 편집하거나 행을 수동으로 삽입).

3. Claude Desktop을 서버에 연결하세요.

4. "90일 안에 만료되는 임대차 계약이 있는 임차인은 누구?" 또는 "온수기 티켓에 대한 답변을 작성해 줘" 같은 질문을 하세요.

이제 당신의 데이터를 말하는 AI 네이티브 임차인 운영 레이어를 구축한 것입니다. 저녁 하나만 투자하면 됩니다.

회사 사용 워크스루

당신은 Belle Realty(또는 이에 상응하는 관리 회사)를 운영합니다. 여러 직원이 원시 SQL을 보지 않고, 의도치 않은 쓰기 위험 없이 포트폴리오 데이터에 대해 Claude 접근 권한을 가져야 합니다.

1. 이 서버를 지속적인 프로세스로 배포하세요 (Railway, Fly 또는 Docker 호스트).

2. MCP_TRANSPORT=http와 MCP_HTTP_TOKEN=<shared-secret>을 설정하세요.

3. 각 팀원은 URL + 토큰으로 Claude Desktop 또는 Cursor를 구성합니다.

4. 읽기 전용 도구는 모든 사람에게 활용도를 줍니다. 유일한 쓰기 도구는 임차인 관계를 보호합니다.

5. mcp_audit_log는 모든 AI 작업에 대한 사후 기록을 제공합니다.

아키텍처

graph LR
    A[Claude Desktop / Cursor] -->|MCP stdio or HTTP| B[belle-mcp-server]
    B --> C[RateLimiter]
    B --> D[Zod validation]
    B --> E[Supabase Postgres]
    B --> F[mcp_audit_log]
    E --> G[(properties, tenants, leases, tickets)]

자세한 내용은 docs/architecture.md에 있습니다.

확장하기

4단계로 새 도구를 추가하세요:

1. 데이터 형태가 새로운 경우 src/schemas/domain.ts에 Zod 스키마를 추가하세요.

2. input 스키마, 핸들러, JSON-Schema 정의를 포함한 src/tools/<name>.ts를 만드세요.

3. src/tools/index.ts에 등록하세요.

4. tests/에 테스트를 추가하세요.

모든 쓰기 도구는 draft_maintenance_response의 제안-쓰기 패턴을 따라야 합니다.

배포

Railway (HTTP 전송에 권장)

railway up

railway.json은 서버를 빌드하고 node dist/index.js를 실행합니다. Railway 대시보드에서 환경 변수를 설정하세요.

로컬 (stdio 전용)

빌드한 후 MCP 클라이언트를 dist/index.js에 연결하기만 하면 됩니다. 호스팅이 필요 없습니다.

개발

npm run dev       # tsx watch mode
npm run test      # vitest
npm run build     # tsc → dist/
npm run inspect   # MCP Inspector UI

관련 레포

• lease-abstractor — 임대차 계약 PDF/DOCX에서 구조화된 추상화 추출

• support-triage-agent — 지원 메시지에 적용된 동일한 HITL 패턴

• diligence-agent — 문서 폴더에 대한 RAG 기반 실사

• ai-fluency-program — 상위 커리큘럼

라이선스

MIT — LICENSE 참조.

법률, 세무 또는 부동산 관리 조언이 아닙니다. 자격을 갖춘 전문가의 개입 없이 규정 준수에 중요한 결정에 사용하지 마세요.