### Install @ideadesignmedia/open-ai.js

Source: https://context7.com/ideadesignmedia/open-ai.js/llms.txt

Install the library using npm, yarn, or pnpm.

```bash
# npm
npm install @ideadesignmedia/open-ai.js

# yarn
yarn add @ideadesignmedia/open-ai.js

# pnpm
pnpm add @ideadesignmedia/open-ai.js
```

--------------------------------

### Server Initialize Response Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

This is an example of a server's response to an initialize request, indicating protocol version, supported capabilities, server information, and instructions for the client.

```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-06-18",
"capabilities": {
"logging": {},
"prompts": { "listChanged": true},
"resources": { "subscribe": true, "listChanged": true},
"tools": { "listChanged": true}
},
"serverInfo": {
"name": "ExampleServer",
"version": "1.0.0"
},
"instructions": "Welcome! This server requires login for API calls."
}
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/REPO_GUIDANCE.md

Install project dependencies using Yarn. This is a standard step before building or running the project.

```bash
yarn install
```

--------------------------------

### Install @ideadesignmedia/open-ai.js

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/README.md

Install the library using npm, yarn, or pnpm. Node 18+ is recommended for global fetch and FormData.

```bash
# npm
npm install @ideadesignmedia/open-ai.js
```

```bash
# yarn
yarn add @ideadesignmedia/open-ai.js
```

```bash
# pnpm
pnpm add @ideadesignmedia/open-ai.js
```

--------------------------------

### Resource with Annotations Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

Example of a resource object including annotations for audience, priority, and last modified date.

```json
{
"uri": "file:///project/README.md",
"name": "README.md",
"title": "Project Documentation",
"mimeType": "text/markdown",
"annotations": {
"audience": ["user"],
"priority": 0.8,
"lastModified": "2025-01-12T15:00:58Z"
}
}
```

--------------------------------

### Example Tool Manifest Entry

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/mcp_spec.md

Defines a tool's name, description, and input schema for integration with MCP.

```json
{
  "name": "search_web",
  "description": "Search the web for a query string",
  "inputSchema": {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  }
}
```

--------------------------------

### Prompt Response Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/Model Context Protocol (MCP) – 2025‑06‑18 Specification Guide.md

Example response when retrieving a prompt. It includes a description and a list of messages, typically a user-role message with the prompt's content.

```json
{
"jsonrpc": "2.0",
"id": 43,
"result": {
"description": "Code review prompt",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Please review this Python code:\n def hello():\n\nprint('world')"
}
}
]
}
}
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/REPO_GUIDANCE.md

Illustrates MCP server options for exposing tools, resources, prompts, and models, along with transport selection.

```typescript
// Server options allow exposing tools/resources/prompts/models and selecting transports (`websocket`, `http`, `stdio`).
```

--------------------------------

### Define Tools and Start an MCP Server

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/README.md

Set up an McpServer with custom tools, handlers, resources, prompts, and models. The server can be configured with specific transports.

```typescript
import {
  McpServer,
  defineFunctionTool,
  defineObjectSchema
} from '@ideadesignmedia/open-ai.js'

const getIncident = defineFunctionTool({
  type: 'function',
  function: {
    name: 'get_incident_status',
    description: 'Fetch incident by ticket id',
    parameters: defineObjectSchema({
      type: 'object',
      properties: { ticket: { type: 'string' } },
      required: ['ticket']
    } as const)
  }
} as const)

const server = new McpServer({
  instructions: 'Incident MCP server',
  tools: [
    {
      tool: getIncident,
      handler: async ({ ticket }) => ({ ticket, status: 'RESOLVED' })
    }
  ],
  resources: [{ id: 'runbook', name: 'Incident runbook' }],
  readResource: async () => 'Always update status channels.',
  prompts: [{ name: 'postmortem', description: 'Postmortem template' }],
  getPrompt: async () => ({ text: '# Postmortem\n- Summary\n- Timeline' }),
  models: [{ name: 'playground', description: 'Demo model' }],
  selectModel: (name) => console.log('selected model:', name)

  // If your server implementation supports configuring transports in the constructor,
  // include them here. Otherwise, configure them according to your host's expectations.
  // Example fields that some hosts use: transports, port, path
  // transports: ['websocket'], port: 3030, path: '/mcp'
})

// Start the server
await server.start()
```

