npm package: @pioneer-platform/pioneer-tools
Description: Unified tool wrappers for pioneer-sdk across MCP, CLI, and chat interfaces
Author: Pioneer Platform
Latest version: 0.1.0

# @pioneer-platform/pioneer-tools

Unified tool wrappers for pioneer-sdk across MCP, CLI, and chat interfaces.

## Overview

This package provides a standard tool interface for pioneer-sdk functionality that can be adapted for different use cases:
- MCP servers (JSON-RPC over SSE)
- CLI commands
- AI chat function executors
- REST APIs

## Features

- ✅ **Unified Tools** - Single implementation of pioneer-sdk tools
- ✅ **Multiple Adapters** - MCP, CLI, chat, REST (coming soon)
- ✅ **Type-Safe** - Full TypeScript support
- ✅ **Extensible** - Easy to add custom tools
- ✅ **Validated** - Input validation per tool schema

## Installation

```bash
npm install @pioneer-platform/pioneer-tools
```

## Available Tools

### Information Tools
- `getInfo` - Get SDK information (username, counts, etc.)
- `getDeviceInfo` - Get connected device information
- `getVaultStatus` - Get vault and portfolio status

### Query Tools
- `getBalances` - Get all account balances with filters
- `getPubkeys` - Get public keys for blockchains
- `refreshBalances` - Refresh balance data

### Action Tools
- `sync` - Sync all wallet data

## Usage

### Core Executor

```typescript
import { PioneerToolExecutor } from '@pioneer-platform/pioneer-tools';

// Initialize with your pioneer-sdk instance
const executor = new PioneerToolExecutor(pioneerSdk);

// Execute a tool
const result = await executor.execute('getBalances', {
  includeZero: false,
  network: 'eip155:1',
});

console.log(result);
// {
//   success: true,
//   data: [...],
//   message: 'Found 5 balances'
// }
```

### Get All Tools

```typescript
// Get all registered tools
const tools = executor.getTools();

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
  console.log(`  Category: ${tool.category}`);
  console.log(`  Schema:`, tool.inputSchema);
}
```

### Custom Tools

```typescript
import { PioneerTool } from '@pioneer-platform/pioneer-tools';

const myCustomTool: PioneerTool = {
  name: 'myTool',
  description: 'Does something custom',
  category: 'action',
  inputSchema: {
    type: 'object',
    properties: {
      param1: {
        type: 'string',
        description: 'A parameter',
      },
    },
  },
  async execute(sdk, params) {
    // Your custom logic here
    return {
      success: true,
      data: { result: 'done' },
      message: 'Custom tool executed',
    };
  },
};

// Register custom tool
executor.registerTool(myCustomTool);
```

### Execute Multiple Tools

```typescript
const results = await executor.executeMany([
  { name: 'getInfo', params: {} },
  { name: 'getBalances', params: { includeZero: false } },
  { name: 'sync', params: {} },
]);

// Returns array of ToolResult
```

## Adapters (Coming Soon)

### MCP Adapter

```typescript
import { MCPAdapter } from '@pioneer-platform/pioneer-tools/mcp';

const mcpAdapter = new MCPAdapter(executor);

// Use in MCP server
app.post('/mcp/message', async (req, res) => {
  const result = await mcpAdapter.handleToolCall(
    req.body.params.name,
    req.body.params.arguments
  );
  
  res.json(mcpAdapter.formatForMCP(result));
});
```

### CLI Adapter

```typescript
import { CLIAdapter } from '@pioneer-platform/pioneer-tools/cli';

const cliAdapter = new CLIAdapter(executor);

// Execute CLI command
await cliAdapter.executeCommand('balance', { format: 'table' });
```

### Chat Adapter

```typescript
import { ChatFunctionAdapter } from '@pioneer-platform/pioneer-tools/chat';

const chatAdapter = new ChatFunctionAdapter(executor);

// Execute from AI intent
const result = await chatAdapter.executeFunctions(
  ['getBalances', 'getInfo'],
  { includeZero: false }
);
```

## Tool Schema

Each tool has a standard interface:

```typescript
interface PioneerTool {
  name: string;                    // Tool identifier
  description: string;             // What it does
  category: ToolCategory;          // Tool category
  inputSchema: ToolSchema;         // JSON schema for inputs
  execute: (sdk, params) => Promise<ToolResult>;
}

interface ToolResult {
  success: boolean;
  data?: any;
  error?: string;
  message?: string;
}
```

## Tool Categories

- `info` - Information and status queries
- `query` - Data queries (balances, pubkeys, etc.)
- `capability` - Capability checks
- `path` - Path management
- `navigation` - UI navigation (for web/desktop)
- `config` - Configuration changes
- `action` - Actions that modify state

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev

# Clean
npm run clean
```

## Roadmap

- [x] Core tool executor
- [x] Basic tools (info, balances, pubkeys, sync)
- [ ] MCP adapter implementation
- [ ] CLI adapter implementation
- [ ] Chat adapter implementation
- [ ] Navigation tools (for web/desktop)
- [ ] Asset search tools
- [ ] Path management tools
- [ ] Configuration tools
- [ ] Swap/staking tools

## License

MIT