{
  "markdown": "# 🏠 Hometeam MCP Server\n\n**Ask any AI about Black-owned businesses in South Florida. This is where the answers come from.**\n\nThe Hometeam MCP server connects AI assistants to a curated, community-verified directory of Black-owned businesses across Miami-Dade, Broward, and Palm Beach counties. When someone asks Claude, \"find me a Black-owned caterer in Broward County,\" this server provides the real, verified data behind the answer.\n\nBuilt on the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) — the open standard for connecting AI assistants to external data sources.\n\n---\n\n## Published on the MCP Registry\n\nThis server is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.JajuanX/hometeam-directory`.\n\n**Live endpoint:** `https://mcp.thehometeam.io/sse`\n\n### Connect with Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hometeam\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote@latest\",\n        \"https://mcp.thehometeam.io/sse\"\n      ]\n    }\n  }\n}\n```\n\n### Available tools\n\n| Tool | Description |\n|------|-------------|\n| `search_businesses` | Search by keyword, category, neighborhood, or county |\n| `get_business_details` | Get full profile: hours, contact, reviews, specials |\n| `find_by_specialty` | Natural language search (\"someone to do box braids near Miramar\") |\n| `list_categories` | All 14 business categories |\n| `list_neighborhoods` | Neighborhoods across Miami-Dade, Broward, Palm Beach |\n| `get_latest_draft_class` | Newest businesses added on Draft Day |\n\n### Rate limits\n\n| Tier | Limit | Access |\n|------|-------|--------|\n| Free | 100 queries/day | No API key needed |\n| Pro | 10,000 queries/day | API key (coming soon) |\n\n---\n\n## Connect to the live server\n\n### Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"hometeam\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote@latest\",\n        \"https://mcp.thehometeam.io/sse\"\n      ]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Then ask:\n- \"Find me a Black-owned restaurant in Lauderhill\"\n- \"What new businesses just joined Hometeam?\"\n- \"I need someone to do box braids near Miramar\"\n\n### HTTP endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET https://mcp.thehometeam.io/` | Service info and available tools |\n| `GET https://mcp.thehometeam.io/health` | Health check |\n| `GET https://mcp.thehometeam.io/sse` | SSE connection for MCP clients |\n| `POST https://mcp.thehometeam.io/messages` | MCP message handler |\n\n### Rate limits\n\n| Tier | Limit | How to access |\n|------|-------|---------------|\n| Free | 100 queries/day | No API key required |\n| Pro | 10,000 queries/day | API key (coming soon — join the waitlist at thehometeam.io/developers) |\n\n### Quick test\n\n```bash\n# Service info\ncurl https://mcp.thehometeam.io/\n\n# Health check\ncurl https://mcp.thehometeam.io/health\n```\n\n### Verify on the registry\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0/servers/io.github.JajuanX%2Fhometeam-directory/versions/latest\"\n```\n\n### Local development\n\nIf you want to run the server locally (for development or contributing):\n\n```bash\ngit clone https://github.com/juanx/hometeam-project-orange.git\ncd hometeam-project-orange/hometeam/mcp-server\nnpm install\ncp .env.example .env\n# Edit .env — set MONGO_URI to the same database as the backend\n\n# Run with stdio transport (for Claude Desktop local testing)\nnpm run start:local\n\n# Run with HTTP/SSE transport (for remote access)\nnpm start\n```\n\nClaude Desktop config for local:\n\n```json\n{\n  \"mcpServers\": {\n    \"hometeam\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/hometeam-mcp-server/server.js\"],\n      \"env\": {\n        \"MONGO_URI\": \"your_mongodb_connection_string\"\n      }\n    }\n  }\n}\n```\n\n**Important:** Use the absolute path from `pwd` in the mcp-server directory. `console.log` is redirected to `console.error` because stdio transport uses stdout for JSON-RPC communication.\n\n---\n\n## Available tools\n\nThe MCP server exposes 6 tools that AI assistants can call:\n\n### `search_businesses`\nSearch the directory by keyword, category, neighborhood, or county.\n\n```json\n{\n  \"query\": \"jerk chicken\",\n  \"county\": \"Broward\",\n  \"limit\": 5,\n  \"sort\": \"most_visited\"\n}\n```\n\nReturns matching businesses with name, category, neighborhood, rating, contact info, and Hometeam profile link.\n\n---\n\n### `get_business_details`\nGet everything about a specific business — hours, contact, social media, reviews, current specials.\n\n```json\n{ \"slug\": \"keishas-kitchen\" }\n```\n\nOr search by name:\n\n```json\n{ \"name\": \"Keisha's Kitchen\" }\n```\n\nReturns the full business profile including recent reviews, active specials, and community trust signals.\n\n---\n\n### `find_by_specialty`\nThe smart search. Describe what you need in plain English.\n\n```json\n{ \"need\": \"someone to do box braids for my daughter's birthday\", \"location\": \"Miramar\" }\n```\n\n```json\n{ \"need\": \"tax preparation for my small business\", \"location\": \"Palm Beach\" }\n```\n\n```json\n{ \"need\": \"a barber who can do a fresh fade\", \"location\": \"Overtown\" }\n```\n\nMaps natural language to categories and searches intelligently. This is the tool most AI assistants reach for first.\n\n---\n\n### `list_categories`\nReturns all business categories in the directory. No parameters needed.\n\nCategories: Restaurants & Food, Hair & Beauty, Health & Wellness, Home Services, Professional Services, Retail & Shopping, Auto Services, Education & Tutoring, Events & Entertainment, Fitness & Training, Technology & Media, Real Estate, Childcare & Family, Arts & Creative.\n\n---\n\n### `list_neighborhoods`\nReturns South Florida neighborhoods, optionally filtered by county.\n\n```json\n{ \"county\": \"Broward\" }\n```\n\nCovers 29+ neighborhoods across Miami-Dade, Broward, and Palm Beach counties.\n\n---\n\n### `get_latest_draft_class`\nReturns the most recent Draft Class — the newest businesses to join Hometeam. No parameters needed.\n\nHometeam drafts new businesses monthly through community events. This tool lets AI assistants answer \"what's new?\" questions with real, timely data.\n\n---\n\n## How it works\n\n```\nUser asks AI: \"Find me a Black-owned caterer in Broward\"\n         │\n         ▼\nAI assistant sees Hometeam MCP tools are available\n         │\n         ▼\nAI calls search_businesses({ query: \"caterer\", county: \"Broward\" })\n         │\n         ▼\nHometeam MCP server queries the live MongoDB database\n         │\n         ▼\nReturns real business data: name, location, rating, contact, hours\n         │\n         ▼\nAI presents the answer to the user with Hometeam attribution\n         │\n         ▼\nUser visits the business. Community grows.\n```\n\nThe data is always live — not a cached snapshot. When a business updates their hours or posts a special, the MCP server reflects it immediately.\n\n---\n\n## Project structure\n\n```\nmcp-server/\n├── server.js                  # Entry point (stdio transport — local/Claude Desktop)\n├── httpServer.js              # HTTP/SSE transport (deployed/remote access)\n├── config/\n│   └── db.js                  # MongoDB connection\n├── models/                    # Mongoose schemas (read-only, shared with backend DB)\n│   ├── Business.js\n│   ├── Category.js\n│   ├── Neighborhood.js\n│   ├── Review.js\n│   ├── Event.js\n│   ├── DraftClass.js\n│   └── McpUsage.js\n├── tools/                     # MCP tool definitions + handlers\n│   ├── searchBusinesses.js\n│   ├── getBusinessDetails.js\n│   ├── findBySpecialty.js\n│   ├── listCategories.js\n│   ├── listNeighborhoods.js\n│   └── getLatestDraftClass.js\n├── middleware/\n│   └── apiKeyAuth.js          # API key validation (paid tier — coming soon)\n├── utils/\n│   └── logUsage.js            # Query analytics logger\n├── scripts/\n│   └── release.js             # Semantic version release script\n└── .env.example\n```\n\n---\n\n## Transport modes\n\n### Stdio (local)\nFor Claude Desktop and local development. Communicates via stdin/stdout using JSON-RPC.\n\n```bash\nnpm run start:local\n```\n\n**Critical:** All logging uses `console.error`, not `console.log`. Stdout is reserved for the MCP protocol. Any `console.log` output corrupts the JSON-RPC stream and crashes the connection.\n\n### HTTP/SSE (deployed)\nFor production and remote AI agents. Express server with Server-Sent Events.\n\n```bash\nnpm start\n# Starts on PORT (default 3001, Heroku assigns dynamically)\n```\n\nEndpoints:\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/` | Service info, version, tool list |\n| GET | `/health` | Health check |\n| GET | `/sse` | SSE connection for MCP clients |\n| POST | `/messages` | MCP JSON-RPC message handler |\n\n---\n\n## Developer workflow\n\n### Coding conventions\n\nDefined in `AGENTS.md` at the project root (shared with the backend). Key rules:\n\n- **ES Modules** — `import`/`export` with `.js` extensions on all relative imports\n- **Async/await** throughout\n- **`console.error` only** — never `console.log` (breaks stdio transport)\n- **Models** — `export default`, read-only versions of backend schemas\n- **Tools** — each tool in its own file, exports schema + handler\n\n### Adding a new MCP tool\n\n1. Create `mcp-server/tools/myNewTool.js` with a schema and handler export:\n   ```javascript\n   export const myNewToolSchema = {\n     description: 'What this tool does — written for an AI to understand when to use it',\n     inputSchema: {\n       type: 'object',\n       properties: {\n         param1: { type: 'string', description: 'What this parameter means' },\n       },\n       required: ['param1'],\n     },\n   };\n\n   export const myNewToolHandler = async (args) => {\n     // Query MongoDB, format results\n     return { success: true, data: { args } };\n   };\n   ```\n\n2. Register it in `mcp-server/tools/index.js`:\n   ```javascript\n   import { myNewToolHandler, myNewToolSchema } from './myNewTool.js';\n\n   export const TOOL_DEFINITIONS = [\n     // existing tools...\n     {\n       name: 'my_new_tool',\n       description: myNewToolSchema.description,\n       inputSchema: myNewToolSchema.inputSchema,\n       handler: myNewToolHandler,\n     },\n   ];\n   ```\n\n3. Restart the MCP server and test with Claude Desktop locally before deploying.\n\n### Branch strategy and commits\n\nSame as the backend — feature branches, conventional commits:\n\n```\nfeat: add business-hours-aware search tool\nfix: correct category matching in find_by_specialty\nchore: update @modelcontextprotocol/sdk\n```\n\n---\n\n## Versioning and releases\n\nVersion lives in `package.json` and is served in the MCP server info and HTTP root endpoint.\n\n```bash\n# Bug fix (1.0.0 → 1.0.1)\nnpm run release:patch\n\n# New feature — e.g., new MCP tool (1.0.0 → 1.1.0)\nnpm run release:minor\n\n# Breaking change (1.0.0 → 2.0.0)\nnpm run release:major\n```\n\nThe script: checks for clean working tree → bumps `package.json` → commits → creates git tag → pushes → Heroku auto-deploys.\n\n---\n\n## Deployment\n\n### Heroku\n\nThe deployed version uses `httpServer.js` (HTTP/SSE), not `server.js` (stdio).\n\n```bash\nheroku login\nheroku create hometeam-mcp\n\nheroku config:set NODE_ENV=production\nheroku config:set MONGO_URI=\"your_mongodb_atlas_uri\"\nheroku config:set MCP_SERVER_NAME=\"hometeam-directory\"\nheroku config:set CORS_ORIGIN=\"*\"\n\ngit push heroku main\n\n# Verify\ncurl https://mcp.thehometeam.io/\ncurl https://mcp.thehometeam.io/health\n```\n\n**Do not set PORT** — Heroku assigns it. The `Procfile` runs `node httpServer.js`.\n\n### Verify tools are registered\n\n```bash\ncurl https://mcp.thehometeam.io/\n```\n\nResponse includes all 6 tool names in the `tools` array.\n\nIn Claude Desktop MCP logs, you should see:\n```\ntools/list → search_businesses, get_business_details, find_by_specialty,\n             list_categories, list_neighborhoods, get_latest_draft_class\n```\n\n---\n\n## Usage analytics\n\nEvery query is logged (anonymized) to the `mcpusages` MongoDB collection:\n\n- Which tool was called\n- Input parameters (sanitized)\n- Which businesses appeared in results\n- Response time\n\nThis data powers:\n\n**For business owners:** Their dashboard shows \"AI recommendation served via MCP\" in the activity feed, with how often AI agents recommend their business.\n\n**For the platform:** Aggregated trends reveal demand — \"Caribbean catering queries spiked 300% in Broward this month.\"\n\n---\n\n## API access tiers\n\n### Free tier (current)\n- 100 queries per day per IP\n- All 6 tools\n- Basic business data\n- No API key required\n\n### Pro tier (coming soon)\n- 10,000 queries per day\n- Enhanced data (full reviews, photos, specials, visit counts)\n- Usage analytics dashboard\n- Priority support\n- Starting at $99/month\n\n**Business owners are never charged.** Hometeam is free for all listed businesses.\n\n[Join the Pro tier waitlist →](https://hometeam.app/developers)\n\n---\n\n## Environment variables\n\n```env\nNODE_ENV=development\nPORT=3001\nMONGO_URI=mongodb://localhost:27017/hometeam\nMCP_SERVER_NAME=hometeam-directory\nCORS_ORIGIN=*\n```\n\nThe `MONGO_URI` must point to the same database as the backend. The MCP server reads from it; it does not write business data (only writes usage logs).\n\n---\n\n## Scripts\n\n| Command | Description |\n|---------|-------------|\n| `npm start` | HTTP/SSE server (production, deployed) |\n| `npm run start:local` | Stdio server (Claude Desktop, local dev) |\n| `npm run dev` | HTTP/SSE with auto-reload |\n| `npm run dev:local` | Stdio with auto-reload |\n| `npm run release` | Show release usage help |\n| `npm run release:patch` | Bug fix release |\n| `npm run release:minor` | Feature release |\n| `npm run release:major` | Breaking change release |\n\n---\n\n## Coverage\n\n### Miami-Dade County\nOvertown · Liberty City · Little Haiti · Opa-locka · Carol City · Richmond Heights · Goulds · Florida City · Coconut Grove West · North Miami · Miami Gardens\n\n### Broward County\nLauderhill · Lauderdale Lakes · Fort Lauderdale · Plantation · Miramar · Pembroke Pines · Hollywood · Deerfield Beach · Pompano Beach · Dania Beach · Tamarac\n\n### Palm Beach County\nWest Palm Beach · Riviera Beach · Boynton Beach · Delray Beach · Belle Glade · Lake Worth Beach · Palm Beach Gardens\n\n---\n\n## Why MCP?\n\nMost local business directories are trapped behind websites. You have to know they exist, visit them, and search manually.\n\nMCP makes Hometeam's data available to every AI assistant that supports the protocol. Instead of one website with one search bar, there are millions of AI assistants — each one a potential distribution channel for Black-owned businesses.\n\nWhen someone asks their AI \"where should I eat in Lauderhill?\", the answer should include Black-owned restaurants. Not because of an algorithm, but because the community verified them and Hometeam made the data available.\n\n---\n\n## Related repos\n\n| Repo | Description |\n|------|-------------|\n| [hometeam-backend](https://github.com/juanx/hometeam-backend) | Node.js/Express API |\n| [hometeam-frontend](https://github.com/juanx/hometeam-frontend) | React/TypeScript directory, dashboards, map |\n\n---\n\n## Contributing\n\nWe welcome contributions. To add a new MCP tool, improve search relevance, or fix a bug: open an issue or submit a PR.\n\n---\n\n## License\n\nMIT\n\n---\n\n*Every AI recommendation is a customer walking through a Black-owned business's door. That's the point.*\n",
  "bytes": 15222,
  "sha": "b3570eb38ae99ee6a15389cced5733fb65ab36e9490ae86febc150a205313b58",
  "repo_slug": "jajuanx/hometeam-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jajuanx_hometeam_directory_17a3e0d8/readme"
}