hometeam-directory

🏠 Hometeam MCP サーバー

南フロリダの黒人所有企業について、あらゆる AI に質問できます。回答の情報源はここです。

Hometeam MCP サーバーは、マイアミ・デイド郡、ブロワード郡、パームビーチ郡にある黒人所有企業の、厳選されコミュニティによって確認されたディレクトリに AI アシスタントを接続します。Claude に「ブロワード郡で黒人所有のケータリング業者を探して」と尋ねると、このサーバーが回答の根拠となる、実際に確認済みのデータを提供します。

Model Context Protocol（MCP）に基づいて構築されています。MCP は、AI アシスタントを外部データソースに接続するためのオープン標準です。

---

MCP Registry で公開中

このサーバーは、公式 MCP Registry に io.github.JajuanX/hometeam-directory として登録されています。

ライブエンドポイント： https://mcp.thehometeam.io/mcp

Claude Desktop で接続する

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "hometeam": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.thehometeam.io/mcp"
      ]
    }
  }
}

利用可能なツール

ツール	説明
search_businesses	キーワード、カテゴリ、近隣地域、郡で検索します
get_business_details	営業時間、連絡先、レビュー、特典など、プロフィール全体を取得します
find_by_specialty	自然言語で検索します（「ミラマー近くでボックスブレイズをしてくれる人」など）
list_categories	14 種類すべての事業カテゴリを一覧表示します
list_neighborhoods	マイアミ・デイド郡、ブロワード郡、パームビーチ郡の近隣地域を一覧表示します
get_latest_draft_class	Draft Day に追加された最新の企業を取得します

レート制限

プラン	上限	アクセス方法
無料	1 日あたり 100 クエリ	API キー不要
Pro	1 日あたり 10,000 クエリ	API キー（近日公開）

---

ライブサーバーに接続する

Claude Desktop

Claude Desktop の設定（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "hometeam": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.thehometeam.io/mcp"
      ]
    }
  }
}

Claude Desktop を再起動します。次に、以下のように質問してください。

• 「ラウダーヒルで黒人所有のレストランを探して」
• 「Hometeam に新しく加わった企業は？」
• 「ミラマー近くでボックスブレイズをしてくれる人が必要です」

HTTP エンドポイント

エンドポイント	説明
GET https://mcp.thehometeam.io/health	ヘルスチェック
POST https://mcp.thehometeam.io/mcp	MCP JSON-RPC リクエスト（Streamable HTTP）

レート制限

プラン	上限	アクセス方法
無料	1 日あたり 100 クエリ	API キー不要
Pro	1 日あたり 10,000 クエリ	API キー（近日公開 — https://www.thehometeam.io/developers でウェイトリストに登録）

クイックテスト

# Health check
curl https://mcp.thehometeam.io/health

レジストリで確認する

curl "https://registry.modelcontextprotocol.io/v0/servers/io.github.JajuanX%2Fhometeam-directory/versions/latest"

ローカル開発

開発やコントリビューションのためにサーバーをローカルで実行する場合：

git clone https://github.com/JajuanX/hometeam-mcp-server.git
cd hometeam-mcp-server
npm install
cp .env.example .env
# Edit .env — set MONGO_URI to the same database as the backend

# Run with stdio transport (for Claude Desktop local testing)
npm run start:local

# Run with Streamable HTTP transport (for remote access)
npm start

ローカル用の Claude Desktop 設定：

{
  "mcpServers": {
    "hometeam": {
      "command": "node",
      "args": ["/absolute/path/to/hometeam-mcp-server/server.js"],
      "env": {
        "MONGO_URI": "your_mongodb_connection_string"
      }
    }
  }
}

重要： mcp-server ディレクトリで pwd を実行して得られる絶対パスを使用してください。stdio トランスポートでは stdout を JSON-RPC 通信に使用するため、console.log は console.error にリダイレクトされます。

---

利用可能なツール

この MCP サーバーは、AI アシスタントが呼び出せる 6 つのツールを公開しています。

search_businesses

キーワード、カテゴリ、近隣地域、郡でディレクトリを検索します。

{
  "query": "jerk chicken",
  "county": "Broward",
  "limit": 5,
  "sort": "most_visited"
}

一致する企業の名前、カテゴリ、近隣地域、評価、連絡先情報、Hometeam プロフィールへのリンクを返します。

