Skip to main content
The sources package provides adapters that resolve external API specifications into Toolshed-compatible tool definitions.

​
resolveSource(config)

Dispatches to the correct adapter based on config.type and returns a Source object: 
import { resolveSource } from "@toolshed/sources";

const source = await resolveSource({
  type: "openapi",
  id: "petstore",
  namespace: "petstore",
  specUrl: "https://petstore.swagger.io/v2/swagger.json",
});
// source.tools => ToolDefinition[]
// source.invoke(path, args) => Promise<unknown>

​
Source interface

interface Source {
  id: string;
  type: string;
  namespace: string;
  name: string;
  description: string;
  tools: ToolDefinition[];
  authProviders: AuthProvider[];
  invoke(path: string, args: Record<string, unknown>, authToken?: string): Promise<unknown>;
}

​
Adapters

​
OpenAPIAdapter

Fetches an OpenAPI/Swagger spec and generates tools from each endpoint.
  • Tool paths: namespace.resource.action (e.g., billing.invoices.list)
  • Action mapping: GET -> list/get, POST -> create, PUT -> update, PATCH -> patch, DELETE -> delete
  • Destructiveness: Derived from HTTP method (GET, HEAD, OPTIONS are safe)

​
GraphQLAdapter

Introspects a GraphQL schema and generates tools from queries and mutations.
  • Tool paths: namespace.field_name (camelCase -> snake_case)
  • Destructiveness: Queries are safe, mutations are destructive
  • Schema inference: Extracts input types from field arguments

​
MCPAdapter

Connects to an external MCP server and imports its tools.
  • Tool paths: namespace.tool_name (normalized to lowercase with underscores)
  • Discovery: Calls MCP tools/list via JSON-RPC
  • Invocation: Calls MCP tools/call with tool name and arguments
  • Destructiveness: Reads annotations.destructiveHint from MCP metadata

​
PluginAdapter

Wraps a definePlugin() result as a source for registry consistency.
  • Tool paths: As defined in the plugin
  • Destructiveness: Uses the explicit destructive field on each tool

​
SourceAdapter interface

All adapters implement: 
interface SourceAdapter<T extends SourceConfig> {
  type: T["type"];
  resolve(config: T): Promise<Source>;
}