Skip to main content
The SDK package provides functions for defining plugins, tools, and sources.

​
Exports

​
definePlugin(config): Plugin

Creates a plugin with a manifest and handler registry. 
import { definePlugin } from "@toolshed/sdk";

const plugin = definePlugin({
  id: "my-service",
  name: "My Service",
  description: "Tools for My Service",
  authProviders: [...],
  tools: [...],
});
PluginConfig:
FieldTypeRequiredDescription
idstringYesUnique plugin identifier
namestringYesHuman-readable name
descriptionstringYesPlugin description
authProvidersAuthProvider[]YesAuthentication providers
toolsToolConfig[]YesTool definitions
Returns: Plugin object with:
  • manifest — serialized PluginManifest (Zod schemas converted to JSON Schema)
  • handlers — Map<string, handler> keyed by tool path
Handlers are wrapped with Zod parsing. definePlugin doesn’t store the handler reference verbatim — it wraps it in (ctx, input) => handler(ctx, tool.inputSchema.parse(input ?? {})). This means schema defaults are applied before your handler sees the input, and invalid input throws a Zod error before any side effects. If you write inputSchema: z.object({ calendarId: z.string().default("primary") }) and the caller omits calendarId, your handler reads "primary", not undefined. Tests that compare handler references for equality won’t work — invoke through the wrapper.

​
defineTool(config): ToolConfig

Type-safe wrapper for tool definitions. Returns the config as-is with proper generic inference. 
import { defineTool } from "@toolshed/sdk";
import { z } from "zod";

const myTool = defineTool({
  path: "my_service.items.list",
  name: "List Items",
  description: "List items",
  inputSchema: z.object({ limit: z.number().default(10) }),
  outputSchema: z.object({ items: z.array(z.string()) }),
  async handler(ctx, input) { ... },
});

​
defineSource(config): SourceConfig

Type-safe wrapper for source configurations. Returns the config as-is. 
import { defineSource } from "@toolshed/sdk";

const source = defineSource({
  type: "openapi",
  id: "petstore",
  namespace: "petstore",
  specUrl: "https://petstore.swagger.io/v2/swagger.json",
});

​
elicit(ctx, request): Promise<ElicitationResponse>

Convenience wrapper for requesting user approval. Equivalent to calling ctx.elicit(request) directly. 
import { elicit } from "@toolshed/sdk";

const response = await elicit(ctx, {
  toolPath: "my_service.items.delete",
  message: "Delete this item?",
  type: "approval",
});

​
SourceConfigSchema

Zod discriminated union schema for validating source configurations. Validates openapi, graphql, mcp, and plugin source types.

​
Type exports

Plugin, PluginConfig, ToolConfig, Source, SourceAdapter, SourceConfig, SourceAuth, OpenAPISourceConfig, MCPSourceConfig, GraphQLSourceConfig, PluginSourceConfig