---

get_business_details

特定の企業について、営業時間、連絡先、ソーシャルメディア、レビュー、現在の特典など、あらゆる情報を取得します。

{ "slug": "keishas-kitchen" }

または名前で検索します。

{ "name": "Keisha's Kitchen" }

最近のレビュー、有効な特典、コミュニティの信頼性を示す情報を含む、企業のプロフィール全体を返します。

---

find_by_specialty

スマート検索です。必要なものを平易な英語で説明してください。

{ "need": "someone to do box braids for my daughter's birthday", "location": "Miramar" }

{ "need": "tax preparation for my small business", "location": "Palm Beach" }

{ "need": "a barber who can do a fresh fade", "location": "Overtown" }

自然言語をカテゴリに対応付け、適切に検索します。これは、多くの AI アシスタントが最初に利用するツールです。

---

list_categories

ディレクトリ内のすべてのビジネスカテゴリーを返します。パラメーターは不要です。

カテゴリー：レストラン・フード、ヘア・ビューティー、ヘルス・ウェルネス、ホームサービス、専門サービス、小売・ショッピング、自動車サービス、教育・家庭教師、イベント・エンターテインメント、フィットネス・トレーニング、テクノロジー・メディア、不動産、保育・ファミリー、アート・クリエイティブ。

---

list_neighborhoods

サウスフロリダの近隣地域を返します。郡で絞り込むこともできます。

{ "county": "Broward" }

Miami-Dade、Broward、Palm Beach の各郡にまたがる29以上の近隣地域を網羅しています。

---

get_latest_draft_class

最新のDraft Class、つまりHometeamに新しく加わったビジネスを返します。パラメーターは不要です。

Hometeamでは、コミュニティイベントを通じて毎月新しいビジネスを迎え入れています。このツールを使うと、AIアシスタントは実際の最新データを使って「新しい情報は？」という質問に回答できます。

---

仕組み

User asks AI: "Find me a Black-owned caterer in Broward"
         │
         ▼
AI assistant sees Hometeam MCP tools are available
         │
         ▼
AI calls search_businesses({ query: "caterer", county: "Broward" })
         │
         ▼
Hometeam MCP server queries the live MongoDB database
         │
         ▼
Returns real business data: name, location, rating, contact, hours
         │
         ▼
AI presents the answer to the user with Hometeam attribution
         │
         ▼
User visits the business. Community grows.

データは常にリアルタイムで取得され、キャッシュされたスナップショットではありません。ビジネスが営業時間を更新したり、特典を投稿したりすると、MCP サーバーにすぐ反映されます。

---

プロジェクト構成

mcp-server/
├── server.js                  # Entry point (stdio transport — local/Claude Desktop)
├── httpServer.js              # Streamable HTTP transport (deployed/remote access)
├── config/
│   └── db.js                  # MongoDB connection
├── models/                    # Mongoose schemas (read-only, shared with backend DB)
│   ├── Business.js
│   ├── Category.js
│   ├── Neighborhood.js
│   ├── Review.js
│   ├── Event.js
│   ├── DraftClass.js
│   └── McpUsage.js
├── tools/                     # MCP tool definitions + handlers
│   ├── searchBusinesses.js
│   ├── getBusinessDetails.js
│   ├── findBySpecialty.js
│   ├── listCategories.js
│   ├── listNeighborhoods.js
│   └── getLatestDraftClass.js
├── middleware/
│   └── apiKeyAuth.js          # API key validation (paid tier — coming soon)
├── utils/
│   └── logUsage.js            # Query analytics logger
├── scripts/
│   └── release.js             # Semantic version release script
└── .env.example

---

トランスポートモード

Stdio（ローカル）

Claude Desktopおよびローカル開発向けです。JSON-RPCを使用し、stdin/stdout経由で通信します。

npm run start:local

重要： すべてのログ出力にはconsole.logではなくconsole.errorを使用してください。stdoutはMCPプロトコル専用です。console.logの出力があるとJSON-RPCストリームが破損し、接続がクラッシュします。

Streamable HTTP（デプロイ済み）

本番環境およびリモート AI エージェント向けです。Expressサーバーで、/mcp（および/）にステートレスなStreamable HTTPを提供します。APIキーは不要です。従来の/sseおよび/messagesルートは利用できなくなりました。

