toolsdk

toolsdk

🚀 One SDK to integrate all MCP servers and AI tools

toolsdk provides everything you need to integrate AI tools into your applications - from pre-built React components for tool configuration to a powerful API client for programmatic tool execution.

✨ Features

• 🎨 React Components - Pre-built UI for MCP server and tool configuration
• ⚡ One-line Integration - Execute any tool with minimal code
• 📦 TypeScript First - Full type safety and IntelliSense support
• 🔌 MCP Compatible - Works seamlessly with Model Context Protocol servers
• 🔐 OAuth Support - Built-in authentication flow handling

📦 Installation

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

Peer Dependencies

toolsdk requires React 18+ or 19+ for the React components:

npm install react react-dom

Part 1: Frontend Form Components

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

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:

• MCP Server Selection - Searchable dropdown to select from available packages
• Configuration Management - OAuth and credential configuration for the selected package
• Tool Selection - Choose which tool to execute from the package
• 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> = {
  // Custom renderer for 'repository' field
  repository: {
    render: ({ field, value, onChange }) => (
      <MyCustomRepositoryPicker
        label={field.label}
        value={value as string}
        onChange={onChange}
      />
    )
  },
  // Custom renderer for 'assignees' field
  assignees: {
    render: ({ field, value, onChange }) => (
      <UserMultiSelect
        label={field.label}
        selected={value as string[]}
        onSelect={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>
    </>
  );
}

Part 2: Quick Integration

Use the API client to programmatically interact with MCP servers and execute tools.

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:

// Execute a GitHub tool
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);

Get Tools for AI SDK Integration

toolsdk provides built-in support for AI SDK tool format:

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

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

// Use with Vercel AI SDK
import { generateText } from 'ai';

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

OpenAI Function Calling Format

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

// 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

Subpath Exports

Import Path	Description
toolsdk/api	API client classes (ToolSDKApiClient, ToolSDKAccountApiClient)
toolsdk/react	React components (PackageInstanceVORenderer, MCPServerForm)
toolsdk/types	TypeScript type definitions (VO, DTO, BO types)
toolsdk/developer	Developer utilities
toolsdk/utils	Helper functions

ToolSDKApiClient

Main API client for server-side or authenticated usage.

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

// Access packages
client.packages.pages(params)     // List packages
client.packages.get(key, version) // Get package info
client.packages.my()              // Get your packages

// Work with a specific package
client.package(key, version?, envs?)
  .info()                         // Get package details
  .tools()                        // List available tools
  .run(body)                      // Execute a tool
  .getAISDKTool(toolKey)          // Get AI SDK tool
  .getAISDKToolSet()              // Get all tools as ToolSet
  .getOpenAISDKTools()            // Get OpenAI format tools

🤝 Contributing

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

📄 License

MIT © toolsdk.ai