The Black Friday Agency

Developer & Agent Documentation

One canonical engine. Four doors.

Every interface below calls the same deterministic assess_ai_recommendation_readiness engine, so identical inputs produce identical results. It is read-only: it performs no consequential actions and guarantees no ranking or recommendation.

Endpoints at a glance

DoorURL
Human UIhttps://canairecommendmybusiness.com/decision-tools
Browser WebMCPhttps://canairecommendmybusiness.com/decision-tools
REST (POST)https://canairecommendmybusiness.com/api/v1/assess-ai-recommendation-readiness
MCP (JSON-RPC)https://canairecommendmybusiness.com/api/mcp
OpenAPIhttps://canairecommendmybusiness.com/openapi.json
Capability manifesthttps://canairecommendmybusiness.com/capability-manifest.json
Discoveryhttps://canairecommendmybusiness.com/.well-known/mcp.json

Inputs

businessSize — solo · micro · small · midmarket · enterprise

dataMaturity — none · basic · developing · structured · advanced

technicalStack — minimal · standard · modern · advanced

goals — ai_visibility · lead_generation · trust_authority · content_coverage · conversion_optimization · structured_data · agent_readiness · reputation_management

Required: businessSize, dataMaturity, technicalStack. Optional: goals, businessName, industry.

Outputs

readinessScore (0–100), tier, dimensionScores, gapAnalysis, priorityActions, and implementationRoadmap.

Door 1

Human UI

A no-code interactive form. Fill it in and get an instant readiness breakdown. It posts to the same REST engine used by every other door.

Open the assessment
Door 2

Browser WebMCP

On /decision-tools the page registers a page-level WebMCP tool named assess_ai_recommendation_readiness via document.modelContext.registerTool() (falling back to navigator.modelContext). A browser agent that supports WebMCP can discover and call it directly. When no WebMCP host is present, the page degrades gracefully to the REST door.

// Registered on the page (simplified)
document.modelContext.registerTool({
  name: "assess_ai_recommendation_readiness",
  inputSchema: { /* businessSize, dataMaturity, technicalStack, goals */ },
  handler: async (args) =>
    fetch("/api/v1/assess-ai-recommendation-readiness", {
      method: "POST",
      headers: { "Content-Type": "application/json",
                 "X-Interface": "browser_webmcp" },
      body: JSON.stringify(args),
    }).then((r) => r.json()),
});
Door 3

REST

POST structured JSON. CORS is open (*). An OpenAPI 3.1 description is at /openapi.json.

curl -X POST https://canairecommendmybusiness.com/api/v1/assess-ai-recommendation-readiness \
  -H "Content-Type: application/json" \
  -d '{
  "businessSize": "small",
  "dataMaturity": "developing",
  "technicalStack": "standard",
  "goals": ["ai_visibility", "structured_data"]
}'
Door 4

MCP (Model Context Protocol)

A genuine MCP server over Streamable HTTP (JSON-RPC 2.0), protocol revision 2025-06-18. Supports initialize, tools/list, tools/call, and ping.

Initialize:

curl -X POST https://canairecommendmybusiness.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18",
       "capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}'

Call the tool:

curl -X POST https://canairecommendmybusiness.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"assess_ai_recommendation_readiness",
       "arguments":{"businessSize":"small",
       "dataMaturity":"developing","technicalStack":"standard",
       "goals":["ai_visibility"]}}}'

Safety & scope

Every door is read-only and deterministic. Tool calls take no consequential actions (no bookings, purchases, or writes to third-party systems) and provide no guarantee of any ranking or recommendation outcome. Interface-level analytics record only categorical, non-sensitive data (which door, size bucket, resulting tier/score) — never raw inputs or PII.