--------------------------------

### List Resource Templates Response

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

Example JSON-RPC response listing available resource templates, including URI templates and their descriptions.

```json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"resourceTemplates": [
{
"uriTemplate": "file:///{path}",
"name": "Project Files",
"title": "Project Files",
"description": "Access files in the project directory",
"mimeType": "application/octet-stream"
}
]
}
}
```

--------------------------------

### Implement Provider Adapter

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/REPO_GUIDANCE.md

Example structure for implementing a new LLM provider adapter. This involves mapping requests, parsing responses, and handling errors.

```typescript
// Map unified request → provider payload (tools/messages format)
// Parse provider response → unified shape (including tool calls)
// Throw `FetchError(status, message, body)` on HTTP errors
// Set `supportsStreaming`/`supportsTools` appropriately
```

--------------------------------

### Audio Content Block Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

Shows the structure for returning audio data, similar to images with base64 encoded data and MIME type.

```json
{
  "type": "audio",
  "data": "<base64 audio data>",
  "mimeType": "audio/mpeg"
}
```

--------------------------------

### tools/call Request Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

This JSON request demonstrates how to invoke a specific tool, 'get_weather', with the required 'location' argument. Ensure the arguments conform to the tool's input schema.

```json
{
"jsonrpc": "2.0",
"id": 52,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": { "location": "New York"}
}
}
```

--------------------------------

### Example MCP Tool Invocation Request

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/mcp_spec.md

A JSON-RPC 2.0 request to invoke a tool named 'search_web' with specific arguments.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/invoke",
  "params": { "name": "search_web", "arguments": { "query": "Phoenix weather" } },
  "id": 1
}
```

--------------------------------

### MCP Manifest Structure Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/mcp_spec.md

The overall structure of an MCP manifest file, outlining server information, tool definitions, and resource definitions.

```APIDOC
## Manifest Structure Example

### Description
This illustrates the top-level structure of an MCP manifest file, which describes the capabilities of an MCP server.

### Method
N/A (This is a data structure definition)

### Endpoint
N/A (This is a data structure definition)

### Request Body
- **mcpVersion** (string) - Required - The version of the MCP specification.
- **server** (object) - Required - Information about the server.
  - **name** (string) - Required - The name of the server.
  - **version** (string) - Required - The version of the server.
- **tools** (array) - Optional - A list of tool definitions.
- **resources** (array) - Optional - A list of resource definitions.

### Request Example
```json
{
  "mcpVersion": "2025-06-18",
  "server": {
    "name": "example-server",
    "version": "1.0.0"
  },
  "tools": [ /* tool definitions */ ],
  "resources": [ /* resource definitions */ ]
}
```

### Response
N/A (This is a request body example for a manifest structure)
```

--------------------------------

### Chat and Tool Calling with OpenAIClient

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/README.md

Perform chat completions and handle tool calls using the OpenAIClient. This example demonstrates setting up a tool and processing a tool call response.

```typescript
import OpenAIClient, { Message } from '@ideadesignmedia/open-ai.js'

const openai = new OpenAIClient({
  key: process.env.OPEN_AI_API_KEY!,
  organization: process.env.OPEN_AI_ORGANIZATION
})

const weatherTool = {
  type: 'function' as const,
  function: {
    name: 'get_weather',
    description: 'Return the temperature for a city',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'City name' },
        units: { type: 'string', enum: ['metric', 'imperial'] }
      },
      required: ['city'],
      additionalProperties: false
    }
  }
}

const completion = await openai.chatCompletion(
  [
    Message('You are a helpful assistant.', 'system'),
    Message('What is the weather in Paris?', 'user')
  ],
  1,
  undefined,
  {
    model: 'gpt-4o-mini',
    tools: [weatherTool],
    tool_choice: 'auto'
  }
)