npm start
# Starts on PORT (default 3100, Heroku assigns dynamically)

エンドポイント：

メソッド	パス	説明
GET	/health	ヘルスチェック
POST	/mcp, /	MCP JSON-RPCリクエスト
GET	/mcp, /	405を返します。POSTを使用してください
DELETE	/mcp, /	セッションのクリーンアップ確認

---

開発ワークフロー

コーディング規約

プロジェクトルートのAGENTS.mdで定義されています（バックエンドと共有）。主なルール：

• ES Modules — すべての相対インポートで.js拡張子を付け、import/exportを使用します
• 一貫したAsync/awaitの使用
• console.errorのみ — console.logは使用しないでください（stdioトランスポートが壊れます）
• モデル — export defaultを使用し、バックエンドスキーマの読み取り専用バージョンを使います
• ツール — 各ツールを個別のファイルに置き、スキーマとハンドラーをエクスポートします

新しいMCPツールの追加

1. スキーマとハンドラーのエクスポートを含むmcp-server/tools/myNewTool.jsを作成します：

   export const myNewToolSchema = {
     description: 'What this tool does — written for an AI to understand when to use it',
     inputSchema: {
       type: 'object',
       properties: {
         param1: { type: 'string', description: 'What this parameter means' },
       },
       required: ['param1'],
     },
   };
   
   export const myNewToolHandler = async (args) => {
     // Query MongoDB, format results
     return { success: true, data: { args } };
   };
   

2. mcp-server/tools/index.jsに登録します：

   import { myNewToolHandler, myNewToolSchema } from './myNewTool.js';
   
   export const TOOL_DEFINITIONS = [
     // existing tools...
     {
       name: 'my_new_tool',
       description: myNewToolSchema.description,
       inputSchema: myNewToolSchema.inputSchema,
       handler: myNewToolHandler,
     },
   ];
   

3. MCP サーバーを再起動し、デプロイ前にClaude Desktopでローカルテストを行います。

ブランチ戦略とコミット

バックエンドと同様に、機能ブランチとConventional Commitsを使用します：

feat: add business-hours-aware search tool
fix: correct category matching in find_by_specialty
chore: update @modelcontextprotocol/sdk

---

バージョン管理とリリース

バージョンはpackage.jsonに記載され、MCP サーバーの情報とHTTPルートエンドポイントで提供されます。

# Bug fix (1.0.0 → 1.0.1)
npm run release:patch

# New feature — e.g., new MCP tool (1.0.0 → 1.1.0)
npm run release:minor

# Breaking change (1.0.0 → 2.0.0)
npm run release:major

このスクリプトは、作業ツリーがクリーンであることを確認 → package.jsonのバージョンを更新 → コミット → gitタグを作成 → プッシュ、の順に処理します。その後、Herokuが自動デプロイします。

---

デプロイ

Heroku

デプロイ版では、server.js（stdio）ではなくhttpServer.js（Streamable HTTP）を使用します。

heroku login
heroku create hometeam-mcp

heroku config:set NODE_ENV=production
heroku config:set MONGO_URI="your_mongodb_atlas_uri"
heroku config:set MCP_SERVER_NAME="hometeam-directory"
heroku config:set CORS_ORIGIN="*"

git push heroku main

# Verify
curl https://mcp.thehometeam.io/health

PORTは設定しないでください — Herokuが割り当てます。Procfileはnode httpServer.jsを実行します。

ツールの登録を確認する

curl https://mcp.thehometeam.io/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

レスポンスのresult.tools配列には、6つすべてのツール名が含まれます。

Claude DesktopのMCPログには、次のように表示されます：

tools/list → search_businesses, get_business_details, find_by_specialty,
             list_categories, list_neighborhoods, get_latest_draft_class

---

使用状況分析

すべてのクエリは匿名化され、MongoDBのmcpusagesコレクションに記録されます：

• 呼び出されたツール
• 入力パラメーター（サニタイズ済み）
• 結果に表示されたビジネス
• 応答時間

このデータは次の用途に役立ちます：

ビジネスオーナー向け： ダッシュボードのアクティビティフィードに「MCP経由でAIによるおすすめが提供されました」と表示され、AIエージェントが自社のビジネスをおすすめした頻度を確認できます。

