@metorial/mcp-sdk-utils

MCP SDK utilities for Metorial. Provides common utilities and helpers for MCP (Model Context Protocol) integration with AI SDK frameworks.

Installation

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

Usage

Basic AI SDK Integration

import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

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

// Use with AI SDK
metorial.withProviderSession(
  metorialAiSdk,
  {
    serverDeployments: ['your-server-deployment-id']
  },
  async session => {
    let result = await generateText({
      model: openai('gpt-4o'),
      prompt: 'Summarize the latest news about AI developments',
      maxSteps: 10,
      tools: session.tools
    });

    console.log(result.text);
  }
);

Advanced Tool Usage

import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';
import { generateText, streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

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

// Streaming with tools
metorial.withProviderSession(
  metorialAiSdk,
  {
    serverDeployments: ['your-server-deployment-id']
  },
  async session => {
    let { textStream } = await streamText({
      model: openai('gpt-4o'),
      prompt: 'Research the latest developments in quantum computing',
      maxSteps: 15,
      tools: session.tools
    });

    for await (let chunk of textStream) {
      process.stdout.write(chunk);
    }
  }
);

Custom Tool Configuration

import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

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

// Configure session with specific tools
metorial.withProviderSession(
  metorialAiSdk,
  {
    serverDeployments: ['your-server-deployment-id'],
    // Optional: Filter specific tools
    toolFilter: tool => tool.name.startsWith('search')
  },
  async session => {
    console.log(
      'Available tools:',
      session.tools.map(t => t.name)
    );

    let result = await generateText({
      model: anthropic('claude-3-sonnet-20240229'),
      prompt: 'Find information about renewable energy trends',
      maxSteps: 8,
      tools: session.tools
    });

    console.log('Result:', result.text);
  }
);

Error Handling

import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

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

try {
  await metorial.withProviderSession(
    metorialAiSdk,
    {
      serverDeployments: ['your-server-deployment-id']
    },
    async session => {
      let result = await generateText({
        model: openai('gpt-4o'),
        prompt: 'Analyze the current market trends',
        maxSteps: 10,
        tools: session.tools
      });

      return result.text;
    }
  );
} catch (error) {
  if (error.code === 'TOOL_EXECUTION_ERROR') {
    console.error('Tool execution failed:', error.message);
  } else if (error.code === 'SESSION_ERROR') {
    console.error('Session error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

React Component Integration

import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';
import { useChat } from 'ai/react';
import { openai } from '@ai-sdk/openai';

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

  let { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
    body: {
      metorialConfig: {
        provider: metorialAiSdk,
        serverDeployments: ['your-server-deployment-id']
      }
    }
  });

  return (
    <div>
      <div className="messages">
        {messages.map(message => (
          <div key={message.id}>
            <strong>{message.role}:</strong> {message.content}
          </div>
        ))}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Ask me anything..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
    </div>
  );
}

API Route Handler

// pages/api/chat.ts
import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';
import { openai, streamText } from 'ai';
import { NextRequest } from 'next/server';

export async function POST(req: NextRequest) {
  let { messages, metorialConfig } = await req.json();

  let metorial = new Metorial({
    apiKey: process.env.METORIAL_API_KEY!
  });

  return metorial.withProviderSession(
    metorialAiSdk,
    {
      serverDeployments: metorialConfig.serverDeployments
    },
    async session => {
      let { textStream } = await streamText({
        model: openai('gpt-4o'),
        messages,
        maxSteps: 10,
        tools: session.tools
      });

      return textStream;
    }
  );
}

Tool Discovery and Inspection

import { metorialAiSdk } from '@metorial/mcp-sdk-utils';
import { Metorial } from '@metorial/sdk';

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

// Inspect available tools
metorial.withProviderSession(
  metorialAiSdk,
  {
    serverDeployments: ['your-server-deployment-id']
  },
  async session => {
    console.log('Available tools:');
    session.tools.forEach(tool => {
      console.log(`- ${tool.name}: ${tool.description}`);
      if (tool.function?.parameters) {
        console.log(`  Parameters:`, tool.function.parameters);
      }
    });

    // Test a specific tool
    let searchTool = session.tools.find(t => t.name === 'searchContext');
    if (searchTool) {
      let result = await searchTool.call({
        query: 'metorial AI tools',
        maxResults: 3
      });
      console.log('Tool test result:', result);
    }
  }
);

API Reference

metorialAiSdk

The main integration function that provides MCP tools to AI SDK frameworks.

Usage: Pass to metorial.withProviderSession() as the provider parameter.

Returns: Session object with tools compatible with AI SDK.

Session Object

The session object provides:

• tools: Array of MCP tools compatible with AI SDK
• callTools(toolCalls): Function to execute tool calls

Tool Object

Each tool in the session has:

• name: Tool name
• description: Tool description
• function: Tool function definition with parameters
• call(args): Function to call the tool directly

License

MIT License - see LICENSE file for details.