npm package: @mcpsdk.dev/sdk
Description: MCPSDK - A decentralized Tool SDK for AI Agents. Add automation features and 100+ integrations to your AI apps.
Author: mcpsdk.dev
Latest version: 2.1.0

<p align="center">
  <a href="https://toolsdk.ai">
    <img src="https://raw.githubusercontent.com/toolsdk-ai/toolsdk-mcp-registry/main/assets/hero.png" alt="toolsdk" width="600" />
  </a>
</p>

<h1 align="center">toolsdk</h1>

<p align="center">
  <strong>One SDK to integrate all MCP servers and AI tools</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/toolsdk"><img src="https://badge.fury.io/js/toolsdk.svg" alt="npm version" /></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue.svg" alt="TypeScript" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
</p>

<p align="center">
  <a href="https://toolsdk.ai">Website</a> •
  <a href="https://www.npmjs.com/package/toolsdk">NPM</a> •
  <a href="https://github.com/toolsdk-ai/toolsdk-mcp-registry">MCP Registry</a>
</p>

---

**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](https://github.com/toolsdk-ai/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

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

---

## Quick Start

### Initialize Client

```typescript
import { ToolSDKApiClient } from 'toolsdk/api';

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

### Execute Tools

Run a tool with a single method call:

```typescript
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:

```typescript
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

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

```typescript
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

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

### OpenAI Function Calling

```typescript
// 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.

```typescript
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 |

---

<details>
<summary><strong>🎨 React Components (Optional)</strong></summary>

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+:

```bash
npm install react react-dom
```

### PackageInstanceVORenderer

The main component for rendering a complete tool configuration form:

```tsx
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:

```tsx
<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:

```tsx
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:

```tsx
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

```tsx
<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`:

```tsx
import { MCPServerForm } from 'toolsdk/react';

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

</details>

---

## 🤝 Contributing

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

## 📄 License

MIT © [toolsdk.ai](https://toolsdk.ai)