@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

$3

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

$3

`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);
}
);
`

$3

`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
await metorial.mcp.withProviderSession(
metorialOpenAI.chatCompletions,
{
serverDeployments: ['your-server-deployment-id']
},
async session => {
// 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);
}
}
);
`

$3

`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);
`

$3

`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);
`

$3

`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);
`

$3

`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

$3

#### Constructor

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

#### 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
- mcp.withProviderSession(provider, init, action): Execute action with provider integration
- mcp.createConnection(deploymentId): Create direct MCP connection

$3

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

$3

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 file for details.