const first = completion.choices[0]
if (first.message.tool_calls?.length) {
  // Step 1: read the requested tool + args
  const call = first.message.tool_calls[0]
  const args = JSON.parse(call.function.arguments)

  // Step 2: run your actual function
  const result = await get_weather(args)

  // Step 3: send follow-up with assistant tool_calls and tool result
  const followUp = await openai.chatCompletion(
    [
      Message('You are a helpful assistant.', 'system'),
      Message('What is the weather in Paris?', 'user'),
      // Assistant message must include tool_calls it requested
      { role: 'assistant', content: null, tool_calls: first.message.tool_calls },
      // Tool message must include tool_call_id of the call you are answering
      { role: 'tool', content: JSON.stringify(result), tool_call_id: call.id }
    ],
    1,
    undefined,
    { model: 'gpt-4o-mini', tools: [weatherTool], tool_choice: 'none' }
  )
  console.log(followUp.choices[0]?.message?.content)
}
```

--------------------------------

### Structured Content Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/Model Context Protocol (MCP) – 2025‑06‑18 Specification Guide.md

Demonstrates returning structured content alongside text content for broader client compatibility. The text content is a JSON string, while structuredContent is the parsed object.

```json
{
  "content": [
    { "type": "text", "text": "{\"temperature\":22.5,\"conditions\":\"Partly cloudy\",\"humidity\":65}" }
  ],
  "structuredContent": {
    "temperature": 22.5,
    "conditions": "Partly cloudy",
    "humidity": 65
  }
}
```

--------------------------------

### Client Initialize Request

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

A minimal initialize request sent by the client to start the MCP session. It declares supported protocol version and client capabilities.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": { "listChanged": true},
      "sampling": {},
      "elicitation": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### Resource Link Content Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/Model Context Protocol (MCP) – 2025‑06‑18 Specification Guide.md

Represents a reference to a resource produced or identified by a tool. The client can decide to auto-fetch it or present it to the user. Annotations can specify audience and priority.

```json
{
"type": "resource_link",
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"description": "Primary application entry point",
"mimeType": "text/x-rust",
"annotations": { "audience": ["assistant"], "priority": 0.9 }
}
```

--------------------------------

### Create and Start McpServer with Tools, Resources, and Prompts

Source: https://context7.com/ideadesignmedia/open-ai.js/llms.txt

Initialize an McpServer with specified port, path, transports, and instructions. Register tools with their handlers, expose resources with MIME types, and define prompt templates with retrieval functions.

```typescript
const server = new McpServer({
  port: 3030,
  path: '/mcp',
  transports: ['websocket', 'http'],
  instructions: 'Incident management MCP server for operations team',

  // Register tools with handlers
  tools: [
    {
      tool: getIncidentTool,
      handler: async ({ ticket }) => {
        // Fetch from your database
        return { ticket, status: 'OPEN', priority: 'HIGH', assignee: 'ops-team' }
      }
    },
    {
      tool: resolveIncidentTool,
      handler: async ({ ticket, resolution }) => {
        // Update your database
        return { ticket, status: 'RESOLVED', resolution, resolved_at: new Date().toISOString() }
      }
    }
  ],

  // Expose resources
  resources: [
    { id: 'runbook', name: 'Incident Runbook', mimeType: 'text/markdown' },
    { id: 'escalation', name: 'Escalation Matrix', mimeType: 'application/json' }
  ],
  readResource: async (idOrUri) => {
    if (idOrUri === 'runbook') return '# Incident Response\n1. Assess\n2. Communicate\n3. Resolve'
    if (idOrUri === 'escalation') return { levels: ['L1', 'L2', 'L3'], timeout_minutes: 15 }
    throw new Error('Resource not found')
  },

  // Expose prompt templates
  prompts: [
    { name: 'postmortem', description: 'Post-incident review template' }
  ],
  getPrompt: async (name) => {
    if (name === 'postmortem') {
      return { text: '# Postmortem\n## Summary\n## Timeline\n## Root Cause\n## Action Items' }
    }
    throw new Error('Prompt not found')
  }
})

await server.start()
console.log('MCP server running on ws://localhost:3030/mcp')

// Graceful shutdown
process.on('SIGINT', async () => {
  await server.stop()
  process.exit(0)
})
```

--------------------------------

### MCP Tools Invoke Request Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/mcp_spec.md

An example JSON-RPC 2.0 request to invoke a tool using the 'tools/invoke' method.

```APIDOC
## Tools Invoke Request Example

### Description
This example demonstrates how a client sends a request to invoke a specific tool on the server, providing the tool's name and its arguments.

### Method
POST

