# @metorial/sdk

Primary SDK package for Metorial. Provides the main SDK functionality, session management, and MCP (Model Context Protocol) integration capabilities.

## Installation

```bash
npm install @metorial/sdk
# or
yarn add @metorial/sdk
# or
pnpm add @metorial/sdk
# or
bun add @metorial/sdk
```

## Usage

### Basic SDK Initialization

```typescript
import { Metorial } from '@metorial/sdk';

// Initialize the SDK
let metorial = new Metorial({
  apiKey: 'your-metorial-api-key',
  apiHost: 'https://api.metorial.com', // optional
  mcpHost: 'https://mcp.metorial.com' // optional
});

// Access different SDK components
let instance = metorial.instance; // Instance management
let secrets = metorial.secrets; // Secrets management
let servers = metorial.servers; // Server management
let sessions = metorial.sessions; // Session management
```

### MCP Session Management

```typescript
import { Metorial } from '@metorial/sdk';

let metorial = new Metorial({
  apiKey: 'your-metorial-api-key'
});

// Create a basic MCP session
await metorial.mcp.withSession(
  {
    serverDeployments: ['your-server-deployment-id']
  },
  async session => {
    // Get session information
    let sessionInfo = await session.getSession();
    console.log('Session:', sessionInfo);

    // Get available tools
    let toolManager = await session.getToolManager();
    let tools = toolManager.getTools();
    console.log(
      'Available tools:',
      tools.map(t => t.name)
    );

    // Get server capabilities
    let capabilities = await session.getCapabilities();
    console.log('Capabilities:', capabilities);
  }
);
```

### Provider Session Integration

```typescript
import { Metorial } from '@metorial/sdk';
import { metorialOpenAI } from '@metorial/openai';
import OpenAI from 'openai';

let metorial = new Metorial({
  apiKey: 'your-metorial-api-key'
});

let openai = new OpenAI({
  apiKey: 'your-openai-api-key'
});

// Use with AI provider integration
let session = await metorial.connect({
  adapter: metorialOpenAI.chatCompletions(),
  providers: [{ providerDeploymentId: 'your-provider-deployment-id' }]
});

// session.tools() contains the tools formatted for OpenAI
let response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: 'Search for information about AI developments'
    }
  ],
  tools: session.tools()
});

let choice = response.choices[0];
if (choice.message.tool_calls) {
  // Execute tool calls
  let toolResponses = await session.callTools(choice.message.tool_calls);
  console.log('Tool responses:', toolResponses);
}
```

### Direct MCP Connection

```typescript
import { Metorial } from '@metorial/sdk';

let metorial = new Metorial({
  apiKey: 'your-metorial-api-key'
});

// Create a direct MCP connection
let connection = await metorial.mcp.createConnection('your-server-deployment-id');

// Use the connection for direct MCP communication
let tools = await connection.listTools();
console.log('Available tools:', tools);

let result = await connection.callTool('searchContext', {
  query: 'metorial AI tools',
  maxResults: 5
});
console.log('Search result:', result);
```

### Server Management

```typescript
import { Metorial } from '@metorial/sdk';

let metorial = new Metorial({
  apiKey: 'your-metorial-api-key'
});

// List all servers
let servers = await metorial.servers.list();
console.log('Available servers:', servers);

// Get specific server
let server = await metorial.servers.get('server-id');
console.log('Server details:', server);

// List server deployments
let deployments = await metorial.servers.deployments.list();
console.log('Deployments:', deployments);

// Create a new deployment
let newDeployment = await metorial.servers.deployments.create({
  serverId: 'server-id',
  variantId: 'variant-id',
  versionId: 'version-id'
});
console.log('New deployment:', newDeployment);
```

### Session Management

```typescript
import { Metorial } from '@metorial/sdk';

let metorial = new Metorial({
  apiKey: 'your-metorial-api-key'
});

// List all sessions
let sessions = await metorial.sessions.list();
console.log('Active sessions:', sessions);

// Get specific session
let session = await metorial.sessions.get('session-id');
console.log('Session details:', session);

// Create a new session
let newSession = await metorial.sessions.create({
  serverDeploymentId: 'deployment-id'
});
console.log('New session:', newSession);

// Get session messages
let messages = await metorial.sessions.messages.list('session-id');
console.log('Session messages:', messages);

// Get session connections
let connections = await metorial.sessions.connections.list('session-id');
console.log('Session connections:', connections);
```

### Secrets Management

```typescript
import { Metorial } from '@metorial/sdk';

let metorial = new Metorial({
  apiKey: 'your-metorial-api-key'
});

// List all secrets
let secrets = await metorial.secrets.list();
console.log('Available secrets:', secrets);

// Get specific secret
let secret = await metorial.secrets.get('secret-id');
console.log('Secret details:', secret);

// Create a new secret
let newSecret = await metorial.secrets.create({
  name: 'my-api-key',
  value: 'secret-value',
  description: 'API key for external service'
});
console.log('New secret:', newSecret);
```

## API Reference

### `Metorial` Class

#### Constructor

```typescript
new Metorial(config: {
  apiKey: string;
  apiHost?: string;
  mcpHost?: string;
  apiVersion?: string;
  headers?: Record<string, string>;
})
```

#### Properties

- `instance`: Instance management endpoint
- `secrets`: Secrets management endpoint
- `servers`: Server management endpoint
- `sessions`: Session management endpoint
- `mcp`: MCP-specific methods

#### MCP Methods

- `mcp.createSession(init)`: Create a new MCP session
- `mcp.withSession(init, action)`: Execute action with session lifecycle management
- `connect(options)`: Connect to MCP providers with an AI adapter
- `mcp.createConnection(deploymentId)`: Create direct MCP connection

### Session Management

The SDK provides comprehensive session management with automatic lifecycle handling, tool discovery, and provider integration.

### Error Handling

All SDK methods throw `MetorialSDKError` for API errors with additional context:

```typescript
try {
  await metorial.servers.get('invalid-id');
} catch (error) {
  if (error instanceof MetorialSDKError) {
    console.log('API Error:', error.message);
    console.log('Status:', error.status);
    console.log('Code:', error.code);
  }
}
```

## License

MIT License - see [LICENSE](../../LICENSE) file for details.