プラットフォーム向け： 集計した傾向から需要が明らかになります — 「今月、Browardでカリブ料理のケータリングに関するクエリが300％増加しました。」

---

APIアクセスの段階

無料プラン（現在）

• IP アドレスごとに 1 日 100 クエリ
• 6 つすべてのツール
• 基本的なビジネスデータ
• API キー不要

Pro プラン（近日公開）

• 1 日 10,000 クエリ
• 拡張データ（すべてのレビュー、写真、特典、来店数）
• 使用状況分析ダッシュボード
• 優先サポート
• 月額 $99 から

掲載されているビジネスのオーナーに料金が請求されることはありません。 Hometeam は、掲載されているすべてのビジネスで無料です。

Pro プランのウェイトリストに登録 →

---

環境変数

NODE_ENV=development
PORT=3001
MONGO_URI=mongodb://localhost:27017/hometeam
MCP_SERVER_NAME=hometeam-directory
CORS_ORIGIN=*
MCP_BASE_URL=https://www.thehometeam.io
MCP_PUBLIC_URL=https://mcp.thehometeam.io

MCP_BASE_URL は任意で、/business/:slug と /draft-class/:slug のリンクに使用する公開ウェブサイトのオリジンを上書きします。デフォルトは https://www.thehometeam.io です。MCP_PUBLIC_URL はヘルスメタデータに使用する MCP サービスのオリジンであり、掲載ページへのリンクには使用されません。デプロイする前に、本番環境の MCP_BASE_URL を確認してください。既存の上書き設定はコード内のデフォルト値より優先され、意図したウェブサイトのオリジンを指定する必要があります。

MONGO_URI はバックエンドと同じデータベースを指している必要があります。MCP サーバーはそこからデータを読み取ります。ビジネスデータは書き込みません（使用状況ログのみ書き込みます）。

---

スクリプト

コマンド	説明
npm test	URL 回帰テスト（データベースや認証情報は不要）
npm start	Streamable HTTP サーバー（本番環境、デプロイ済み）
npm run start:local	Stdio サーバー（Claude Desktop、ローカル開発）
npm run dev	自動リロード付き Streamable HTTP
npm run dev:local	自動リロード付き Stdio
npm run release	リリース方法のヘルプを表示
npm run release:patch	バグ修正リリース
npm run release:minor	機能リリース
npm run release:major	破壊的変更を伴うリリース

---

対応地域

Miami-Dade County

Overtown · Liberty City · Little Haiti · Opa-locka · Carol City · Richmond Heights · Goulds · Florida City · Coconut Grove West · North Miami · Miami Gardens

Broward County

Lauderhill · Lauderdale Lakes · Fort Lauderdale · Plantation · Miramar · Pembroke Pines · Hollywood · Deerfield Beach · Pompano Beach · Dania Beach · Tamarac

Palm Beach County

West Palm Beach · Riviera Beach · Boynton Beach · Delray Beach · Belle Glade · Lake Worth Beach · Palm Beach Gardens

---

なぜ MCP なのか？

地域のビジネスディレクトリの多くは、ウェブサイトの中に閉じ込められています。存在を知り、アクセスして、手動で検索しなければなりません。

MCP によって、このプロトコルに対応するすべての AI アシスタントが Hometeam のデータを利用できるようになります。検索バーが 1 つあるウェブサイトが 1 つあるのではなく、何百万もの AI アシスタントが存在し、その一つひとつが黒人経営のビジネスにとって潜在的な流通チャネルになります。

誰かが AI に「Lauderhill で食事するならどこがいい？」と尋ねたとき、回答には黒人経営のレストランが含まれるべきです。それはアルゴリズムのおかげではなく、コミュニティがその店を確認し、Hometeam がデータを利用可能にしたからです。

---

関連リポジトリ

リポジトリ	説明
hometeam-backend	Node.js/Express API
hometeam-frontend	React/TypeScript のディレクトリ、ダッシュボード、マップ

---

貢献

皆さんからの貢献を歓迎します。新しい MCP ツールの追加、検索の関連性の改善、バグの修正を行う場合は、Issue を作成するか、PR を送信してください。

---

ライセンス

MIT

---

AI のおすすめを通じて訪れるお客様一人ひとりが、黒人経営のビジネスの扉をくぐります。それが目指すところです。