toolsdk provides a powerful API client for programmatic tool execution, with optional React components for building tool configuration UIs. It connects to toolsdk-mcp-registry - a curated registry of 100+ MCP servers and AI tools.

✨ Features

• ⚡ One-line Integration - Execute any tool with minimal code
• 📦 TypeScript First - Full type safety and IntelliSense support
• � MCP Cormpatible - Works seamlessly with Model Context Protocol servers
• 🤖 AI SDK Ready - Built-in support for Vercel AI SDK and OpenAI function calling
• 🎨 React Components - Optional pre-built UI for tool configuration

📦 Installation

npm install toolsdk
# or
pnpm add toolsdk
# or
yarn add toolsdk

Quick Start

Initialize Client

import { ToolSDKApiClient } from 'toolsdk/api';

const client = new ToolSDKApiClient({
  apiKey: 'your-api-key'
});

Execute Tools

Run a tool with a single method call:

const result = await client.package('github').run({
  toolKey: 'create-issue',
  inputData: {
    owner: 'myorg',
    repo: 'myrepo',
    title: 'Bug Report',
    body: 'Description of the issue...'
  }
});

console.log('Issue created:', result);

With Configuration Instance

For tools that require OAuth or credentials:

const result = await client.package('github').run({
  toolKey: 'create-issue',
  configurationInstanceId: 'config-instance-id',
  inputData: {
    owner: 'myorg',
    repo: 'myrepo',
    title: 'Bug Report'
  }
});

Browse Available Packages

// List all available packages
const packages = await client.packages.pages({
  pageNo: 1,
  pageSize: 20
});

console.log('Available packages:', packages.data);

// Get package details
const github = await client.package('github').info();
console.log('GitHub tools:', github.tools);

// List tools for a package
const tools = await client.package('github').tools();

AI SDK Integration

Vercel AI SDK

import { generateText } from 'ai';

// Get a single tool
const tool = await client.package('github').getAISDKTool('create-issue');

// Or get all tools from a package as a ToolSet
const toolSet = await client.package('github').getAISDKToolSet();

const result = await generateText({
  model: yourModel,
  tools: toolSet,
  prompt: 'Create a GitHub issue for the bug we discussed'
});

With Configuration Instance

const toolSet = await client.package('github').getAISDKToolSet({
  configurationInstanceId: 'config-instance-id'
});

OpenAI Function Calling

// Get tools in OpenAI function calling format
const openAITools = await client.package('github').getOpenAISDKTools();

// Or get a single tool
const tool = await client.package('github').getOpenAISDKTool('create-issue');

// Use with OpenAI SDK
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Create a GitHub issue' }],
  tools: openAITools
});

API Reference

ToolSDKApiClient

Main API client for server-side or authenticated usage.

const client = new ToolSDKApiClient({ apiKey: 'your-api-key' });

// Package operations
client.packages.pages(params)           // List packages with pagination
client.packages.get(key, version?)      // Get package info
client.packages.my()                    // Get your packages (developer)

// Work with a specific package
const pkg = client.package(key, version?, envs?);
pkg.info()                              // Get package details
pkg.tools()                             // List available tools
pkg.run(body)                           // Execute a tool
pkg.getAISDKTool(toolKey)               // Get AI SDK tool
pkg.getAISDKToolSet()                   // Get all tools as ToolSet
pkg.getOpenAISDKTool(toolKey)           // Get single OpenAI format tool
pkg.getOpenAISDKTools()                 // Get all OpenAI format tools
pkg.configuration                       // Access configuration API
pkg.createInstance(body)                // Create package instance

// Configuration management
client.configuration(packageKey, version?)
client.configurationInstance(instanceId)

// Package instance management
client.packageInstance(instanceId)

// Account operations
client.account(accountKey)

// Developer operations
client.developer

Subpath Exports

| Import Path | Description | |-------------|-------------| | toolsdk/api | API client classes (ToolSDKApiClient, ToolSDKAccountApiClient) | | toolsdk/react | React components (optional) | | toolsdk/types | TypeScript type definitions | | toolsdk/developer | Developer utilities | | toolsdk/utils | Helper functions |

Use pre-built React components to let users configure MCP servers and tools in your application.

Peer Dependencies

React components require React 18+ or 19+:

npm install react react-dom

PackageInstanceVORenderer

The main component for rendering a complete tool configuration form:

import { PackageInstanceVORenderer } from 'toolsdk/react';

function ToolConfigForm() {
  return (
    <PackageInstanceVORenderer
      accountToken="your-account-token"
      consumerKey="unique-consumer-key"
      onChange={(instance) => {
        console.log('Selected package:', instance.package?.name);
        console.log('Selected tool:', instance.toolKey);
        console.log('Input data:', instance.inputData);
      }}
    />
  );
}

This component provides:

1. MCP Server Selection - Searchable dropdown to select from available packages
2. Configuration Management - OAuth and credential configuration for the selected package
3. Tool Selection - Choose which tool to execute from the package
4. Input Fields - Dynamic form fields based on the selected tool's schema

With Default Values

Pre-populate the form with default selections:

<PackageInstanceVORenderer
  accountToken="your-account-token"
  consumerKey="unique-consumer-key"
  defaultValue={{
    packageKey: 'github',
    toolKey: 'create-issue',
    inputData: {
      title: 'Bug Report',
      body: 'Description of the issue...'
    }
  }}
  onChange={(instance) => console.log(instance)}
/>

Custom Field Rendering

Override default field rendering for specific input types:

import { PackageInstanceVORenderer, type CustomField } from 'toolsdk/react';

const customFields: Record<string, CustomField> = {
  repository: {
    render: ({ field, value, onChange }) => (
      <MyCustomRepositoryPicker
        label={field.label}
        value={value as string}
        onChange={onChange}
      />
    )
  }
};

function ToolConfigForm() {
  return (
    <PackageInstanceVORenderer
      accountToken="your-account-token"
      consumerKey="unique-consumer-key"
      customFields={customFields}
      onChange={(instance) => console.log(instance)}
    />
  );
}

Form Validation

Use the ref to validate before submission:

import { useRef } from 'react';
import { 
  PackageInstanceVORenderer, 
  type PackageInstanceVORendererRef 
} from 'toolsdk/react';

function ToolConfigForm() {
  const formRef = useRef<PackageInstanceVORendererRef>(null);

  const handleSubmit = async () => {
    const isValid = await formRef.current?.validate();
    if (isValid) {
      // Proceed with form submission
    }
  };

  return (
    <>
      <PackageInstanceVORenderer
        ref={formRef}
        accountToken="your-account-token"
        consumerKey="unique-consumer-key"
        onChange={(instance) => console.log(instance)}
      />
      <button onClick={handleSubmit}>Submit</button>
    </>
  );
}

Options

<PackageInstanceVORenderer
  accountToken="your-account-token"
  consumerKey="unique-consumer-key"
  options={{
    baseURL: 'https://custom-api.toolsdk.ai',  // Custom API endpoint
    scope: 'ALL_PUBLIC'                         // Package list scope
  }}
  onChange={(instance) => console.log(instance)}
/>

MCPServerForm (Alias)

MCPServerForm is an alias for PackageInstanceVORenderer:

import { MCPServerForm } from 'toolsdk/react';

// Same usage as PackageInstanceVORenderer
<MCPServerForm
  accountToken="your-account-token"
  consumerKey="unique-consumer-key"
  onChange={(instance) => console.log(instance)}
/>

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © toolsdk.ai