From d936e1e9a7decec531cd815c3538a6e5bc0007ff Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 13 Nov 2026 13:34:28 +0000 Subject: [PATCH 1/2] Add recommend: one pick and the next step for a need, on MCP, WebMCP and GET /api/recommend Co-authored-by: assaf.barnir --- DISTRIBUTION.md | 2 +- README.md | 3 +- app/api/[transport]/route.ts | 55 +++++- app/api/recommend/route.ts | 39 +++++ app/connect/page.tsx | 7 +- app/for-agents/page.tsx | 6 +- app/index.md/route.ts | 3 +- app/llms.txt/route.ts | 10 +- app/page.tsx | 4 +- app/robots.ts | 5 +- docs/API.md | 58 ++++++- e2e/tests/60-machine-endpoints.spec.mjs | 29 +++- lib/decide.test.ts | 47 +++++- lib/decide.ts | 120 ++++++++++++- lib/mcp-tools.ts | 1 + lib/public-api.ts | 11 ++ lib/webmcp-tools.ts | 63 ++++++- plugins/agent-switchboard/README.md | 1 + public/.well-known/mcp.json | 22 ++- public/.well-known/webmcp.json | 216 +++++++++++++++++++++++- public/openapi.json | 104 +++++++++++- public/skill.md | 3 +- scripts/mcp-smoke.mjs | 6 +- tests/organic-surfaces.test.ts | 10 +- 24 files changed, 788 insertions(+), 37 deletions(-) create mode 100644 app/api/recommend/route.ts diff --git a/DISTRIBUTION.md b/DISTRIBUTION.md index ff6bb0a..0311eb6 100644 --- a/DISTRIBUTION.md +++ b/DISTRIBUTION.md @@ -3,7 +3,7 @@ Where the Agent Switchboard MCP server is listed, and how to update each channel. The server: remote streamable-HTTP at `https://agentswitchboard.dev/api/mcp` (no auth). -Tools: `search_agents`, `get_agent`, `list_categories`, `compare_agents`, `alternatives_to`, `connect_bundle`, `submit_listing`. +Tools: `search_agents`, `get_agent`, `list_categories`, `compare_agents`, `alternatives_to`, `connect_bundle`, `recommend`, `submit_listing`. User-facing setup steps per assistant: [/connect](https://agentswitchboard.dev/connect). **AI-assistant surfaces are always organic.** The MCP server and the WebMCP tools rank by diff --git a/README.md b/README.md index 107fb33..329cc7e 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,8 @@ Point any MCP client at it and query the catalog with native tools: Tools: `search_agents` · `get_agent` · `list_categories` · `compare_agents` · `alternatives_to` · `connect_bundle` (one MCP client config for up to 10 -listings) · `submit_listing` (files a public GitHub issue for review; publishes +listings) · `recommend` (one pick and the next step for a need, in a sentence) · +`submit_listing` (files a public GitHub issue for review; publishes nothing). Streamable HTTP, no auth. Stdio-only clients: `npx -y mcp-remote https://agentswitchboard.dev/api/mcp` diff --git a/app/api/[transport]/route.ts b/app/api/[transport]/route.ts index 4ba45d5..47a069a 100644 --- a/app/api/[transport]/route.ts +++ b/app/api/[transport]/route.ts @@ -17,7 +17,7 @@ import { z } from 'zod'; import { VERIFIED_DEFINITION } from '@/components/VerifiedBadge'; import { getEveryAgent, getAllCategories, getRetiredListings } from '@/lib/catalog'; import { COMPARE_QUERY_KEYS } from '@/lib/compare-link'; -import { alternativesDecision, bundleDecision, compareDecision, type Decision } from '@/lib/decide'; +import { alternativesDecision, bundleDecision, compareDecision, recommendDecision, type Decision } from '@/lib/decide'; import { absoluteIconUrl } from '@/lib/icons'; import { organicOrder, withoutPlacement } from '@/lib/organic'; import { logConsumer } from '@/lib/log'; @@ -36,6 +36,8 @@ import { COMPARE_SLUGS_INPUT, CONNECT_BUNDLE_DESCRIPTION, OFFICIAL_DEFINITION, + RECOMMEND_DESCRIPTION, + RECOMMEND_NEED_INPUT, SINCE_INPUT, TASK_INPUT, VERIFIED_INPUT, @@ -90,6 +92,7 @@ const CORS = { const INSTRUCTIONS = 'Agent Switchboard is a curated directory of AI agents, MCP servers, and agentic tools. ' + + 'When the user wants one tool for a job, recommend takes their need in a sentence and returns one pick, why, the next step to start using it and two alternatives. ' + 'Use search_agents to find tools for a job (pick a task such as "query-a-database", or filter by category, access method, official, verified, or auth type; ' + 'since keeps what was added lately; sort by newest or most skills), get_agent for one listing, and list_categories for valid category slugs. ' + 'To help a user choose: compare_agents puts 2 or 3 listings side by side, alternatives_to finds listings that could stand in for one, ' + @@ -504,6 +507,54 @@ const handler = createMcpHandler( } ); + server.registerTool( + 'recommend', + { + title: 'Recommend', + description: RECOMMEND_DESCRIPTION, + annotations: readOnly('Recommend'), + inputSchema: { + need: z.string().max(2000).describe(RECOMMEND_NEED_INPUT), + }, + outputSchema: { + request: z.string().describe('The need as read'), + answer: z.string().describe('The recommendations in plain sentences, one line per need, ready to tell the user'), + recommendations: z.array( + z.object({ + need: z.string().describe("The user's words for this need"), + task: z.object({ slug: z.string(), label: z.string(), url: z.string() }).describe('The directory task it matched'), + pick: z.object(decisionAgentShape), + pickedBecause: z.string(), + why: z.string().nullable().describe('The skill of the pick that does the task'), + unmet: z.array(z.string()).describe('What the need asked for that no listing for the task has'), + nextStep: z.object({ + how: z + .enum(['config', 'guide', 'other']) + .describe('config: paste server into an MCP client; guide: an MCP server to set up from url; other: no MCP server, start from url'), + label: z.string(), + url: z.string().describe("The vendor's setup instructions"), + server: mcpServerShape.nullable().describe('With how config: its entry for mcpServers'), + note: z.string().describe('How it connects'), + }), + alternatives: z.array(z.object(decisionAgentShape)), + fits: z.number().int().describe('How many listings do the task'), + }) + ), + unmatched: z + .array(z.object({ need: z.string(), nearestTasks: z.array(z.object({ slug: z.string(), label: z.string(), url: z.string() })) })) + .describe('Needs with no pick, and the tasks closest to them'), + stackUrl: z.string().nullable().describe('Two or more picks as a shared stack on the site'), + operatorUrl: z.string().describe('The same request on the site'), + basis: z.string().describe('How the pick is made'), + notes: z.array(z.string()), + }, + }, + async ({ need }) => { + const catalog = await organicCatalog(); + return decisionResult(recommendDecision(need, getTasks(), catalog)); + } + ); + server.registerTool( 'submit_listing', { @@ -518,7 +569,7 @@ const handler = createMcpHandler( ); }, { - serverInfo: { name: 'agentswitchboard', version: '1.8.0' }, + serverInfo: { name: 'agentswitchboard', version: '1.9.0' }, instructions: INSTRUCTIONS, }, { diff --git a/app/api/recommend/route.ts b/app/api/recommend/route.ts new file mode 100644 index 0000000..05b61c8 --- /dev/null +++ b/app/api/recommend/route.ts @@ -0,0 +1,39 @@ +/** + * One recommendation for what a user needs, and the next step to start using it. + * + * GET /api/recommend?need= + * → { request, answer, recommendations: [ { need, task, pick, pickedBecause, + * why, unmet, nextStep: { how, label, url, server, note }, + * alternatives, fits } ], unmatched, stackUrl, operatorUrl, basis, notes } + * + * The Operator's pick (lib/operator.ts) for each need the request names, from + * the catalog in organic order: no featured order and no placement field. + * No need is a 400; a need no task matches is a 404 with the closest tasks. + * The need's text is never logged. Read-only, no auth, open CORS. + */ + +import { getEveryAgent } from '@/lib/catalog'; +import { recommendDecision } from '@/lib/decide'; +import { logConsumer } from '@/lib/log'; +import { organicOrder, withoutPlacement } from '@/lib/organic'; +import { corsPreflight, jsonResponse } from '@/lib/public-api'; +import { getTasks } from '@/lib/tasks'; + +export const dynamic = 'force-dynamic'; + +export async function GET(req: Request): Promise { + const need = new URL(req.url).searchParams.get('need') ?? ''; + const decision = recommendDecision(need, getTasks(), organicOrder(await getEveryAgent())); + logConsumer('/api/recommend', req, { + picks: decision.ok ? decision.body.recommendations.length : 0, + unmatched: decision.ok ? decision.body.unmatched.length : decision.error, + }); + if (!decision.ok) { + return jsonResponse({ error: decision.error, message: decision.message, ...decision.extra }, decision.status); + } + return jsonResponse(withoutPlacement(decision.body)); +} + +export async function OPTIONS(): Promise { + return corsPreflight(); +} diff --git a/app/connect/page.tsx b/app/connect/page.tsx index 9e490dd..0181fd7 100644 --- a/app/connect/page.tsx +++ b/app/connect/page.tsx @@ -36,7 +36,8 @@ const XAI_API_EXAMPLE = `curl https://api.x.ai/v1/responses \\ "server_label": "agentswitchboard", "allowed_tools": [ "search_agents", "get_agent", "list_categories", - "compare_agents", "alternatives_to", "connect_bundle" + "compare_agents", "alternatives_to", "connect_bundle", + "recommend" ] }] }'`; @@ -63,6 +64,10 @@ const TOOLS: { name: string; does: string }[] = [ name: 'connect_bundle', does: "One MCP client config to paste for up to 10 listings, copied from each vendor's docs, and how to connect the rest.", }, + { + name: 'recommend', + does: 'One pick for what your user needs, said in a sentence, with why it fits, the next step to start using it and two alternatives.', + }, { name: 'submit_listing', does: 'Suggest a new listing. Opens a public GitHub issue for review; publishes nothing.' }, ]; diff --git a/app/for-agents/page.tsx b/app/for-agents/page.tsx index 1c02606..9018c1b 100644 --- a/app/for-agents/page.tsx +++ b/app/for-agents/page.tsx @@ -117,8 +117,9 @@ export default async function ForAgentsPage() { Connect directly and query the catalog with native tools —{' '} search_agents,{' '} get_agent,{' '} - list_categories — help a user - choose with compare_agents,{' '} + list_categories — get one pick and + the next step for a need with recommend, + help a user choose with compare_agents,{' '} alternatives_to and{' '} connect_bundle (one MCP client config for up to {MY_STACK_MAX} listings), and suggest a listing with{' '} @@ -186,6 +187,7 @@ GET /api/agents//alternatives GET /api/categories GET /api/compare?a=&b=&c= GET /api/bundle?items=, +GET /api/recommend?need= GET /api/stacks GET /api/stacks/ GET /api/tasks diff --git a/app/index.md/route.ts b/app/index.md/route.ts index 99d67e9..8a5bd4a 100644 --- a/app/index.md/route.ts +++ b/app/index.md/route.ts @@ -74,8 +74,9 @@ On the website, the REST API and /agents.json, a \`sponsored\` flag also marks p ## What to use -- \`${BASE_URL}/api/mcp\` — MCP server (streamable HTTP). Tools: \`search_agents\`, \`get_agent\`, \`list_categories\`, \`compare_agents\`, \`alternatives_to\`, \`connect_bundle\`, \`submit_listing\` (files a public GitHub issue for review). Setup for Grok, Claude, ChatGPT: [/connect](${BASE_URL}/connect). +- \`${BASE_URL}/api/mcp\` — MCP server (streamable HTTP). Tools: \`search_agents\`, \`get_agent\`, \`list_categories\`, \`compare_agents\`, \`alternatives_to\`, \`connect_bundle\`, \`recommend\`, \`submit_listing\` (files a public GitHub issue for review). Setup for Grok, Claude, ChatGPT: [/connect](${BASE_URL}/connect). - \`GET ${BASE_URL}/api/agents?q=&task=&category=&access=&official=&verified=&auth=&since=&sort=&limit=&offset=&page=\` — plain REST search, no auth. \`auth=none\` keeps listings that need no key or sign-in; \`task\` keeps those that fit a task from \`/api/tasks\`; \`since=7\` (or a date, \`YYYY-MM-DD\`) keeps what was added in the last 7 days; \`sort\` is \`relevance\`, \`newest\`, \`skills\` or \`name\`. Detail: \`/api/agents/{slug}\`. +- To recommend one tool: \`/api/recommend?need={the need, in a sentence}\` (or the MCP tool \`recommend\`) gives one pick for each need it names, why it fits, the next step to start using it and two alternatives, by the Operator's fixed rules. - To help a user choose and set up: \`/api/compare?a={slug}&b={slug}&c={slug}\` puts 2 or 3 listings side by side; \`/api/agents/{slug}/alternatives\` lists the ones that could stand in for one, each with why; \`/api/bundle?items={slug},{slug}\` gives one MCP client config for up to ${MY_STACK_MAX} listings, and how to connect the rest. The MCP tools \`compare_agents\`, \`alternatives_to\` and \`connect_bundle\` return the same. - [/openapi.json](${BASE_URL}/openapi.json) — OpenAPI 3.1 description of the HTTP surface. - [/.well-known/mcp.json](${BASE_URL}/.well-known/mcp.json) — MCP server manifest. diff --git a/app/llms.txt/route.ts b/app/llms.txt/route.ts index 1f8cbcf..0814fbe 100644 --- a/app/llms.txt/route.ts +++ b/app/llms.txt/route.ts @@ -87,6 +87,11 @@ from major vendors, e.g. Notion's own Notion MCP; \`verified=true\` for Verified work, filtering on \`accessMethods\`, \`categories\` and \`official\`. To help a user choose and set up: +- One recommendation for what your user needs, and the next step to start using it: the + \`recommend\` MCP tool, or GET /api/recommend?need=. Each need + it names gets one pick, why it fits, the next step (the MCP config to paste when the + vendor's docs give one) and two alternatives. Picked by fixed matching rules, not a + model or paid placement. Write the need yourself; never include names, emails or phones. - Compare 2 or 3 listings, the facts that set each apart and one row per field: the \`compare_agents\` MCP tool, or GET /api/compare?a=&b=&c= - Listings that could stand in for one, each with why: the \`alternatives_to\` MCP tool, @@ -100,7 +105,7 @@ To help a user choose and set up: - Remote MCP (Streamable HTTP, no auth): https://agentswitchboard.dev/api/mcp - Stdio-only clients: npx -y mcp-remote https://agentswitchboard.dev/api/mcp - Server manifest: https://agentswitchboard.dev/.well-known/mcp.json -- Tools: search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle, submit_listing (files a public GitHub issue for human review; publishes nothing) +- Tools: search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle, recommend, submit_listing (files a public GitHub issue for human review; publishes nothing) - Connect it to Grok, Grok Bot, the xAI API, Claude, or ChatGPT: https://agentswitchboard.dev/connect - Plain REST search (no MCP handshake needed): GET /api/agents?q=&task=&category=&access=&official=&verified=&auth=&since=&sort=&limit=&offset=&page= - REST detail: GET /api/agents/{slug} @@ -110,6 +115,7 @@ To help a user choose and set up: - REST compare: GET /api/compare?a={slug}&b={slug}&c={slug} - REST alternatives: GET /api/agents/{slug}/alternatives - REST connect bundle: GET /api/bundle?items={slug},{slug} +- REST recommend: GET /api/recommend?need={the need, in a sentence} - OpenAPI: https://agentswitchboard.dev/openapi.json - Connector skill: https://agentswitchboard.dev/skill.md @@ -121,7 +127,7 @@ instead of scraping the DOM. No setup: they self-register on page load. - Declaration: https://agentswitchboard.dev/.well-known/webmcp.json - Tools: search_agents, get_agent, list_categories, compare_agents, alternatives_to, - connect_bundle. They call the REST API above, so answers and their order are the + connect_bundle, recommend. They call the REST API above, so answers and their order are the same as the remote MCP's; search and listing objects use the REST field names (see the OpenAPI document). diff --git a/app/page.tsx b/app/page.tsx index a59ec1c..e197377 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -260,7 +260,7 @@ export default async function HomePage() { connect your agent → agentswitchboard.dev/api/mcp - search_agents · compare_agents · alternatives_to · connect_bundle + recommend · search_agents · compare_agents · alternatives_to · connect_bundle
/api/mcp - MCP server · search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle + MCP server · search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle, recommend streamable-http · no auth
diff --git a/app/robots.ts b/app/robots.ts index a0eb63d..6eb47d3 100644 --- a/app/robots.ts +++ b/app/robots.ts @@ -40,8 +40,9 @@ export default function robots(): MetadataRoute.Robots { { userAgent: '*', allow: '/', - // Public catalog APIs must stay crawlable (Muse review fetches them). - disallow: ['/_next/', ...QUERY_PAGES, ...SHARE_CARDS], + // Public catalog APIs must stay crawlable (Muse review fetches them), + // except /api/recommend: every need is another URL, as on a query page. + disallow: ['/_next/', ...QUERY_PAGES, '/api/recommend', ...SHARE_CARDS], crawlDelay: 5, }, { userAgent: LINK_PREVIEW_BOTS, allow: '/', disallow: ['/_next/'] }, diff --git a/docs/API.md b/docs/API.md index 88e644d..314c7f3 100644 --- a/docs/API.md +++ b/docs/API.md @@ -14,6 +14,7 @@ need no authentication, are CORS-open, and read the same cached catalog** | **REST compare** | 2 or 3 listings side by side | `GET /api/compare` | | **REST alternatives** | listings that could stand in for one | `GET /api/agents/{slug}/alternatives` | | **REST connect bundle** | one MCP client config for several listings | `GET /api/bundle` | +| **REST recommend** | one pick and the next step for a need, in a sentence | `GET /api/recommend` | | **MCP server** | MCP clients (Grok, Claude, ChatGPT, Cursor, …) | `POST /api/mcp` | | **WebMCP** | agents viewing the page in a browser | `document.modelContext` | | **Catalog dump** | bulk / offline indexing | `GET /agents.json` (index) → `GET /catalog/{n}.json` | @@ -372,6 +373,60 @@ note; none found is a `400` with `{ "error": "no_listings", "message", "notes" } --- +## REST recommend — `GET /api/recommend` + +One recommendation for what a user needs, and the next step to start using it: +the [Operator](https://agentswitchboard.dev/operator)'s pick for each need the +request names. Write the need yourself from what the user said; never include +names, email addresses or phone numbers. Up to 300 characters are read. + +```bash +curl "https://agentswitchboard.dev/api/recommend?need=read+my+Gmail+and+query+Postgres" +``` + +```jsonc +{ + "request": "read my Gmail and query Postgres", + "answer": "For “read my Gmail”: Gmail MCP (https://agentswitchboard.dev/agents/gmail-mcp). Picked because it mentions “Gmail”. … Next step: Add its MCP server to your MCP client: https://developers.google.com/… Alternatives: …\nFor “query Postgres”: …", + "recommendations": [ + { + "need": "read my Gmail", + "task": { "slug": "send-and-read-email", "label": "send and read email", "url": "https://agentswitchboard.dev/tasks/send-and-read-email" }, + "pick": { /* …REST search fields and authType */ }, + "pickedBecause": "Picked because it mentions “Gmail”.", + "why": "…the pick's skill that does the task", + "unmet": [], + "nextStep": { + "how": "config", // config | guide | other, as in GET /api/bundle + "label": "Add its MCP server to your MCP client", + "url": "https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server", + "server": { "url": "https://gmailmcp.googleapis.com/mcp/v1" }, + "note": "Hosted by Google. You sign in with Google when you first connect." + }, + "alternatives": [ /* two listings, as pick */ ], + "fits": 24 + } + // …one per need + ], + "unmatched": [], // needs with no pick: { need, nearestTasks[] } + "stackUrl": "https://agentswitchboard.dev/stack?items=gmail-mcp,postgres-mcp-pro", // null for one pick + "operatorUrl": "https://agentswitchboard.dev/operator?q=read+my+Gmail+and+query+Postgres", + "basis": "Picked by the directory’s own matching rules, …", + "notes": [] +} +``` + +Each need is matched to one of the [tasks](https://agentswitchboard.dev/tasks); +among the task's listings, those that mention what the need names come first, +then Official ones, then the task's best fits. Saying MCP, CLI, API, browser +extension or official in the need narrows the pick. No model, so the same need +always gets the same answer, and placement never changes it: the catalog is read +in organic order and the answer carries no placement field. No need is a `400` +with `{ "error": "no_need" }`; a need that matches no task is a `404` with +`{ "error": "no_match", "message", "unmatched" }`, naming the closest tasks. + +--- + ## MCP server — `POST /api/mcp` Streamable HTTP MCP endpoint. Point any MCP client at it: @@ -396,9 +451,10 @@ Stdio-only clients: `npx -y mcp-remote https://agentswitchboard.dev/api/mcp` | `compare_agents` | `slugs` (2 or 3, required) | as [`GET /api/compare`](#rest-compare--get-apicompare): `{ title, url, intro, agents[], rows[], notes }` | | `alternatives_to` | `slug` (required), `limit?` (1–8) | as [`GET /api/agents/{slug}/alternatives`](#rest-alternatives--get-apiagentsslugalternatives) | | `connect_bundle` | `slugs` (1 to 10, required) | as [`GET /api/bundle`](#rest-connect-bundle--get-apibundle): `{ summary, stackUrl, config, claudeCode, setupPrompt, items[], notes }` | +| `recommend` | `need` (required) | as [`GET /api/recommend`](#rest-recommend--get-apirecommend): `{ request, answer, recommendations[], unmatched, stackUrl, operatorUrl, basis, notes }` | | `submit_listing` | `name`, `url`, `description` (required); `access?`, `category?`, `contact_email?` | `{ status, message, issueUrl?, existingSlug? }` | -All tools declare an `outputSchema` and return `structuredContent`. Results are organic: they never list featured listings first, and they leave out `featured` and any other placement field. The six +All tools declare an `outputSchema` and return `structuredContent`. Results are organic: they never list featured listings first, and they leave out `featured` and any other placement field. The seven read tools are annotated `readOnlyHint: true`, `destructiveHint: false`; `submit_listing` is `readOnlyHint: false`, `destructiveHint: true` (it posts a public issue the user can't take back), so clients ask before each call. Every tool also diff --git a/e2e/tests/60-machine-endpoints.spec.mjs b/e2e/tests/60-machine-endpoints.spec.mjs index 06b7052..334ab9b 100644 --- a/e2e/tests/60-machine-endpoints.spec.mjs +++ b/e2e/tests/60-machine-endpoints.spec.mjs @@ -14,7 +14,7 @@ const REAL_SLUG = 'playwright-mcp'; // status: "archived" in content/agents/*.json at HEAD const ARCHIVED_SLUGS = ['midjourney', 'blender-mcp', 'smithery', 'framelink', 'headlong']; const MCP_HEADERS = { ...H, 'content-type': 'application/json', accept: 'application/json, text/event-stream' }; -const READ_TOOLS = ['alternatives_to', 'compare_agents', 'connect_bundle', 'get_agent', 'list_categories', 'search_agents']; +const READ_TOOLS = ['alternatives_to', 'compare_agents', 'connect_bundle', 'get_agent', 'list_categories', 'recommend', 'search_agents']; const content = (file) => JSON.parse(fs.readFileSync(new URL(`../../content/${file}`, import.meta.url), 'utf8')); const CATALOG = (await loadCatalog(BASE, H)).agents; @@ -82,7 +82,7 @@ test.describe('text docs', () => { expect(body).toMatch(/^# Agent Switchboard/); expect(body).toContain('https://agentswitchboard.dev/api/mcp'); expect(body).toContain( - 'Tools: search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle, submit_listing' + 'Tools: search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle, recommend, submit_listing' ); }); @@ -417,6 +417,27 @@ test.describe('decision endpoints', () => { expect(body.error).toBe('no_listings'); expect(body.notes).toHaveLength(2); }); + + test('/api/recommend gives one pick per need, with the next step and two alternatives', async ({ request }) => { + const { body } = await getJson(request, '/api/recommend?need=read+my+Notion+and+query+Postgres'); + expect(body.recommendations.map((r) => r.task.slug)).toEqual(['work-in-notion-and-docs', 'query-a-database']); + for (const r of body.recommendations) { + expect(r.pick.slug).toBeTruthy(); + expect(['config', 'guide', 'other']).toContain(r.nextStep.how); + expect(r.nextStep.url).toMatch(/^https?:\/\//); + expect(r.alternatives.length).toBeLessThanOrEqual(2); + } + expect(body.answer.split('\n')).toHaveLength(2); + expect(body.stackUrl).toMatch(new RegExp(`^${ORIGIN}/stack\\?items=`)); + expect(JSON.stringify(body)).not.toMatch(/"(featured|sponsored|sponsorLabel|tier)"/); + }); + + test('/api/recommend refuses no need and a need no task matches', async ({ request }) => { + expect((await request.get('/api/recommend', { headers: H })).status()).toBe(400); + const res = await request.get('/api/recommend?need=make+me+a+sandwich', { headers: H }); + expect(res.status()).toBe(404); + expect((await res.json()).error).toBe('no_match'); + }); }); test.describe('crawler files', () => { @@ -495,7 +516,7 @@ test.describe('crawler files', () => { }); test.describe('manifests', () => { - test('/.well-known/mcp.json names the remote endpoint and the seven tools', async ({ request }) => { + test('/.well-known/mcp.json names the remote endpoint and the eight tools', async ({ request }) => { const { res, body } = await getJson(request, '/.well-known/mcp.json'); expect(res.headers()['content-type']).toMatch(/json/); expect(body.remotes).toContainEqual({ type: 'streamable-http', url: 'https://agentswitchboard.dev/api/mcp' }); @@ -557,7 +578,7 @@ test.describe('MCP server /api/mcp', () => { expect(body.result.instructions).toContain('connect_bundle'); }); - test('tools/list lists the six read tools and submit_listing', async ({ request }) => { + test('tools/list lists the seven read tools and submit_listing', async ({ request }) => { const body = await mcp(request, 'tools/list'); expect(body.error).toBeUndefined(); const names = body.result.tools.map((t) => t.name).sort(); diff --git a/lib/decide.test.ts b/lib/decide.test.ts index 269078f..da87384 100644 --- a/lib/decide.test.ts +++ b/lib/decide.test.ts @@ -1,11 +1,16 @@ import { describe, expect, it } from 'vitest'; +import { bundleItem } from './bundle'; import { getEveryAgent } from './catalog'; import { compareRows, compareSuggestions, compareTitle, curatedComparisons, factLines, pairPath } from './compare'; import { compareHref } from './compare-link'; -import { alternativesDecision, bundleDecision, compareDecision } from './decide'; +import { alternativesDecision, bundleDecision, compareDecision, RECOMMEND_BASIS, recommendDecision } from './decide'; import { BASE_URL } from './env'; +import { putThrough } from './operator'; +import { organicOrder } from './organic'; import { alternativeWhy, getAlternatives, MAX_ALTERNATIVES, MIN_ALTERNATIVES } from './related'; +import { operatorHref } from './request-parts'; import { MY_STACK_MAX, stackHref } from './stack-link'; +import { getTasks } from './tasks'; import type { Agent } from './types'; function listing(slug: string, overrides: Partial = {}): Agent { @@ -256,3 +261,43 @@ describe('bundleDecision', () => { }); }); }); + +describe('recommendDecision', () => { + const organic = async () => organicOrder(await getEveryAgent()); + + it("gives the Operator's pick for each need, with why, the next step and two alternatives", async () => { + const catalog = await organic(); + const need = 'read my Notion, file Linear tickets, ping me on Slack'; + const put = putThrough(need, getTasks(), catalog); + const answer = body(recommendDecision(need, getTasks(), catalog)); + expect(answer.recommendations.map((r) => r.pick.slug)).toEqual(put.parts.map((p) => p.pick!.slug)); + expect(answer.recommendations.map((r) => r.alternatives.map((a) => a.slug))).toEqual( + put.parts.map((p) => p.alternatives.map((a) => a.slug)) + ); + expect(answer.recommendations.map((r) => r.task.slug)).toEqual(put.parts.map((p) => p.task!.slug)); + expect(answer.stackUrl).toBe(`${BASE_URL}${stackHref(put.stack.map((a) => a.slug))}`); + expect(answer.operatorUrl).toBe(`${BASE_URL}${operatorHref(need)}`); + expect(answer.basis).toBe(RECOMMEND_BASIS); + expect(answer.unmatched).toEqual([]); + expect(answer.answer.split('\n')).toHaveLength(put.parts.length); + expect(answer.answer).toContain(`${answer.recommendations[0].pick.name} (${answer.recommendations[0].pick.url})`); + }); + + it("makes the next step the pick's MCP config when its docs give one, else its guide or docs", async () => { + const catalog = await organic(); + const answer = body(recommendDecision('read my Gmail, query Postgres, write and fix code', getTasks(), catalog)); + for (const r of answer.recommendations) { + const item = bundleItem(catalog.find((a) => a.slug === r.pick.slug)!); + expect(r.nextStep).toMatchObject({ how: item.how, url: item.docsUrl, server: item.server, note: item.note }); + } + expect(answer.recommendations.some((r) => r.nextStep.how === 'config' && r.nextStep.server)).toBe(true); + }); + + it('refuses no need, and a need that matches no task, with the closest tasks', async () => { + const catalog = await organic(); + expect(recommendDecision(' ', getTasks(), catalog)).toMatchObject({ ok: false, status: 400, error: 'no_need' }); + const none = recommendDecision('make me a sandwich', getTasks(), catalog); + expect(none).toMatchObject({ ok: false, status: 404, error: 'no_match' }); + expect(!none.ok && none.message).toMatch(/^No task in the directory matches "make me a sandwich", so there is no pick\./); + }); +}); diff --git a/lib/decide.ts b/lib/decide.ts index c04966d..6fea513 100644 --- a/lib/decide.ts +++ b/lib/decide.ts @@ -1,12 +1,13 @@ /** * The decision tools' answers as data, for GET /api/compare, - * /api/agents/{slug}/alternatives and /api/bundle, and the MCP tools - * compare_agents, alternatives_to and connect_bundle. Each is built from the - * same functions as the site's own page (/compare, an alternatives page, a - * stack page), so an assistant says what a visitor sees. + * /api/agents/{slug}/alternatives, /api/bundle and /api/recommend, and the MCP + * tools compare_agents, alternatives_to, connect_bundle and recommend. Each is + * built from the same functions as the site's own page (/compare, an + * alternatives page, a stack page, the Operator), so an assistant says what a + * visitor sees. */ -import { bundleNotes, bundleSummary, connectBundle } from './bundle'; +import { bundleItem, bundleNotes, bundleSummary, connectBundle, type BundleHow } from './bundle'; import { compareRows, compareSuggestions, @@ -20,12 +21,15 @@ import { } from './compare'; import { COMPARE_MAX, compareHref } from './compare-link'; import { BASE_URL } from './env'; +import { pickedBecause, putThrough } from './operator'; import { decisionAgent } from './public-api'; import { alternativeWhy, getAlternatives, MAX_ALTERNATIVES, MIN_ALTERNATIVES } from './related'; +import { operatorHref, PARTS_MAX, REQUEST_MAX } from './request-parts'; import { listedAgents, sharedStack } from './shared-stack'; import { stackHref } from './stack-link'; +import type { Task } from './tasks'; import type { Agent } from './types'; -import { pluralize } from './utils'; +import { joinList, pluralize } from './utils'; /** Why a decision tool has no answer: the HTTP status, an error code and a message, plus anything that helps the next call. */ export interface Refusal { @@ -171,3 +175,107 @@ export function bundleDecision( extra: { notes }, }; } + +// ── recommend ─────────────────────────────────────────────────────── + +/** How a recommendation is picked, said with every answer. */ +export const RECOMMEND_BASIS = + 'Picked by the directory’s own matching rules, the same for every caller and with no model: each need is matched to one of the directory’s tasks, ' + + 'then the listings for that task that mention what the need names come first (a product, a service), then Official ones, then the task’s best fits. ' + + 'Asking for an MCP server, a CLI, an API, a browser extension or Official narrows the pick. Paid placement never changes it.'; + +const NEXT_STEP_LABEL: Record = { + config: 'Add its MCP server to your MCP client', + guide: 'Set up its MCP server from its guide', + other: 'Start from its setup docs', +}; + +function nextStep(agent: Agent) { + const item = bundleItem(agent); + return { how: item.how, label: NEXT_STEP_LABEL[item.how], url: item.docsUrl, server: item.server, note: item.note }; +} + +const taskRef = (task: Task) => ({ slug: task.slug, label: task.label, url: `${BASE_URL}/tasks/${task.slug}` }); + +function answerLine(r: RecommendBody['recommendations'][number]): string { + const alternatives = r.alternatives.length > 0 ? ` Alternatives: ${joinList(r.alternatives.map((a) => a.name))}.` : ''; + const because = r.pickedBecause.startsWith('Picked') ? r.pickedBecause : 'The task’s best fit.'; + const why = r.why ? ` ${r.why}${/[.!?]$/.test(r.why) ? '' : '.'}` : ''; + return ( + `For “${r.need}”: ${r.pick.name} (${r.pick.url}). ${because}${why} ` + + `Next step: ${r.nextStep.label}: ${r.nextStep.url}.${alternatives}` + ); +} + +function recommendBody(need: unknown, tasks: Task[], catalog: Agent[]) { + const put = putThrough(need, tasks, catalog); + const recommendations = put.parts.flatMap((part) => + part.task && part.pick + ? [ + { + need: part.text, + task: taskRef(part.task), + pick: decisionAgent(part.pick), + pickedBecause: pickedBecause(part), + why: part.why, + unmet: part.unmet, + nextStep: nextStep(part.pick), + alternatives: part.alternatives.map(decisionAgent), + fits: part.fits, + }, + ] + : [] + ); + const unmatched = put.parts + .filter((part) => !part.task || !part.pick) + .map((part) => ({ need: part.text, nearestTasks: (part.task ? [part.task] : part.nearest).map(taskRef) })); + const notes = [ + ...(put.cut ? [`The request was cut at ${REQUEST_MAX} characters.`] : []), + ...(put.extra > 0 ? [`Only the first ${PARTS_MAX} needs were read; ${put.extra} more were left out.`] : []), + ]; + const body = { + request: put.request, + answer: '', + recommendations, + unmatched, + stackUrl: put.stack.length > 1 ? `${BASE_URL}${stackHref(put.stack.map((a) => a.slug))}` : null, + operatorUrl: `${BASE_URL}${operatorHref(put.request)}`, + basis: RECOMMEND_BASIS, + notes, + }; + return body; +} + +export type RecommendBody = ReturnType; + +/** + * One pick for each need in `need` (the user's words: "query Postgres and + * send email"), with why, the next step to start using it and two + * alternatives, as the Operator puts it through. `catalog` must be in organic + * order (lib/organic.ts): ties go to the catalog's order. + */ +export function recommendDecision(need: unknown, tasks: Task[], catalog: Agent[]): Decision { + const body = recommendBody(need, tasks, catalog); + if (!body.request) { + return { + ok: false, + status: 400, + error: 'no_need', + message: 'Say what your user needs in a sentence, e.g. "query Postgres and send email".', + }; + } + if (body.recommendations.length === 0) { + const nearest = [...new Map(body.unmatched.flatMap((u) => u.nearestTasks).map((t) => [t.slug, t])).values()]; + const closest = nearest.length > 0 ? ` The closest tasks: ${nearest.map((t) => t.slug).join(', ')}.` : ''; + return { + ok: false, + status: 404, + error: 'no_match', + message: `No task in the directory matches "${body.request}", so there is no pick.${closest} Say it another way, or search the directory.`, + extra: { unmatched: body.unmatched }, + }; + } + const left = body.unmatched.map((u) => `No pick for “${u.need}”: no task in the directory matches it.`); + body.answer = [...body.recommendations.map(answerLine), ...left].join('\n'); + return { ok: true, body }; +} diff --git a/lib/mcp-tools.ts b/lib/mcp-tools.ts index 89b2ec2..cde2cc3 100644 --- a/lib/mcp-tools.ts +++ b/lib/mcp-tools.ts @@ -11,5 +11,6 @@ export const MCP_TOOL_NAMES: ReadonlySet = new Set([ 'compare_agents', 'alternatives_to', 'connect_bundle', + 'recommend', 'submit_listing', ]); diff --git a/lib/public-api.ts b/lib/public-api.ts index 098ea0e..77e560b 100644 --- a/lib/public-api.ts +++ b/lib/public-api.ts @@ -129,6 +129,17 @@ export const CONNECT_BUNDLE_DESCRIPTION = 'Also returns a claude mcp add command for each server in the config, for Claude Code, and the /stack link for the listings. ' + "Nothing is guessed: every address and command is copied from the vendor's docs, as on the listing's page."; +export const RECOMMEND_DESCRIPTION = + 'One recommendation for what your user needs, and the next step to start using it, as the site\'s Operator (/operator) picks it. ' + + 'Pass the need in a sentence you write yourself, e.g. "query Postgres and send email": each need it names gets one pick, why it fits, ' + + 'the next step (the MCP client config to paste when the vendor\'s docs give one, else its setup guide or docs) and two alternatives; ' + + 'two or more picks also come with a /stack link. Name a product to prefer the listings that mention it; say MCP, CLI, API, browser extension or official to narrow the pick. ' + + 'Picked by fixed matching rules, not a model, so the same need always gets the same answer. A need that matches no task is refused with the closest tasks. ' + + 'Never include names, email addresses or phone numbers.'; + +export const RECOMMEND_NEED_INPUT = + "What the user needs, in a sentence or two, e.g. \"query Postgres and send email\" (up to 300 characters are read)"; + /** * A listing in a decision tool's answer: the search-result fields and its auth * type. The MCP server returns these too, and connector directories reject diff --git a/lib/webmcp-tools.ts b/lib/webmcp-tools.ts index 7d9fc13..1696583 100644 --- a/lib/webmcp-tools.ts +++ b/lib/webmcp-tools.ts @@ -1,11 +1,11 @@ /** * The WebMCP tools that components/WebMcp.tsx registers on `document.modelContext`: - * search_agents, get_agent, list_categories, compare_agents, alternatives_to and - * connect_bundle. + * search_agents, get_agent, list_categories, compare_agents, alternatives_to, + * connect_bundle and recommend. * * Each tool calls the public REST API (/api/agents, /api/agents/{slug}, * /api/categories, /api/compare, /api/agents/{slug}/alternatives, - * /api/bundle). That runs the same code as the remote MCP server at /api/mcp, + * /api/bundle, /api/recommend). That runs the same code as the remote MCP server at /api/mcp, * so answers and their order are the same; search and listing objects use the * REST field names (see /openapi.json), which differ from the remote MCP's in * a few places. Results are organic, as on the remote MCP (lib/organic.ts): @@ -30,6 +30,8 @@ import { CONNECT_BUNDLE_DESCRIPTION, MAX_LIMIT, OFFICIAL_DEFINITION, + RECOMMEND_DESCRIPTION, + RECOMMEND_NEED_INPUT, SINCE_INPUT, TASK_INPUT, VERIFIED_INPUT, @@ -489,4 +491,59 @@ export const WEBMCP_TOOLS: WebMcpTool[] = [ return decide('connect_bundle', `/api/bundle?items=${items}`); }), }, + { + name: 'recommend', + description: RECOMMEND_DESCRIPTION, + inputSchema: { + type: 'object', + properties: { + need: { type: 'string', maxLength: 2000, description: RECOMMEND_NEED_INPUT }, + }, + required: ['need'], + }, + // GET /api/recommend (lib/decide.ts recommendDecision). + outputSchema: { + type: 'object', + required: ['request', 'answer', 'recommendations', 'unmatched', 'stackUrl', 'operatorUrl', 'basis', 'notes'], + properties: { + request: { type: 'string', description: 'The need as read' }, + answer: { + type: 'string', + description: 'The recommendations in plain sentences, one line per need, ready to tell the user', + }, + recommendations: { + type: 'array', + items: { + type: 'object', + properties: { + need: { type: 'string', description: "The user's words for this need" }, + task: { type: 'object', description: 'The directory task it matched: slug, label, url' }, + pick: { type: 'object', properties: decisionProps }, + pickedBecause: { type: 'string' }, + why: { type: ['string', 'null'], description: 'The skill of the pick that does the task' }, + unmet: { ...stringList, description: 'What the need asked for that no listing for the task has' }, + nextStep: { + type: 'object', + description: + 'how (config: paste server into an MCP client; guide: an MCP server to set up from url; other: no MCP server, start from url), label, url, server, note', + }, + alternatives: { type: 'array', items: { type: 'object', properties: decisionProps } }, + fits: { type: 'integer', description: 'How many listings do the task' }, + }, + }, + }, + unmatched: { type: 'array', description: 'Needs with no pick, and the tasks closest to them' }, + stackUrl: { type: ['string', 'null'], description: 'Two or more picks as a shared stack on the site' }, + operatorUrl: { type: 'string', description: 'The same request on the site' }, + basis: { type: 'string', description: 'How the pick is made' }, + notes: stringList, + }, + }, + annotations: { readOnlyHint: true }, + execute: tool('recommend', async (input) => { + const need = str(input.need); + if (!need) return asError('recommend needs what the user needs, in a sentence, e.g. "query Postgres and send email".'); + return decide('recommend', `/api/recommend?need=${encodeURIComponent(need.slice(0, 2000))}`); + }), + }, ]; diff --git a/plugins/agent-switchboard/README.md b/plugins/agent-switchboard/README.md index de9f60a..6a5daa5 100644 --- a/plugins/agent-switchboard/README.md +++ b/plugins/agent-switchboard/README.md @@ -18,6 +18,7 @@ no account, API key or configuration. In approval prompts it appears as | `compare_agents` | Two or three listings side by side | | `alternatives_to` | Listings that could stand in for one, with what each has in common | | `connect_bundle` | One MCP client config for up to 10 listings, and how to connect the rest | +| `recommend` | One pick for what you need, said in a sentence, with why it fits, the next step and two alternatives | | `submit_listing` | Suggests a missing product by filing a public GitHub issue for human review. It publishes nothing. It is marked destructive, so clients ask before calling it | Every tool except `submit_listing` is read-only. diff --git a/public/.well-known/mcp.json b/public/.well-known/mcp.json index 834a435..ee0336b 100644 --- a/public/.well-known/mcp.json +++ b/public/.well-known/mcp.json @@ -2,7 +2,7 @@ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", "name": "io.github.assafbar2/agentswitchboard", "description": "Search a curated directory of AI agents, MCP servers, and agentic tools, and suggest new listings. Use it to find out whether an agent already exists for a job, which access methods it offers (API, MCP, CLI, browser extension), and where its homepage is.", - "version": "1.8.0", + "version": "1.9.0", "websiteUrl": "https://agentswitchboard.dev", "repository": { "url": "https://github.com/assafbar2/agentswitchboard.dev", @@ -203,6 +203,26 @@ "$schema": "http://json-schema.org/draft-07/schema#" } }, + { + "name": "recommend", + "title": "Recommend", + "description": "One recommendation for what your user needs, and the next step to start using it, as the site's Operator (/operator) picks it. Pass the need in a sentence you write yourself, e.g. \"query Postgres and send email\": each need it names gets one pick, why it fits, the next step (the MCP client config to paste when the vendor's docs give one, else its setup guide or docs) and two alternatives; two or more picks also come with a /stack link. Name a product to prefer the listings that mention it; say MCP, CLI, API, browser extension or official to narrow the pick. Picked by fixed matching rules, not a model, so the same need always gets the same answer. A need that matches no task is refused with the closest tasks. Never include names, email addresses or phone numbers.", + "inputSchema": { + "type": "object", + "properties": { + "need": { + "type": "string", + "maxLength": 2000, + "description": "What the user needs, in a sentence or two, e.g. \"query Postgres and send email\" (up to 300 characters are read)" + } + }, + "required": [ + "need" + ], + "additionalProperties": false, + "$schema": "http://json-schema.org/draft-07/schema#" + } + }, { "name": "submit_listing", "title": "Submit a Listing", diff --git a/public/.well-known/webmcp.json b/public/.well-known/webmcp.json index 8a95dff..4939b3b 100644 --- a/public/.well-known/webmcp.json +++ b/public/.well-known/webmcp.json @@ -1,7 +1,7 @@ { "name": "io.github.assafbar2/agentswitchboard", - "description": "In-browser WebMCP tools for Agent Switchboard, registered on document.modelContext when the page loads. Same six read tools as the remote MCP server at /api/mcp: search_agents, get_agent, list_categories, compare_agents, alternatives_to and connect_bundle. They call the public REST API (/api/agents, /api/agents/{slug}, /api/categories, /api/compare, /api/agents/{slug}/alternatives, /api/bundle), so answers and their order are the same as the remote server's; result objects use the REST field names (see /openapi.json).", - "version": "1.8.0", + "description": "In-browser WebMCP tools for Agent Switchboard, registered on document.modelContext when the page loads. Same seven read tools as the remote MCP server at /api/mcp: search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle and recommend. They call the public REST API (/api/agents, /api/agents/{slug}, /api/categories, /api/compare, /api/agents/{slug}/alternatives, /api/bundle, /api/recommend), so answers and their order are the same as the remote server's; result objects use the REST field names (see /openapi.json).", + "version": "1.9.0", "websiteUrl": "https://agentswitchboard.dev", "surface": "document.modelContext", "polyfill": "@mcp-b/webmcp-polyfill", @@ -1015,6 +1015,218 @@ } } } + }, + { + "name": "recommend", + "description": "One recommendation for what your user needs, and the next step to start using it, as the site's Operator (/operator) picks it. Pass the need in a sentence you write yourself, e.g. \"query Postgres and send email\": each need it names gets one pick, why it fits, the next step (the MCP client config to paste when the vendor's docs give one, else its setup guide or docs) and two alternatives; two or more picks also come with a /stack link. Name a product to prefer the listings that mention it; say MCP, CLI, API, browser extension or official to narrow the pick. Picked by fixed matching rules, not a model, so the same need always gets the same answer. A need that matches no task is refused with the closest tasks. Never include names, email addresses or phone numbers.", + "annotations": { + "readOnlyHint": true + }, + "inputSchema": { + "type": "object", + "properties": { + "need": { + "type": "string", + "maxLength": 2000, + "description": "What the user needs, in a sentence or two, e.g. \"query Postgres and send email\" (up to 300 characters are read)" + } + }, + "required": [ + "need" + ] + }, + "outputSchema": { + "type": "object", + "required": [ + "request", + "answer", + "recommendations", + "unmatched", + "stackUrl", + "operatorUrl", + "basis", + "notes" + ], + "properties": { + "request": { + "type": "string", + "description": "The need as read" + }, + "answer": { + "type": "string", + "description": "The recommendations in plain sentences, one line per need, ready to tell the user" + }, + "recommendations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "need": { + "type": "string", + "description": "The user's words for this need" + }, + "task": { + "type": "object", + "description": "The directory task it matched: slug, label, url" + }, + "pick": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "url": { + "type": "string" + }, + "iconUrl": { + "type": [ + "string", + "null" + ], + "description": "Absolute URL of the listing's 128px PNG icon, served by Agent Switchboard; null when it has none" + }, + "description": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "categories": { + "type": "array", + "items": { + "type": "string" + } + }, + "accessMethods": { + "type": "array", + "items": { + "type": "string" + } + }, + "verified": { + "type": "boolean", + "description": "Verified: we checked it works — its URLs load and its declared access (API, MCP, CLI or extension) responds. Re-checked monthly; the label drops if it stops working." + }, + "official": { + "type": "boolean", + "description": "Official: a first-party listing, published by the company behind the product under its own domain or GitHub org (e.g. Notion's own Notion MCP, not a community build), where that company is a major vendor (publicly traded, a frontier AI lab, or valued around $1B+). It records who publishes the product, not a paid placement, and is separate from Verified." + }, + "authType": { + "type": "string" + } + } + }, + "pickedBecause": { + "type": "string" + }, + "why": { + "type": [ + "string", + "null" + ], + "description": "The skill of the pick that does the task" + }, + "unmet": { + "type": "array", + "items": { + "type": "string" + }, + "description": "What the need asked for that no listing for the task has" + }, + "nextStep": { + "type": "object", + "description": "how (config: paste server into an MCP client; guide: an MCP server to set up from url; other: no MCP server, start from url), label, url, server, note" + }, + "alternatives": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "url": { + "type": "string" + }, + "iconUrl": { + "type": [ + "string", + "null" + ], + "description": "Absolute URL of the listing's 128px PNG icon, served by Agent Switchboard; null when it has none" + }, + "description": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "categories": { + "type": "array", + "items": { + "type": "string" + } + }, + "accessMethods": { + "type": "array", + "items": { + "type": "string" + } + }, + "verified": { + "type": "boolean", + "description": "Verified: we checked it works — its URLs load and its declared access (API, MCP, CLI or extension) responds. Re-checked monthly; the label drops if it stops working." + }, + "official": { + "type": "boolean", + "description": "Official: a first-party listing, published by the company behind the product under its own domain or GitHub org (e.g. Notion's own Notion MCP, not a community build), where that company is a major vendor (publicly traded, a frontier AI lab, or valued around $1B+). It records who publishes the product, not a paid placement, and is separate from Verified." + }, + "authType": { + "type": "string" + } + } + } + }, + "fits": { + "type": "integer", + "description": "How many listings do the task" + } + } + } + }, + "unmatched": { + "type": "array", + "description": "Needs with no pick, and the tasks closest to them" + }, + "stackUrl": { + "type": [ + "string", + "null" + ], + "description": "Two or more picks as a shared stack on the site" + }, + "operatorUrl": { + "type": "string", + "description": "The same request on the site" + }, + "basis": { + "type": "string", + "description": "How the pick is made" + }, + "notes": { + "type": "array", + "items": { + "type": "string" + } + } + } + } } ] } diff --git a/public/openapi.json b/public/openapi.json index 5ff2275..24f26e5 100644 --- a/public/openapi.json +++ b/public/openapi.json @@ -444,6 +444,49 @@ } } }, + "/api/recommend": { + "get": { + "operationId": "recommend", + "summary": "One pick and the next step for what a user needs", + "description": "One recommendation for what a user needs, and the next step to start using it, as the site's Operator (/operator) picks it. Each need the request names gets one pick, why it fits, the next step (the MCP client config to paste when the vendor's docs give one, else its setup guide or docs) and two alternatives; two or more picks also come with a /stack link. Picked by fixed matching rules, not a model: each need is matched to a task, then the task's listings that mention what the need names come first, then Official ones, then the task's best fits. Saying MCP, CLI, API, browser extension or official in the need narrows the pick. The catalog is read in organic order and the answer carries no placement field. Write the need yourself; never include names, email addresses or phone numbers.", + "tags": ["catalog"], + "parameters": [ + { + "name": "need", + "in": "query", + "required": true, + "description": "What the user needs, in a sentence or two. Up to 300 characters are read.", + "schema": { "type": "string", "examples": ["read my Gmail and query Postgres"] } + } + ], + "responses": { + "200": { + "description": "The recommendations.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/RecommendResult" } + } + } + }, + "400": { + "description": "No need given (`error: \"no_need\"`).", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "404": { + "description": "No task in the directory matches the need (`error: \"no_match\"`); `unmatched` names the closest tasks.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + } + } + } + }, "/agents.json": { "get": { "operationId": "listAgents", @@ -494,7 +537,7 @@ "post": { "operationId": "mcpTransport", "summary": "Model Context Protocol endpoint (streamable HTTP)", - "description": "Speaks MCP over streamable HTTP. Exposes seven tools: `search_agents`, `get_agent`, `list_categories`, `compare_agents`, `alternatives_to`, `connect_bundle`, and `submit_listing`, which files a listing suggestion for human review. This is a JSON-RPC transport, not a REST resource. REST clients should call /api/agents, /api/compare, /api/agents/{slug}/alternatives and /api/bundle instead.", + "description": "Speaks MCP over streamable HTTP. Exposes eight tools: `search_agents`, `get_agent`, `list_categories`, `compare_agents`, `alternatives_to`, `connect_bundle`, `recommend`, and `submit_listing`, which files a listing suggestion for human review. This is a JSON-RPC transport, not a REST resource. REST clients should call /api/agents, /api/compare, /api/agents/{slug}/alternatives, /api/bundle and /api/recommend instead.", "tags": ["mcp"], "requestBody": { "required": true, @@ -1171,6 +1214,65 @@ } ] }, + "RecommendResult": { + "type": "object", + "required": ["request", "answer", "recommendations", "unmatched", "stackUrl", "operatorUrl", "basis", "notes"], + "properties": { + "request": { "type": "string", "description": "The need as read." }, + "answer": { "type": "string", "description": "The recommendations in plain sentences, one line per need, ready to tell the user." }, + "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } }, + "unmatched": { + "type": "array", + "description": "Needs with no pick, and the tasks closest to them.", + "items": { + "type": "object", + "required": ["need", "nearestTasks"], + "properties": { + "need": { "type": "string" }, + "nearestTasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRef" } } + } + } + }, + "stackUrl": { "type": ["string", "null"], "format": "uri", "description": "Two or more picks as a shared stack on Agent Switchboard; null for one." }, + "operatorUrl": { "type": "string", "format": "uri", "description": "The same request on the site's Operator page." }, + "basis": { "type": "string", "description": "How the pick is made." }, + "notes": { "type": "array", "items": { "type": "string" }, "description": "What of the request was not read." } + } + }, + "Recommendation": { + "type": "object", + "required": ["need", "task", "pick", "pickedBecause", "why", "unmet", "nextStep", "alternatives", "fits"], + "properties": { + "need": { "type": "string", "description": "The user's words for this need." }, + "task": { "$ref": "#/components/schemas/TaskRef" }, + "pick": { "$ref": "#/components/schemas/DecisionAgent" }, + "pickedBecause": { "type": "string", "examples": ["Picked because it mentions “Gmail”."] }, + "why": { "type": ["string", "null"], "description": "The pick's skill that does the task." }, + "unmet": { "type": "array", "items": { "type": "string" }, "description": "What the need asked for that no listing for the task has." }, + "nextStep": { + "type": "object", + "required": ["how", "label", "url", "server", "note"], + "properties": { + "how": { "type": "string", "enum": ["config", "guide", "other"], "description": "config: paste server into an MCP client; guide: an MCP server to set up from url; other: no MCP server, start from url." }, + "label": { "type": "string", "examples": ["Add its MCP server to your MCP client"] }, + "url": { "type": "string", "format": "uri", "description": "The vendor's setup instructions." }, + "server": { "oneOf": [{ "$ref": "#/components/schemas/McpServer" }, { "type": "null" }], "description": "With how config: its entry for mcpServers." }, + "note": { "type": "string", "description": "How it connects." } + } + }, + "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionAgent" } }, + "fits": { "type": "integer", "description": "How many listings do the task." } + } + }, + "TaskRef": { + "type": "object", + "required": ["slug", "label", "url"], + "properties": { + "slug": { "type": "string", "examples": ["query-a-database"] }, + "label": { "type": "string", "examples": ["query a database"] }, + "url": { "type": "string", "format": "uri" } + } + }, "Error": { "type": "object", "required": ["error", "message"], diff --git a/public/skill.md b/public/skill.md index c7d8e8f..b71e443 100644 --- a/public/skill.md +++ b/public/skill.md @@ -39,6 +39,7 @@ Prefer REST. OpenAPI: https://agentswitchboard.dev/openapi.json 6. `GET /api/compare?a={slug}&b={slug}` (add `&c={slug}` for a third) to put listings side by side: what sets each apart (`setsApart`), then one row per field with each listing's value by slug. 7. `GET /api/agents/{slug}/alternatives` for listings that could stand in for one, strongest first, each with a `why` line. 8. `GET /api/bundle?items={slug},{slug}` (up to 10) for one MCP client config to paste (`config`, `{"mcpServers": …}`), and how each listing connects (`items[].how` and `note`). +9. `GET /api/recommend?need={the need, in a sentence}` when the user wants one tool for a job: one pick for each need it names (`recommendations[].pick`), why it fits, the next step to start using it (`nextStep`: the MCP config to paste when the vendor's docs give one, else its guide or docs) and two alternatives. `answer` says it in plain sentences. Write the need yourself from what the user said; never include names, emails or phone numbers. A need that matches no task is HTTP 404 `{ "error": "no_match" }` with the closest tasks. Query notes: @@ -54,7 +55,7 @@ Unknown slugs return HTTP 404 `{ "error": "not_found", "message": "…" }`. Sear Bulk dump: `GET /agents.json` is an index linking pages of up to 50 listings (`/catalog/1.json` and on, each with `next`). Prefer search for user questions. -Optional MCP (only if the client speaks MCP, not required): `POST https://agentswitchboard.dev/api/mcp` with tools `search_agents` (the same filters, `since` and `sort`), `get_agent`, `list_categories`, `compare_agents`, `alternatives_to` and `connect_bundle` (the same answers as the compare, alternatives and bundle endpoints). +Optional MCP (only if the client speaks MCP, not required): `POST https://agentswitchboard.dev/api/mcp` with tools `search_agents` (the same filters, `since` and `sort`), `get_agent`, `list_categories`, `compare_agents`, `alternatives_to`, `connect_bundle` and `recommend` (the same answers as the compare, alternatives, bundle and recommend endpoints). ## How to answer the user diff --git a/scripts/mcp-smoke.mjs b/scripts/mcp-smoke.mjs index 9316713..997f4f6 100644 --- a/scripts/mcp-smoke.mjs +++ b/scripts/mcp-smoke.mjs @@ -32,7 +32,7 @@ const { tools } = await client.listTools(); const names = tools.map((t) => t.name).sort(); check( 'tools/list', - names.join(',') === 'alternatives_to,compare_agents,connect_bundle,get_agent,list_categories,search_agents,submit_listing', + names.join(',') === 'alternatives_to,compare_agents,connect_bundle,get_agent,list_categories,recommend,search_agents,submit_listing', names.join(', ') ); for (const t of tools) { @@ -124,6 +124,10 @@ const bundle = await client.callTool({ const servers = Object.keys(bundle.structuredContent?.config?.mcpServers ?? {}); check('connect_bundle', servers.includes('linear') && servers.includes('playwright-mcp'), bundle.structuredContent?.summary); +const recommend = await client.callTool({ name: 'recommend', arguments: { need: 'read my Notion and query Postgres' } }); +const picks = recommend.structuredContent?.recommendations ?? []; +check('recommend', picks.length === 2 && picks.every((r) => r.pick?.slug && r.nextStep?.url), picks.map((r) => r.pick?.slug).join(', ')); + const dup = await client.callTool({ name: 'submit_listing', arguments: { diff --git a/tests/organic-surfaces.test.ts b/tests/organic-surfaces.test.ts index 50664b0..85fc41a 100644 --- a/tests/organic-surfaces.test.ts +++ b/tests/organic-surfaces.test.ts @@ -47,6 +47,7 @@ const alternativesRoute = await import('@/app/api/agents/[slug]/alternatives/rou const categoriesRoute = await import('@/app/api/categories/route'); const compareRoute = await import('@/app/api/compare/route'); const bundleRoute = await import('@/app/api/bundle/route'); +const recommendRoute = await import('@/app/api/recommend/route'); const PLACEMENT_KEY = /^(featured|featuredUntil|sponsored|sponsorLabel|tier)$/; @@ -78,6 +79,10 @@ const CALLS: [string, Record][] = [ ['alternatives_to', { slug: 'pinecone' }], ['alternatives_to', { slug: 'playwright-mcp' }], ['connect_bundle', { slugs: ['playwright-mcp', 'github-mcp', 'notion-mcp', 'cursor'] }], + ['recommend', { need: 'read my Notion, file Linear tickets, ping me on Slack' }], + ['recommend', { need: 'query Postgres and send email' }], + ['recommend', { need: 'write and fix code' }], + ['recommend', { need: 'an official MCP to browse the web' }], ]; let rpcId = 0; @@ -119,6 +124,7 @@ async function restFetch(input: string | URL | Request): Promise { if (p === '/api/categories') return categoriesRoute.GET(req); if (p === '/api/compare') return compareRoute.GET(req); if (p === '/api/bundle') return bundleRoute.GET(req); + if (p === '/api/recommend') return recommendRoute.GET(req); throw new Error(`WebMCP fetched an unexpected path: ${p}`); } @@ -173,7 +179,7 @@ describe('AI-assistant surfaces are organic', () => { it('the MCP tool list names no placement field and promises no placement order', async () => { const { result } = await rpc('tools/list'); - expect(result.tools).toHaveLength(7); + expect(result.tools).toHaveLength(8); // The logger's allow-list of tool names (lib/mcp-tools.ts) matches what is registered. expect(result.tools.map((t: { name: string }) => t.name).sort()).toEqual([...MCP_TOOL_NAMES].sort()); for (const tool of result.tools) { @@ -186,7 +192,7 @@ describe('AI-assistant surfaces are organic', () => { it('the WebMCP tool declarations name no placement field and promise no placement order', () => { expect(WEBMCP_TOOLS.map((t) => t.name).sort()).toEqual( - ['alternatives_to', 'compare_agents', 'connect_bundle', 'get_agent', 'list_categories', 'search_agents'] + ['alternatives_to', 'compare_agents', 'connect_bundle', 'get_agent', 'list_categories', 'recommend', 'search_agents'] ); for (const tool of WEBMCP_TOOLS) { expect(JSON.stringify(tool.outputSchema ?? {}), tool.name).not.toMatch(/"(featured|featuredUntil|sponsored|sponsorLabel|tier)"/); From edb53525f53f90964cdac84ba7416bc0fa44bc82 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 13 Nov 2026 14:19:59 +0000 Subject: [PATCH 2/2] Release 2.10.2: recommend Co-authored-by: assaf.barnir --- CHANGELOG.md | 11 +++++++++++ package-lock.json | 4 ++-- package.json | 2 +- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e93c98..db30a40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ Every release of [Agent Switchboard](https://agentswitchboard.dev), newest first Versions follow MAJOR.MINOR.PATCH: a minor version adds features, a patch fixes or adjusts. Versions before 2.2.0 were assigned afterwards, reconstructed from the git history. "Directory" lines summarize catalog changes since the previous release; the full log of every listing added, updated or removed is on [/changelog](https://agentswitchboard.dev/changelog), and batch by batch on [/drops](https://agentswitchboard.dev/drops). From 2.2.0 on, each minor release opens with its highlights, what you can do now with a link to try it, which [/whats-new](https://agentswitchboard.dev/whats-new) also shows. +## [2.10.2] - 2026-11-13 - One pick for a need + +### Highlights +- Ask for one tool for a job and get one pick, why it fits, the next step to start using it and two alternatives: say the need in a sentence to `GET /api/recommend` or the MCP and WebMCP tool `recommend`. [Try it](https://agentswitchboard.dev/for-agents#rest) + +### Added +- `recommend`, as an MCP tool, a WebMCP tool and `GET /api/recommend?need=…`: for each need a request names, the Operator's pick, why it was picked, its skill that does the task, the next step (the MCP client config to paste when the vendor's docs give one, else its setup guide or docs) and two alternatives, plus a [/stack](https://agentswitchboard.dev/stack) link for two or more picks and the answer in plain sentences. The pick follows fixed rules, not a model, so the same need always gets the same answer, and featured or sponsored placement never changes it. A need that matches no task is a 404 that names the closest tasks. The route records only how many picks it made, never the need, and robots.txt keeps crawlers off it. ([#399](https://github.com/assafbar2/agentswitchboard.dev/pull/399)) + +### Changed +- The MCP server is version 1.10.0, with nine tools, `recommend` and `request_missing_tool` among them; WebMCP registers seven read tools. [/openapi.json](https://agentswitchboard.dev/openapi.json) is version 1.14.0, and [docs/API.md](https://github.com/assafbar2/agentswitchboard.dev/blob/main/docs/API.md), [/for-agents](https://agentswitchboard.dev/for-agents), [/connect](https://agentswitchboard.dev/connect), llms.txt and skill.md describe `recommend`. ([#399](https://github.com/assafbar2/agentswitchboard.dev/pull/399)) + ## [2.10.1] - 2026-11-13 - What's new keeps up ### Highlights diff --git a/package-lock.json b/package-lock.json index 4c96a31..874c385 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "agentswitchboard.dev", - "version": "2.10.1", + "version": "2.10.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "agentswitchboard.dev", - "version": "2.10.1", + "version": "2.10.2", "license": "MIT", "dependencies": { "@mcp-b/webmcp-polyfill": "^5.0.1", diff --git a/package.json b/package.json index ca69a8a..f85020f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agentswitchboard.dev", - "version": "2.10.1", + "version": "2.10.2", "private": true, "scripts": { "dev": "next dev",