Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.3] - 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.2] - 2026-11-13 - Prices for the Sponsored slot

### Highlights
Expand Down
2 changes: 1 addition & 1 deletion DISTRIBUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`, `request_missing_tool`.
Tools: `search_agents`, `get_agent`, `list_categories`, `compare_agents`, `alternatives_to`, `connect_bundle`, `recommend`, `submit_listing`, `request_missing_tool`.
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
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) · `request_missing_tool` (tells the maintainer privately that nothing
fits a job). Streamable HTTP, no auth. Stdio-only clients:
`npx -y mcp-remote https://agentswitchboard.dev/api/mcp`
Expand Down
55 changes: 53 additions & 2 deletions app/api/[transport]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,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 { logZeroResults } from '@/lib/leads';
Expand All @@ -39,6 +39,8 @@ import {
COMPARE_SLUGS_INPUT,
CONNECT_BUNDLE_DESCRIPTION,
OFFICIAL_DEFINITION,
RECOMMEND_DESCRIPTION,
RECOMMEND_NEED_INPUT,
SINCE_INPUT,
TASK_INPUT,
VERIFIED_INPUT,
Expand Down Expand Up @@ -99,6 +101,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, ' +
Expand Down Expand Up @@ -524,6 +527,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',
{
Expand Down Expand Up @@ -565,7 +616,7 @@ const handler = createMcpHandler(
);
},
{
serverInfo: { name: 'agentswitchboard', version: '1.9.0' },
serverInfo: { name: 'agentswitchboard', version: '1.10.0' },
instructions: INSTRUCTIONS,
},
{
Expand Down
39 changes: 39 additions & 0 deletions app/api/recommend/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/**
* One recommendation for what a user needs, and the next step to start using it.
*
* GET /api/recommend?need=<the user's need, in a sentence>
* → { 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<Response> {
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<Response> {
return corsPreflight();
}
7 changes: 6 additions & 1 deletion app/connect/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
}]
}'`;
Expand All @@ -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.' },
{
name: 'request_missing_tool',
Expand Down
8 changes: 5 additions & 3 deletions app/for-agents/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,9 @@ export default async function ForAgentsPage() {
Connect directly and query the catalog with native tools —{' '}
<code className="font-bold">search_agents</code>,{' '}
<code className="font-bold">get_agent</code>,{' '}
<code className="font-bold">list_categories</code> — help a user
choose with <code className="font-bold">compare_agents</code>,{' '}
<code className="font-bold">list_categories</code> — get one pick and
the next step for a need with <code className="font-bold">recommend</code>,
help a user choose with <code className="font-bold">compare_agents</code>,{' '}
<code className="font-bold">alternatives_to</code> and{' '}
<code className="font-bold">connect_bundle</code> (one MCP client config
for up to {MY_STACK_MAX} listings), and suggest a listing with{' '}
Expand Down Expand Up @@ -171,7 +172,7 @@ export default async function ForAgentsPage() {
<section className="space-y-2" id="webmcp">
<h2 className="dir-bar">## In-browser tools (WebMCP)</h2>
<p>
If you are viewing this page in a browser, the six read tools are
If you are viewing this page in a browser, the seven read tools are
registered on{' '}
<code className="font-bold">document.modelContext</code>{' '}
(W3C WebMCP API, polyfilled). Call them directly — no scraping, no setup.
Expand Down Expand Up @@ -210,6 +211,7 @@ GET /api/agents/<slug>/alternatives
GET /api/categories
GET /api/compare?a=<slug>&b=<slug>&c=<slug>
GET /api/bundle?items=<slug>,<slug>
GET /api/recommend?need=<the need, in a sentence>
GET /api/stacks
GET /api/stacks/<slug>
GET /api/tasks
Expand Down
3 changes: 2 additions & 1 deletion app/index.md/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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), \`request_missing_tool\` (tells the maintainer privately that nothing fits a job; REST: \`POST /api/missing-tool\`). 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), \`request_missing_tool\` (tells the maintainer privately that nothing fits a job; REST: \`POST /api/missing-tool\`). 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.
Expand Down
10 changes: 8 additions & 2 deletions app/llms.txt/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,11 @@ work, filtering on \`accessMethods\`, \`categories\`, \`authType\` (\`none\` for
sign-in) 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=<the need, in a sentence>. 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=<slug>&b=<slug>&c=<slug>
- Listings that could stand in for one, each with why: the \`alternatives_to\` MCP tool,
Expand All @@ -101,7 +106,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), request_missing_tool (tells the maintainer privately that nothing fits a job; also POST /api/missing-tool)
- 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), request_missing_tool (tells the maintainer privately that nothing fits a job; also POST /api/missing-tool)
- 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}
Expand All @@ -111,6 +116,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

Expand All @@ -122,7 +128,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).

Expand Down
4 changes: 2 additions & 2 deletions app/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ export default async function HomePage() {
connect your agent → agentswitchboard.dev/api/mcp
</span>
<span className="mono text-[13px] text-[var(--dir-muted)] sm:ml-auto">
search_agents · compare_agents · alternatives_to · connect_bundle
recommend · search_agents · compare_agents · alternatives_to · connect_bundle
</span>
</Link>
<Link
Expand Down Expand Up @@ -566,7 +566,7 @@ export default async function HomePage() {
</div>
<div className="agent-row">
<span className="agent-accent">/api/mcp</span>
<span className="agent-dim">MCP server · search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle</span>
<span className="agent-dim">MCP server · search_agents, get_agent, list_categories, compare_agents, alternatives_to, connect_bundle, recommend</span>
<span className="agent-dim">streamable-http · no auth</span>
</div>
<div className="agent-row">
Expand Down
5 changes: 3 additions & 2 deletions app/robots.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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/'] },
Expand Down
Loading
Loading