belle-mcp-server

実際のBelle Realtyのプロパティ管理データ（物件、テナント、リース、メンテナンスチケット、家賃台帳）を、Claude Desktop、Cursor、その他MCP互換クライアントが直接呼び出せるツールとして公開する、リファレンス実装のModel Context Protocol (MCP) サーバーです。

6つのツールがあります。5つは厳密に読み取り専用です。1つはHITLゲート付きの書き込み提案です。その比率は意図的であり、このリポジトリの存在意義そのものです。

AI Fluency Program — Level 2 の一部です。

なぜこれがあるのか

「AI＋あなたのデータ」系デモのほとんどは、モデルに無制限のデータベースアクセス権を与えています。それは自爆装置です。

Model Context Protocolは、ツールごとの認証、レート制限、監査を備えた、厳選された小さなサーフェス領域を公開するように設計されています。これは、公開REST APIに適用するのと同じ規律です。このリポジトリは、実際のドメイン（ルイジアナ州のショッピングセンター）に対して、実際のPostgresスキーマ、動作するシード、そして単一のHITLゲート付き書き込みパスを使って、それがどのようなものかを示しています。

このリポジトリを理解すれば、あなたが運営するあらゆるビジネス向けに同様のものを作成できます。

含まれるもの

すべての呼び出しはレート制限（デフォルト60回/分）され、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軒所有する個人オーナーだとします。

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=<共有シークレット> を設定します。

3. 各チームメイトがClaude DesktopまたはCursorにURLとトークンを設定します。

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. src/tools/<name>.ts に input スキーマ、ハンドラー、JSON-Schema定義を記述して作成します。

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 を参照してください。

法的、税務、またはプロパティ管理に関するアドバイスを提供するものではありません。コンプライアンス上重要な決定に、有資格者の関与なしに使用しないでください。