@metorial/sdk

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

Installation

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

Usage

Basic SDK Initialization

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

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

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

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

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

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

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

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:

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.