@scalar/agent 0.1.5

package/README.md

@@ -0,0 +1,166 @@
+# Scalar Agent SDK
+
+Connect your AI agent to Scalar's OpenAPI MCP servers. Provides native integrations for the Vercel AI SDK, OpenAI Agents SDK, and Anthropic Claude SDK.
+
+## Installation
+
+```bash
+npm i @scalar/agent
+```
+
+```bash
+pnpm i @scalar/agent
+```
+
+```bash
+bun i @scalar/agent
+```
+
+## Setup
+
+```ts
+import { agentScalar } from '@scalar/agent'
+
+const scalar = agentScalar({
+  agentKey: 'your-agent-key',
+  baseUrl: 'https://services.scalar.com',
+})
+
+const session = await scalar.session({
+  apis: [{ namespace: 'scalar', slug: 'galaxy' }],
+})
+```
+
+## Providers
+
+### Vercel AI SDK
+
+Uses `@ai-sdk/mcp` natively. Returns a tool set ready for `generateText` / `streamText`.
+
+```ts
+import { generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const scalar = agentScalar({
+  agentKey: 'your-agent-key',
+  baseUrl: 'https://services.scalar.com',
+})
+
+const session = await scalar.session({
+  apis: [{ namespace: 'scalar', slug: 'galaxy' }],
+})
+
+const tools = await session.createVercelAITools()
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  tools,
+  prompt: 'List the available endpoints in the Galaxy API',
+})
+```
+
+### OpenAI Agents SDK
+
+Returns `MCPServerStreamableHttpOptions[]` — pass each entry to `new MCPServerStreamableHttp()` from `@openai/agents`. The agent runtime handles tool discovery and execution natively.
+
+```ts
+import { Agent, MCPServerStreamableHttp, run } from '@openai/agents'
+
+const scalar = agentScalar({
+  agentKey: 'your-agent-key',
+  baseUrl: 'https://services.scalar.com',
+})
+
+const session = await scalar.session({
+  apis: [{ namespace: 'scalar', slug: 'galaxy' }],
+})
+
+const serverOptions = session.createOpenAIMCPServerOptions()
+const servers = serverOptions.map((opts) => new MCPServerStreamableHttp(opts))
+await Promise.all(servers.map((s) => s.connect()))
+
+const agent = new Agent({
+  name: 'api-agent',
+  instructions: 'You help users interact with APIs.',
+  mcpServers: servers,
+})
+
+const result = await run(
+  agent,
+  'List the available endpoints in the Galaxy API',
+)
+
+await Promise.all(servers.map((s) => s.close()))
+```
+
+### Anthropic Claude SDK
+
+Uses `@modelcontextprotocol/sdk` directly. Returns `tools` (ready for `messages.create`) and `executeTool` (for handling `tool_use` response blocks).
+
+```ts
+import Anthropic from '@anthropic-ai/sdk'
+
+const scalar = agentScalar({
+  agentKey: 'your-agent-key',
+  baseUrl: 'https://services.scalar.com',
+})
+
+const session = await scalar.session({
+  apis: [{ namespace: 'scalar', slug: 'galaxy' }],
+})
+
+const client = new Anthropic()
+const { tools, executeTool } = await session.createAnthropicTools()
+
+const messages: Anthropic.MessageParam[] = [
+  { role: 'user', content: 'List the available endpoints in the Galaxy API' },
+]
+
+// Agentic loop
+while (true) {
+  const response = await client.messages.create({
+    model: 'claude-opus-4-6',
+    max_tokens: 4096,
+    tools,
+    messages,
+  })
+
+  messages.push({ role: 'assistant', content: response.content })
+
+  if (response.stop_reason !== 'tool_use') break
+
+  const toolResults: Anthropic.ToolResultBlockParam[] = await Promise.all(
+    response.content
+      .filter(
+        (block): block is Anthropic.ToolUseBlock => block.type === 'tool_use',
+      )
+      .map(async (block) => ({
+        type: 'tool_result',
+        tool_use_id: block.id,
+        content: await executeTool(
+          block.name,
+          block.input as Record<string, unknown>,
+        ),
+      })),
+  )
+
+  messages.push({ role: 'user', content: toolResults })
+}
+```
+
+## Configuration
+
+| Option     | Type     | Description                                                            |
+| ---------- | -------- | ---------------------------------------------------------------------- |
+| `agentKey` | `string` | Scalar agent key, sent as the authorization request header             |
+| `baseUrl`  | `string` | Base URL of the Scalar MCP server. Defaults to the staging environment |
+
+## How it works
+
+Each Scalar API is exposed as an MCP (Model Context Protocol) server. The SDK connects to these servers and surfaces their tools to your AI framework of choice. Every API exposes three tools:
+
+- **`get-openapi-specs-summary`** — lists the available endpoints
+- **`get-mini-openapi-spec`** — fetches a trimmed OpenAPI spec for specific endpoints
+- **`execute-request`** — executes an HTTP request against the API
+
+Tools are namespaced by API to avoid collisions when connecting multiple APIs at once: `{namespace}{delimiter}{slug}__{toolName}`.

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import z from 'zod';
+export interface AgentSDKConfig {
+    /** Base URL of the Scalar MCP server. Defaults to the Scalar staging environment. */
+    baseUrl?: string;
+    /** Sent as the `x-scalar-agent-key` request header. */
+    agentKey?: string;
+}
+type Api = {
+    namespace: string;
+    slug: string;
+};
+export type MCPServerOptions = {
+    url: string;
+    name: string;
+    fetch: (url: RequestInfo | URL, options?: RequestInit) => Promise<Response>;
+};
+export declare const EXECUTE_REQUEST_TOOL_NAME = "execute-request";
+export declare const executeRequestToolInputSchema: z.ZodObject<{
+    method: z.ZodString;
+    path: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const mcpToolSchemas: {
+    "execute-request": {
+        inputSchema: z.ZodObject<{
+            method: z.ZodString;
+            path: z.ZodString;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            body: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    "get-mini-openapi-spec": {
+        inputSchema: z.ZodObject<{
+            question: z.ZodString;
+        }, z.core.$strip>;
+    };
+    "get-openapi-specs-summary": {
+        inputSchema: z.ZodObject<{}, z.core.$strip>;
+    };
+};
+/**
+ * Creates a Scalar agent client configured to connect to Scalar's MCP servers.
+ *
+ * @example
+ * ```ts
+ * const scalar = agentScalar({ agentKey: 'your-agent-key' })
+ * ```
+ */
+export declare const agentScalar: (config?: AgentSDKConfig) => {
+    session: ({ apis }: {
+        apis: Api[];
+    }) => Promise<{
+        /**
+         * Returns tools in Vercel AI SDK format.
+         * Uses `@ai-sdk/mcp` natively.
+         *
+         * @example
+         * ```ts
+         * import { agentScalar } from '@scalar/agent'
+         * import { generateText } from 'ai'
+         * import { openai } from '@ai-sdk/openai'
+         *
+         * const scalar = agentScalar({ agentKey: 'your-agent-key' })
+         * const session = await scalar.session({ apis: [{ namespace: 'scalar', slug: 'galaxy' }] })
+         *
+         * const tools = await session.createVercelAITools()
+         *
+         * const { text } = await generateText({
+         *   model: openai('gpt-4o'),
+         *   tools,
+         *   prompt: 'List the available endpoints in the Petstore API',
+         * })
+         * ```
+         */
+        createVercelAITools: () => Promise<any>;
+        /**
+         * Returns options for creating `MCPServerStreamableHttp` instances via `@openai/agents`.
+         * The agent handles tool discovery and execution natively.
+         *
+         * @example
+         * ```ts
+         * import { agentScalar } from '@scalar/agent'
+         * import { Agent, MCPServerStreamableHttp, run } from '@openai/agents'
+         *
+         * const scalar = agentScalar({ agentKey: 'your-agent-key' })
+         * const session = await scalar.session({ apis: [{ namespace: 'scalar', slug: 'galaxy' }] })
+         *
+         * const servers = (await session.createOpenAIMCP()).map((opts) => new MCPServerStreamableHttp(opts))
+         * await Promise.all(servers.map((s) => s.connect()))
+         *
+         * const agent = new Agent({
+         *   name: 'api-agent',
+         *   instructions: 'You help users interact with APIs.',
+         *   mcpServers: servers,
+         * })
+         *
+         * const result = await run(agent, 'List the available endpoints in the Petstore API')
+         * await Promise.all(servers.map((s) => s.close()))
+         * ```
+         */
+        createOpenAIMCP: () => Promise<MCPServerOptions[]>;
+        /**
+         * Returns tools in `@anthropic-ai/sdk` format.
+         * Uses `@modelcontextprotocol/sdk` Client directly — `listTools()` already returns
+         * JSON Schema so no conversion needed. Tool calls are routed back via `callTool()`.
+         *
+         * @example
+         * ```ts
+         * import { agentScalar } from '@scalar/agent'
+         * import Anthropic from '@anthropic-ai/sdk'
+         *
+         * const scalar = agentScalar({ agentKey: 'your-agent-key' })
+         * const session = await scalar.session({ apis: [{ namespace: 'scalar', slug: 'galaxy' }] })
+         *
+         * const client = new Anthropic()
+         * const { tools, executeTool } = await session.createAnthropicTools()
+         *
+         * const messages: Anthropic.MessageParam[] = [
+         *   { role: 'user', content: 'List the available endpoints in the Petstore API' },
+         * ]
+         *
+         * // Agentic loop
+         * while (true) {
+         *   const response = await client.messages.create({
+         *     model: 'claude-opus-4-6',
+         *     max_tokens: 4096,
+         *     tools,
+         *     messages,
+         *   })
+         *
+         *   messages.push({ role: 'assistant', content: response.content })
+         *
+         *   if (response.stop_reason !== 'tool_use') break
+         *
+         *   const toolResults = await Promise.all(
+         *     response.content
+         *       .filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use')
+         *       .map(async (b) => ({
+         *         type: 'tool_result' as const,
+         *         tool_use_id: b.id,
+         *         content: await executeTool(b.name, b.input as Record<string, unknown>),
+         *       })),
+         *   )
+         *
+         *   messages.push({ role: 'user', content: toolResults })
+         * }
+         * ```
+         */
+        createAnthropicTools: () => Promise<{
+            tools: Anthropic.Tool[];
+            executeTool: (toolName: string, input: Record<string, unknown>) => Promise<string>;
+        }>;
+    }>;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAA;AAG9C,OAAO,CAAC,MAAM,KAAK,CAAA;AAUnB,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,KAAK,GAAG,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC5E,CAAA;AAED,eAAO,MAAM,yBAAyB,oBAAoB,CAAA;AAE1D,eAAO,MAAM,6BAA6B;;;;;iBAKxC,CAAA;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;CAM1B,CAAA;AA2DD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,SAAQ,cAAmB;wBAuBpB;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE;QAS5C;;;;;;;;;;;;;;;;;;;;;WAqBG;;QA6BH;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;+BACwB,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAStD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA8CG;oCAC6B,OAAO,CAAC;YACtC,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,CAAA;YACvB,WAAW,EAAE,CACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,OAAO,CAAC,MAAM,CAAC,CAAA;SACrB,CAAC;;CAyEP,CAAA"}