Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
5.8 KB
Raw Blame
import { getJsonRequestBodySchema, getParameters, getQueryParameterSchema, hasJsonRequestBody, pathParameterNamesFromTemplate, type McpToolOperation } from "./catalog.js"

/**
 * `search_capabilities` is the "search" half of a search+execute facade laid
 * on top of the existing OpenAPI-derived catalog (`catalog.ts`) and its
 * existing in-process "execute" path (`invoke.ts`).
 *
 * Two consumers use this:
 * - The rich `/mcp` endpoint (`index.ts`), where matches are informational —
 *   the harness can call the matched tool name directly, since every
 *   catalog operation is also individually registered there.
 * - The minimal `/mcp/agent` endpoint (`agent.ts`), where matches are the
 *   *only* way to discover what's callable — that endpoint exposes nothing
 *   but `search_capabilities` and a generic `execute_capability`, so each
 *   match carries enough shape (`pathParams`/`queryParams`/`hasBody`) for the
 *   caller to construct a valid `execute_capability` call without guessing.
 */

export const SEARCH_CAPABILITIES_TOOL_NAME = "search_capabilities"
export const EXECUTE_CAPABILITY_TOOL_NAME = "execute_capability"
export type SearchCapabilityType = "all" | "api" | "admin" | "mcp" | "marketplace" | "skills"

export type CapabilityMatch = {
  name: string
  method: string
  path: string
  score: number
  summary: string
  /** Path parameter names this tool's `path` template requires, e.g. ["workerId"]. */
  pathParams: string[]
  /** Query parameter names this tool documents, if any. */
  queryParams: string[]
  /** Whether calling this tool requires a JSON `body`. */
  hasBody: boolean
  /** Exact OpenAPI JSON schema for `body`, present only for JSON mutations. */
  bodySchema?: unknown
  /** Exact OpenAPI JSON schema for the query string parameters, present only when the operation documents any. */
  querySchema?: unknown
  /** Exact MCP arguments schema returned by a live MCP tool list. */
  argumentsSchema?: unknown
  /** Tells generic execute callers where MCP arguments must be supplied. */
  invocation?: { argumentsField: "body" }
  /** Exact confined-script path when Code Mode scripts are enabled. */
  scriptPath?: string
  /** Callable capability or a source-specific advisory/content kind. */
  kind?: string
  /** Standard MCP App binding advertised by the matched provider tool. */
  mcpApp?: { resourceUri: string }
}

export function compareCapabilityMatches(a: CapabilityMatch, b: CapabilityMatch): number {
  const statusPriority = Number("kind" in b && b.kind === "connection_status")
    - Number("kind" in a && a.kind === "connection_status")
  // Relevance leads globally; an actionable status only wins an equal-score tie.
  return (b.score - a.score) || statusPriority || a.name.localeCompare(b.name)
}

export function searchCapabilitySourceFilter(type?: SearchCapabilityType) {
  const capabilityType = type ?? "all"
  return {
    api: capabilityType === "all" || capabilityType === "api",
    admin: capabilityType === "all" || capabilityType === "admin",
    mcp: capabilityType === "all" || capabilityType === "mcp",
    marketplace: capabilityType === "all" || capabilityType === "marketplace" || capabilityType === "skills",
    skills: capabilityType === "all" || capabilityType === "skills",
  }
}

export function tokenize(value: string): string[] {
  return value
    .toLowerCase()
    .split(/[^a-z0-9]+/)
    .filter((token) => token.length > 0)
}

export function scoreText(
  nameTokens: string[],
  summaryTokens: string[],
  queryTokens: string[],
  extraTokens: string[] = [],
): number {
  let score = 0
  for (const queryToken of queryTokens) {
    if (nameTokens.includes(queryToken)) {
      score += 5
    } else if (nameTokens.some((token) => token.startsWith(queryToken) || queryToken.startsWith(token))) {
      score += 3
    }
    if (summaryTokens.includes(queryToken)) {
      score += 2
    }
    if (extraTokens.includes(queryToken)) {
      score += 1
    }
  }
  return score
}

/**
 * Splits a camelCase / PascalCase tool name into lowercase word tokens so a
 * query like "organization" matches a tool named `getOrganizations`.
 */
function tokenizeToolName(name: string): string[] {
  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
  return tokenize(spaced)
}

function summaryFor(operation: McpToolOperation): string {
  return operation.operation.summary ?? operation.operation.description ?? `${operation.method} ${operation.path}`
}

function scoreOperation(operation: McpToolOperation, queryTokens: string[]): number {
  if (queryTokens.length === 0) {
    return 0
  }

  const nameTokens = tokenizeToolName(operation.name)
  const summaryTokens = tokenize(summaryFor(operation))
  const pathTokens = tokenize(operation.path)
  return scoreText(nameTokens, summaryTokens, queryTokens, pathTokens)
}

export function searchCapabilities(
  catalog: McpToolOperation[],
  query: string,
  limit = 5,
): CapabilityMatch[] {
  const queryTokens = tokenize(query)
  const boundedLimit = Math.max(1, Math.min(20, Math.trunc(limit) || 5))

  return catalog
    .map((operation) => {
      const bodySchema = getJsonRequestBodySchema(operation.operation)
      const querySchema = getQueryParameterSchema(operation.operation)
      return {
        name: operation.name,
        method: operation.method,
        path: operation.path,
        score: scoreOperation(operation, queryTokens),
        summary: summaryFor(operation),
        pathParams: pathParameterNamesFromTemplate(operation.path),
        queryParams: getParameters(operation.operation, "query").map((parameter) => parameter.name as string),
        hasBody: hasJsonRequestBody(operation.operation),
        ...(bodySchema === undefined ? {} : { bodySchema }),
        ...(querySchema === undefined ? {} : { querySchema }),
      }
    })
    .filter((match) => match.score > 0)
    .sort(compareCapabilityMatches)
    .slice(0, boundedLimit)
}