### Endpoint
/rpc (or relevant transport endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - Must be '2.0'.
- **method** (string) - Required - Must be 'tools/invoke'.
- **params** (object) - Required - Parameters for the invocation.
  - **name** (string) - Required - The name of the tool to invoke.
  - **arguments** (object) - Required - The arguments to pass to the tool, matching its input schema.
- **id** (integer or string) - Required - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/invoke",
  "params": {
    "name": "search_web",
    "arguments": {
      "query": "Phoenix weather"
    }
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Required - Must be '2.0'.
- **result** (object) - Required - The result of the tool invocation.
  - **status** (string) - Description of the invocation status (e.g., 'success').
  - **output** (any) - The output data from the tool.
- **id** (integer or string) - Required - The ID of the request this response corresponds to.

#### Error Response
- **jsonrpc** (string) - Required - Must be '2.0'.
- **error** (object) - Required - An error object if the invocation failed.
  - **code** (integer) - Required - An error code.
  - **message** (string) - Required - A message describing the error.
- **id** (integer or string) - Required - The ID of the request this response corresponds to.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "output": {
      "temperature": 82
    }
  },
  "id": 1
}
```
```

--------------------------------

### MCP Tool Definition Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/mcp_spec.md

An example of a tool definition within the MCP manifest, specifying its name, description, and input schema.

```APIDOC
## Tool Definition Example

### Description
This is an example of how a tool is defined within the MCP manifest, including its name, a brief description, and the expected input schema.

### Method
N/A (This is a data structure definition)

### Endpoint
N/A (This is a data structure definition)

### Request Body
- **name** (string) - Required - The unique name of the tool.
- **description** (string) - Optional - A human-readable description of the tool's purpose.
- **inputSchema** (object) - Required - A JSON schema defining the expected input parameters for the tool.
  - **type** (string) - Required - Must be 'object'.
  - **properties** (object) - Required - Defines the properties (parameters) of the input.
    - **param_name** (object) - Description of the parameter.
      - **type** (string) - Required - The data type of the parameter (e.g., 'string', 'integer').
  - **required** (array) - Optional - A list of parameter names that are mandatory.

### Request Example
```json
{
  "name": "search_web",
  "description": "Search the web for a query string",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      }
    },
    "required": ["query"]
  }
}
```

### Response
N/A (This is a request body example for a tool definition)
```

--------------------------------

### Connect and Interact with McpClient

Source: https://context7.com/ideadesignmedia/open-ai.js/llms.txt

Shows how to connect, initialize, send initialization confirmation, discover tools, call tools, list and read resources, and get prompt templates using the McpClient. Remember to shut down the client when done.

```typescript
// Connect and initialize
await wsClient.connect()
await wsClient.initialize({
  clientInfo: { name: 'my-app', version: '1.0.0' }
})
await wsClient.sendInitialized()

// Discover available tools
const tools = await wsClient.listTools()
console.log('Available tools:', tools.map(t => t.function.name))
// Output: ['get_incident', 'resolve_incident']

// Call a tool
const incident = await wsClient.callTool('get_incident', { ticket: 'INC-42' })
console.log('Incident:', incident)
// Output: { ticket: 'INC-42', status: 'OPEN', priority: 'HIGH', assignee: 'ops-team' }

// List and read resources
const resources = await wsClient.listResources()
const runbook = await wsClient.readResource('runbook')
console.log('Runbook:', runbook)

// Get prompt templates
const prompts = await wsClient.listPrompts()
const postmortem = await wsClient.getPrompt('postmortem')
console.log('Template:', postmortem)

// Clean up
await wsClient.shutdown()
```

--------------------------------

### Successful tools/call Response Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

This JSON response indicates a successful tool execution, containing the 'result' with the 'content' of the tool's output. The content type is 'text' in this example.

```json
{
"jsonrpc": "2.0",
"id": 52,
"result": {
"content": [
{
"type": "text",

```

--------------------------------

### Heartbeat Ping Response

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/Model Context Protocol (MCP) – 2025‑06‑18 Specification Guide.md

Example of a server responding to a heartbeat ping request with a trivial success result.

```json
{ "jsonrpc": "2.0", "id": X, "result": {} }
```

--------------------------------

### Core API Operations

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/README.md

Examples of using moderation, embeddings, models, and fine-tuning jobs with the OpenAI client.

