Hometeam MCP Server

🏠 主团队MCP服务器

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

Hometeam MCP服务器将人工智能助手连接到迈阿密戴德、布劳沃德和棕榈滩县的一个经过策划、社区验证的黑人企业目录。当有人问克劳德“在布劳沃德县给我找一个黑人所有的餐饮服务商”时，这台服务器会提供答案背后的真实、经过验证的数据。

建立在 模型上下文协议 （MCP）——将人工智能助手连接到外部数据源的开放标准。

______________________________________________________________________

发表于MCP注册表

此服务器列在 MCP官方注册 作为 io.github.JajuanX/hometeam-directory.

实时端点： https://mcp.thehometeam.io/sse

与克劳德桌面连接

添加到您的 claude_desktop_config.json:

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

可用工具

速率限制

______________________________________________________________________

连接到实时服务器

克劳德桌面版

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

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

重新启动克劳德桌面。然后问：

• “在劳德希尔给我找一家黑人开的餐馆”
• “哪些新企业刚刚加入Hometeam？”
• “我需要有人在米拉马尔附近做辫子”

HTTP端点

速率限制

快速测试

# Service info
curl https://mcp.thehometeam.io/

# 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/juanx/hometeam-project-orange.git
cd hometeam-project-orange/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 HTTP/SSE transport (for remote access)
npm start

本地Claude桌面配置：

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

重要提示： 使用来自的绝对路径 pwd 在mcp服务器目录中。 console.log 被重定向到 console.error 因为stdio传输使用stdout进行JSON-RPC通信。

______________________________________________________________________

可用工具

MCP服务器公开了6个AI助手可以调用的工具：

search_businesses

按关键字、类别、社区或县搜索目录。

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

返回具有名称、类别、社区、评级、联系信息和家庭团队个人资料链接的匹配企业。

______________________________________________________________________

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

将自然语言映射到类别并智能搜索。这是大多数人工智能助手首先使用的工具。

______________________________________________________________________

list_categories

返回目录中的所有业务类别。不需要参数。

分类：餐厅与食品、美发与美容、健康与保健、家庭服务、专业服务、零售与购物、汽车服务、教育与辅导、活动与娱乐、健身与培训、技术与媒体、房地产、儿童保育与家庭、艺术与创意。

______________________________________________________________________

list_neighborhoods

返回南佛罗里达州的社区，可选择按县过滤。

{ "county": "Broward" }

覆盖迈阿密戴德、布劳沃德和棕榈滩县的29多个社区。

______________________________________________________________________

get_latest_draft_class

返回最新的草稿类——加入Hometeam的最新企业。不需要参数。

Hometeam每月通过社区活动起草新业务。这个工具让人工智能助手用真实、及时的数据回答“有什么新鲜事吗？”的问题。

______________________________________________________________________

运作原理

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              # HTTP/SSE 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.error，不 console.log.Stdout是为MCP协议保留的。任何 console.log 输出会损坏JSON-RPC流并导致连接崩溃。

HTTP/SSE（已部署）

用于生产和远程AI代理。带有服务器发送事件的Express服务器。

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

终点：

______________________________________________________________________

开发人员工作流程

编码约定

定义于 AGENTS.md 在项目根目录下（与后端共享）。关键规则：

• ES模块 — import/export 随着 .js 所有相关进口的延期
• 异步/等待 贯穿
• 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 } };
   };

1. 在中注册 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,
     },
   ];

1. 在部署之前，重新启动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

脚本：检查工作树是否干净→ bumps package.json → 提交→ 创建git标签→ 推→ Heroku自动部署。

______________________________________________________________________

部署

Heroku

部署版本使用 httpServer.js （HTTP/SSE），不是 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/
curl https://mcp.thehometeam.io/health

不设置端口 --Heroku分配它 Procfile 跑 node httpServer.js.

验证工具是否已注册

curl https://mcp.thehometeam.io/

响应包括中的所有6个工具名称 tools 阵列。

在Claude Desktop MCP日志中，您应该看到：

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

______________________________________________________________________

使用情况分析

每个查询都会记录（匿名）到 mcpusages MongoDB集合：

• 调用了哪个工具
• 输入参数（已净化）
• 哪些企业出现在结果中
• 响应时间

此数据支持：

对于企业主： 他们的仪表板在活动提要中显示“通过MCP提供的AI推荐”，以及AI代理推荐其业务的频率。

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

______________________________________________________________________

API访问层

免费等级（当前）

• 每个IP每天100次查询
• 全部6个工具
• 基本业务数据
• 不需要API密钥

专业版（即将推出）

• 每天10000次查询
• 增强数据（完整评论、照片、特价、访问次数）
• 使用分析仪表板
• 优先支持
• 起价：99美元/月

企业主永远不会被起诉。 Hometeam对所有上市企业免费。

加入专业级候补名单→

______________________________________________________________________

环境变量

NODE_ENV=development
PORT=3001
MONGO_URI=mongodb://localhost:27017/hometeam
MCP_SERVER_NAME=hometeam-directory
CORS_ORIGIN=*

这 MONGO_URI 必须指向与后端相同的数据库。MCP服务器从中读取；它不写入业务数据（只写入使用日志）。

______________________________________________________________________

脚本

______________________________________________________________________

覆盖

迈阿密戴德县

上城·自由城·小海地·奥帕洛卡·卡罗尔城·里士满高地·古尔德斯·佛罗里达城·椰林西·北迈阿密·迈阿密花园

布劳沃德县

劳德代尔山·劳德代尔湖·劳德代尔堡·种植园·米拉马尔·彭布罗克松林·好莱坞·迪尔菲尔德海滩·蓬帕诺海滩·达尼亚海滩·塔马拉克

棕榈滩县

西棕榈滩·里维埃拉海滩·博因顿海滩·德尔雷海滩·贝尔格莱德·沃斯湖海滩·棕榈滩花园

______________________________________________________________________

为什么选择MCP？

大多数本地商业目录都被困在网站后面。你必须知道它们的存在，访问它们，并手动搜索。

MCP使Hometeam的数据可供支持该协议的每个AI助手使用。一个网站没有一个搜索栏，而是有数百万个人工智能助手——每个助手都是黑人企业的潜在分销渠道。

当有人问他们的人工智能“我应该在Lauderhill哪里吃饭？”时，答案应该包括黑人拥有的餐馆。不是因为算法，而是因为社区验证了它们，Hometeam提供了数据。

______________________________________________________________________

相关repos

______________________________________________________________________

贡献

我们欢迎捐款。要添加新的MCP工具、提高搜索相关性或修复错误：打开问题或提交PR。

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

*每一个人工智能推荐都是一个客户走进黑人拥有的企业的大门。这才是重点。*