> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# @toolshed/sources

> Data source adapters for OpenAPI, GraphQL, MCP, and plugins.

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:

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
interface SourceAdapter<T extends SourceConfig> {
  type: T["type"];
  resolve(config: T): Promise<Source>;
}
```