```APIDOC
## Core API Operations

### Description
Demonstrates how to use key features of the OpenAI API including moderation checks, generating embeddings, retrieving model information, and creating fine-tuning jobs.

### Moderation
```ts
const moderation = await openai.moderation('Check this text', 'omni-moderation-latest')
```

### Embeddings
```ts
const embedding = await openai.getEmbedding('Vector me', 'text-embedding-3-small')
```

### Models
```ts
const models = await openai.getModels()
```

### Fine-tuning
```ts
const job = await openai.createFineTuningJob({
  model: 'gpt-4o-mini',
  training_file: file.id
})
```
```

--------------------------------

### Initialize McpClient with Different Transports

Source: https://context7.com/ideadesignmedia/open-ai.js/llms.txt

Demonstrates how to initialize the McpClient using WebSocket, HTTP, and STDIO transports. Ensure the server is running and accessible on the specified URL or command.

```typescript
import { McpClient } from '@ideadesignmedia/open-ai.js'

// WebSocket transport
const wsClient = new McpClient({
  transport: 'websocket',
  url: 'ws://localhost:3030/mcp'
})

// HTTP transport
const httpClient = new McpClient({
  transport: 'http',
  url: 'http://localhost:3030/mcp'
})

// STDIO transport (for local tools like npx servers)
const stdioClient = new McpClient({
  transport: 'stdio',
  stdio: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
  }
})
```

--------------------------------

### Text Content Block Example

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

A simple text output from a tool, indicating successful execution with human-readable information.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
    }
  ],
  "isError": false
}
```

--------------------------------

### Read Resource Content Request

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

Example JSON-RPC request to read the content of a specific resource using its URI.

```json
{"jsonrpc":"2.0","id":11,"method":"resources/read","params":{"uri":"file:///project/src/main.rs"}}
```

--------------------------------

### Server Initialization Response

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/mcp_detailed_spec.md

The server responds to the 'initialize' request with its name, version, and supported capabilities, such as tool and resource discovery.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "server": { "name": "example-server", "version": "1.0.0" },
    "serverCapabilities": {
      "supportsToolDiscovery": true,
      "supportsResourceDiscovery": true,
      "supportsNotifications": true
    }
  },
  "id": 1
}
```

--------------------------------

### Read Resource Content Response

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

Example JSON-RPC response containing the content of a text resource, including metadata and the text itself.

```json
{
"jsonrpc": "2.0",
"id": 11,
"result": {
"contents": [
{
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"title": "Rust Software Application Main File",
"mimeType": "text/x-rust",
"text": "fn main() {\n    println!(\"Hello world!\");\n}"
}
]
}
}
```

--------------------------------

### Type-safe Tool Schemas

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/README.md

Example of defining type-safe tool schemas for LLM tool calling using JSON Schema.

```APIDOC
## Type-safe Tool Schemas

### Description
Demonstrates how to define reusable JSON Schemas for LLM tool calling, ensuring type safety for parameters and arguments.

### Example
```ts
import {
  defineFunctionTool,
  defineObjectSchema,
  type InferParams,
  type InferToolArguments
} from '@ideadesignmedia/open-ai.js'

const scheduleParams = defineObjectSchema({
  type: 'object',
  properties: {
    date: { type: 'string', format: 'date' },
    hour: { type: 'integer', minimum: 0, maximum: 23 },
    reason: { type: 'string' }
  },
  required: ['date', 'hour'],
  additionalProperties: false
} as const)

export const scheduleTool = defineFunctionTool({
  type: 'function',
  function: {
    name: 'schedule_incident_review',
    description: 'Book a review slot',
    parameters: scheduleParams
  }
} as const)

type ScheduleArgs = InferParams<typeof scheduleParams>
type ScheduleCall = InferToolArguments<typeof scheduleTool>
```
```

--------------------------------

### Implement Tool Calling Workflow with OpenAI

Source: https://context7.com/ideadesignmedia/open-ai.js/llms.txt

Demonstrates a full tool calling workflow: defining a tool, making an initial chat completion request where the LLM decides to call the tool, parsing the tool arguments, simulating a tool execution, and then making a follow-up request with the tool's result.

