hometeam-directory

🏠 Hometeam MCP 服务

向任何 AI 询问南佛罗里达州的黑人所有企业。这就是答案的来源。

Hometeam MCP 服务将 AI 助手连接到一个经过精心整理、由社区验证的目录，其中收录了迈阿密-戴德县、布劳沃德县和棕榈滩县的黑人所有企业。当有人问 Claude：“帮我找一家布劳沃德县的黑人所有餐饮服务商”，这个服务会提供答案背后真实且经过验证的数据。

基于 Model Context Protocol（MCP）构建——这是用于将 AI 助手连接到外部数据源的开放标准。

---

已发布到 MCP Registry

此服务已作为 io.github.JajuanX/hometeam-directory 列入 官方 MCP Registry。

在线端点： 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	使用自然语言搜索（“找一位在 Miramar 附近做箱式编辫的人”）
list_categories	全部 14 个企业类别
list_neighborhoods	迈阿密-戴德县、布劳沃德县和棕榈滩县的街区
get_latest_draft_class	Draft Day 新增的企业

速率限制

套餐	限制	访问方式
免费	每天 100 次查询	无需 API 密钥
Pro	每天 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，然后试着询问：

• “帮我在 Lauderhill 找一家黑人所有的餐厅”
• “Hometeam 刚加入了哪些新企业？”
• “我想找一位在 Miramar 附近做箱式编辫的人”

HTTP 端点

端点	说明
GET https://mcp.thehometeam.io/health	健康检查
POST https://mcp.thehometeam.io/mcp	MCP JSON-RPC 请求（Streamable HTTP）

速率限制

套餐	限制	获取方式
免费	每天 100 次查询	无需 API 密钥
Pro	每天 10,000 次查询	API 密钥（即将推出——在 https://www.thehometeam.io/developers 加入候补名单）

快速测试

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

在 Registry 上验证

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 获取的绝对路径。console.log 会重定向到 console.error，因为 stdio 传输使用 stdout 进行 JSON-RPC 通信。

---

可用工具

MCP 服务提供 6 个工具，AI 助手可以调用：

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" }

涵盖迈阿密-戴德县、布劳沃德县和棕榈滩县的 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 和本地开发。通过 stdin/stdout 使用 JSON-RPC 通信。

npm run start:local

重要： 所有日志都使用 console.error，而不是 console.log。Stdout 专用于 MCP 协议。任何 console.log 输出都会破坏 JSON-RPC 数据流并导致连接崩溃。

Streamable HTTP（已部署）

适用于生产环境和远程 AI Agent。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 — 使用 import/export，所有相对导入均带 .js 扩展名
• 全程使用 Async/await
• 仅使用 console.error — 切勿使用 console.log（会破坏 stdio 传输）
• 模型 — 使用 export default，采用后端架构的只读版本
• 工具 — 每个工具单独放在一个文件中，并导出 schema 和 handler

添加新的 MCP 工具

1. 创建 mcp-server/tools/myNewTool.js，并导出 schema 和 handler：

   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 在本地测试。

分支策略和提交

与后端相同——使用功能分支和约定式提交：

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

已部署的版本使用 httpServer.js（Streamable HTTP），而不是 server.js（stdio）。

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 Agent 推荐其业务的频率。

对平台： 汇总趋势可揭示需求——“本月布劳沃德县的加勒比餐饮查询量激增 300%。”

---

API 访问层级

免费版（当前）

• 每个 IP 每天 100 次查询
• 全部 6 个工具
• 基础商业数据
• 无需 API 密钥

Pro 版（即将推出）

• 每天 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	Bug 修复版本发布
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 的数据。不再只有一个带搜索栏的网站，而是有数百万个 AI 助手——每一个都可能成为黑人企业的分发渠道。

当有人问 AI“我该去 Lauderhill 的哪家餐厅吃饭？”时，答案应该包含黑人经营的餐厅。这不是因为某种算法，而是因为社区对它们进行了验证，且 Hometeam 让这些数据得以使用。

---

相关代码库

代码库	说明
hometeam-backend	Node.js/Express API
hometeam-frontend	React/TypeScript 目录、仪表板和地图

---

贡献

欢迎贡献。要添加新的 MCP 工具、提高搜索相关性或修复 Bug，请提交 issue 或 PR。

---

许可证

MIT

---

每一次 AI 推荐，都会让一位顾客走进黑人经营的商家。这正是我们的目标。