@metorial/sdk 1.0.0-rc.4 → 1.0.0-rc.6

package/README.md

@@ -0,0 +1,280 @@
+# @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
+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);
+    }
+  }
+);
+```
+
+### 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
+- `mcp.withProviderSession(provider, init, action)`: Execute action with provider integration
+- `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metorial/sdk",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.6",
   "author": "Tobias Herber",
   "license": "MIT",
   "type": "module",
@@ -25,9 +25,9 @@
     "dist"
   ],
   "dependencies": {
-    "@metorial/core": "^1.0.0-rc.4",
-    "@metorial/mcp-session": "^1.0.0-rc.4",
-    "@metorial/util-endpoint": "^1.0.0-rc.4"
+    "@metorial/core": "^1.0.0-rc.6",
+    "@metorial/mcp-session": "^1.0.0-rc.6",
+    "@metorial/util-endpoint": "^1.0.0-rc.6"
   },
   "devDependencies": {
     "@types/isomorphic-fetch": "^0.0.39",