```typescript
import OpenAIClient, { Message, defineFunctionTool, defineObjectSchema } from '@ideadesignmedia/open-ai.js'

const openai = new OpenAIClient({ key: process.env.OPEN_AI_API_KEY })

// Define a type-safe tool
const weatherTool = defineFunctionTool({
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get current weather for a city',
    parameters: defineObjectSchema({
      type: 'object',
      properties: {
        city: { type: 'string', description: 'City name' },
        units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['city'],
      additionalProperties: false
    } as const)
  }
} as const)

// First request - LLM decides to call the tool
const completion = await openai.chatCompletion(
  [
    Message('You are a weather assistant.', 'system'),
    Message('What is the weather in Tokyo?', 'user')
  ],
  1,
  undefined,
  { model: 'gpt-4o-mini', tools: [weatherTool], tool_choice: 'auto' }
)

const toolCall = completion.choices[0].message.tool_calls?.[0]
if (toolCall) {
  const args = JSON.parse(toolCall.function.arguments)
  // Call your actual weather API
  const weatherResult = { city: args.city, temp: 22, condition: 'sunny' }

  // Follow-up with tool result
  const followUp = await openai.chatCompletion(
    [
      Message('You are a weather assistant.', 'system'),
      Message('What is the weather in Tokyo?', 'user'),
      { role: 'assistant', content: null, tool_calls: [toolCall] },
      { role: 'tool', content: JSON.stringify(weatherResult), tool_call_id: toolCall.id }
    ],
    1,
    undefined,
    { model: 'gpt-4o-mini', tools: [weatherTool], tool_choice: 'none' }
  )

  console.log(followUp.choices[0].message.content)
  // Output: The weather in Tokyo is currently sunny with a temperature of 22°C.
}
```

--------------------------------

### Getting a Specific Prompt Definition

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec_full.txt

Retrieve the actual prompt content, typically chat messages, for a given prompt name and its arguments.

```APIDOC
## POST prompts/get

### Description
Retrieves the content of a specific prompt, including its description and messages, by providing the prompt's name and a map of its arguments.

### Method
POST

### Endpoint
prompts/get

### Parameters
#### Request Body
- **name** (string) - Required - The unique identifier of the prompt to retrieve.
- **arguments** (object) - Required - A map of argument names to their values for the prompt.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 43,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello():\n    print('world')"
    }
  }
}
```

### Response
#### Success Response (200)
- **description** (string) - A description of the prompt.
- **messages** (array) - A list of chat messages that form the prompt template.
  - **role** (string) - The role of the message sender (e.g., "user").
  - **content** (object) - The content of the message.
    - **type** (string) - The type of content (e.g., "text").
    - **text** (string) - The actual text content.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "description": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\n def hello():\n     print('world')"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Initialize OpenAIClient

Source: https://context7.com/ideadesignmedia/open-ai.js/llms.txt

Instantiate the OpenAIClient with your API key and optional organization or host. Access available models through the client instance.

```typescript
import OpenAIClient, { Message } from '@ideadesignmedia/open-ai.js'

const openai = new OpenAIClient({
  key: process.env.OPEN_AI_API_KEY,
  organization: process.env.OPEN_AI_ORGANIZATION,
  // Optional: point to any OpenAI-compatible endpoint
  host: 'https://api.openai.com/v1'
})

// Access all API surfaces through the client instance
const models = await openai.getModels()
console.log('Available models:', models.data.map(m => m.id))
```

--------------------------------

### List Resources Request and Response

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/docs/_tmp_spec.txt

Demonstrates the JSON-RPC request to list available resources and the server's response containing resource descriptors. The response includes resource URIs, names, titles, descriptions, and MIME types.

```json
{
"jsonrpc": "2.0",
"id": 10,
"method": "resources/list",
"params": {}
}
```

```json
{
"jsonrpc": "2.0",
"id": 10,
"result": {
"resources": [
{
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"title": "Rust Software Application Main File",
"description": "Primary application entry point",
"mimeType": "text/x-rust"
}
],
"nextCursor": null
}
}
```

--------------------------------

### Connect with an MCP Client

Source: https://github.com/ideadesignmedia/open-ai.js/blob/main/README.md

Establish a connection to an MCP server using McpClient, initialize the client with information, and interact with server-defined tools.

```typescript
import { McpClient } from '@ideadesignmedia/open-ai.js'

const client = new McpClient({
  transport: 'websocket',
  url: 'ws://127.0.0.1:3030/mcp'
})

await client.connect()
await client.initialize({ clientInfo: { name: 'dashboard', version: '1.0.0' } })
await client.sendInitialized()

const tools = await client.listTools()
const status = await client.callTool('get_incident_status', { ticket: 'INC-42' })
console.log(status)
```