Skip to content
Back to search

openapi

OpenAPI definitions, converters and LLM function calling schema composer.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samchon--openapi/badge.svg)](/listings/samchon--openapi)

HTML

<a href="/listings/samchon--openapi"><img src="/api/listings/samchon--openapi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install @samchon/openapi

Transform your OpenAPI document into an LLM function calling application:

import { HttpLlm, OpenApi } from "@samchon/openapi";

// 1. Load and convert your OpenAPI document
const document: OpenApi.IDocument = OpenApi.convert(swagger);

// 2. Generate LLM function calling schemas
const application: IHttpLlmApplication = HttpLlm.application({
  document,
});

// 3. Find a function to call
const func: IHttpLlmFunction | undefined = application.functions.find(
  (f) => f.path === "/bbs/articles" && f.method === "post"
);

// 4. Use with any LLM provider (OpenAI, Claude, Qwen, etc.)
const completion = await llm.chat.completions.create({
  model: "gpt-4o", // or claude-3-5-sonnet, qwen-plus, etc.
  messages: [...],
  tools: [{
    type: "function",
    function: {
      name: func.name,
      description: func.description,
      parameters: func.parameters,
    }
  }],
});

// 5. Execute with validation
const result = await HttpLlm.execute({
  connection: { host: "http://localhost:3000" },
  application,
  function: func,
  input: llmGeneratedArgs,
});

**That's it!** Your HTTP backend is now AI-callable across all major LLM providers.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 557 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # `@samchon/openapi`
  2. > **This repository has been archived and is no longer maintained.**
  3. >
  4. > All functionality has been merged into [`typia`](https://github.com/samchon/typia) as built-in namespace modules.
  5. >
  6. > - OpenAPI → LLM function calling: [`@typia/utils` HTTP LLM](https://typia.io/docs/llm/http/)
  7. > - TypeScript class → LLM function calling: [`typia.llm.application()`](https://typia.io/docs/llm/application/)
  8. > - LLM JSON utilities: [`@typia/utils` LLM JSON](https://typia.io/docs/llm/json/)
  9. > - MCP integration: [`@typia/mcp`](https://typia.io/docs/utilization/mcp/)
  10. > - Vercel AI SDK: [`@typia/vercel`](https://typia.io/docs/utilization/vercel/)
  11. > - LangChain: [`@typia/langchain`](https://typia.io/docs/utilization/langchain/)
  12. ```mermaid
  13. flowchart TB
  14. subgraph "OpenAPI Specification"
  15. v20("Swagger v2.0") --upgrades--> emended[["OpenAPI v3.1 (emended)"]]
  16. v30("OpenAPI v3.0") --upgrades--> emended
  17. v31("OpenAPI v3.1") --emends--> emended
  18. end
  19. subgraph "LLM Function Calling"
  20. emended --normalizes--> migration[["Migration Schema"]]
  21. migration --"AI-Ready"--> schema{{"LLM Function Schema"}}
  22. end
  23. ```
  24. [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/openapi/blob/master/LICENSE)
  25. [![npm version](https://img.shields.io/npm/v/@samchon/openapi.svg)](https://www.npmjs.com/package/@samchon/openapi)
  26. [![Downloads](https://img.shields.io/npm/dm/@samchon/openapi.svg)](https://www.npmjs.com/package/@samchon/openapi)
  27. [![Build Status](https://github.com/samchon/openapi/workflows/build/badge.svg)](https://github.com/samchon/openapi/actions?query=workflow%3Abuild)
  28. [![API Documents](https://img.shields.io/badge/API-Documents-forestgreen)](https://samchon.github.io/openapi/api/)
  29. [![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
  30. **Transform OpenAPI documents into LLM function calling applications.**
  31. `@samchon/openapi` converts OpenAPI/Swagger documents into LLM function calling schemas. With full TypeScript type safety, automatic validation, and support for every OpenAPI version, it's the simplest way to make your HTTP backend AI-callable.
  32. ## Key Features
  33. - **🌐 Multi-Provider Support**: Works with OpenAI, Claude, Qwen, Llama, and other LLM providers
  34. - **📝 Complete OpenAPI Coverage**: Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 fully supported
  35. - **🔒 Type-Safe Validation**: Built-in validation with detailed error feedback for LLM responses
  36. - **🔄 MCP Integration**: Compose function calling schemas from Model Context Protocol servers
  37. - **📊 Emended Specification**: Standardized OpenAPI v3.1 format that removes ambiguities
  38. - **✅ Production Ready**: Battle-tested with 98%+ success rates in real-world LLM applications
  39. **Live Demo:**
  40. > https://github.com/user-attachments/assets/e1faf30b-c703-4451-b68b-2e7a8170bce5
  41. >
  42. > Watch how `@samchon/openapi` powers an AI shopping chatbot with [`@agentica`](https://github.com/wrtnlabs/agentica)
  43. >
  44. > - [View Backend Repository](https://github.com/samchon/shopping-backend)
  45. > - [Explore OpenAPI Document](https://nestia.io/editor/?simulate=true&e2e=true&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsamchon%2Fshopping-backend%2Frefs%2Fheads%2Fmaster%2Fpackages%2Fapi%2Fswagger.json)
  46. ## Quick Start
  47. ```bash
  48. npm install @samchon/openapi
  49. ```
  50. Transform your OpenAPI document into an LLM function calling application:
  51. ```typescript
  52. import { HttpLlm, OpenApi } from "@samchon/openapi";
  53. // 1. Load and convert your OpenAPI document
  54. const document: OpenApi.IDocument = OpenApi.convert(swagger);
  55. // 2. Generate LLM function calling schemas
  56. const application: IHttpLlmApplication = HttpLlm.application({
  57. document,
  58. });
  59. // 3. Find a function to call
  60. const func: IHttpLlmFunction | undefined = application.functions.find(
  61. (f) => f.path === "/bbs/articles" && f.method === "post"
  62. );
  63. // 4. Use with any LLM provider (OpenAI, Claude, Qwen, etc.)
  64. const completion = await llm.chat.completions.create({
  65. model: "gpt-4o", // or claude-3-5-sonnet, qwen-plus, etc.
  66. messages: [...],
  67. tools: [{
  68. type: "function",
  69. function: {
  70. name: func.name,
  71. description: func.description,
  72. parameters: func.parameters,
  73. }
  74. }],
  75. });
  76. // 5. Execute with validation
  77. const result = await HttpLlm.execute({
  78. connection: { host: "http://localhost:3000" },
  79. application,
  80. function: func,
  81. input: llmGeneratedArgs,
  82. });
  83. ```
  84. **That's it!** Your HTTP backend is now AI-callable across all major LLM providers.
  85. ## OpenAPI Definitions
  86. `@samchon/openapi` provides complete TypeScript definitions for all OpenAPI versions and introduces an "emended" OpenAPI v3.1 specification that serves as an intermediate format.
  87. ```mermaid
  88. flowchart TB
  89. v20(Swagger v2.0) --upgrades--> emended[["<b><u>OpenAPI v3.1 (emended)</u></b>"]]
  90. v30(OpenAPI v3.0) --upgrades--> emended
  91. v31(OpenAPI v3.1) --emends--> emended
  92. emended --downgrades--> v20d(Swagger v2.0)
  93. emended --downgrades--> v30d(OpenAPI v3.0)
  94. ```
  95. **Supported Specifications:**
  96. - [Swagger v2.0](https://github.com/samchon/openapi/blob/master/src/SwaggerV2.ts)
  97. - [OpenAPI v3.0](https://github.com/samchon/openapi/blob/master/src/OpenApiV3.ts)
  98. - [OpenAPI v3.1](https://github.com/samchon/openapi/blob/master/src/OpenApiV3_1.ts)
  99. - [**OpenAPI v3.1 (emended)**](https://github.com/samchon/openapi/blob/master/src/OpenApi.ts) - Standardized format
  100. ### What is "Emended" OpenAPI?
  101. The emended specification removes ambiguities and duplications from OpenAPI v3.1, creating a cleaner, more consistent format. All conversions flow through this intermediate format.
  102. **Key Improvements:**
  103. - **Operations**: Merges parameters from path and operation levels, resolves all references
  104. - **JSON Schema**: Eliminates mixed types, unifies nullable handling, standardizes array/tuple representations
  105. - **Schema Composition**: Consolidates `anyOf`, `oneOf`, `allOf` patterns into simpler structures
  106. ### Converting Between Versions
  107. ```typescript
  108. import { OpenApi } from "@samchon/openapi";
  109. // Convert any version to emended format
  110. const emended: OpenApi.IDocument = OpenApi.convert(swagger); // Swagger 2.0/3.0/3.1
  111. // Downgrade to older versions if needed
  112. const v30: OpenApiV3.IDocument = OpenApi.downgrade(emended, "3.0");
  113. const v20: SwaggerV2.IDocument = OpenApi.downgrade(emended, "2.0");
  114. ```
  115. ### Validating OpenAPI Documents
  116. Use `typia` for runtime validation with detailed type checking:
  117. ```typescript
  118. import { OpenApi, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
  119. import typia from "typia";
  120. const document: any = await fetch("swagger.json").then(r => r.json());
  121. // Validate with detailed error messages
  122. const result = typia.validate<
  123. SwaggerV2.IDocument | OpenApiV3.IDocument | OpenApiV3_1.IDocument
  124. >(document);
  125. if (result.success) {
  126. const emended: OpenApi.IDocument = OpenApi.convert(result.data);
  127. } else {
  128. console.error(result.errors); // Detailed validation errors
  129. }
  130. ```
  131. Try it: [Type assertion](https://typia.io/playground/?script=JYWwDg9gTgLgBAbzgeTAUwHYEEzADQrra4BqAzAapjsOQPoCMBAygO4CGA5p2lCQExwAvnABmUCCDgAiAAIBndiADGACwgYA9BCLtc0gNwAoUJFhwYAT1zsxEqdKs3DRo8o3z4IdsAxwAvHDs8pYYynAAFACUAFxwAAr2wPJoADwAbhDAACYAfAH5CEZwcJqacADiAKIAKnAAmsgAqgBKKPFVAHJY8QCScAAiyADCTQCyXTXFcO4YnnBQaPKQc2hxLUsrKQFBHMDwomgwahHTJdKqMDBg8jFlUOysAHSc+6oArgBG7ylQszCYGBPdwgTSKFTqLQ6TB6YCabyeXiaNAADyUYAANktNOkyE8AAzaXTAJ4AK3kGmk0yixhKs3m2QgyneIEBcXYGEsO0ePngi2WHjQZIpGGixmmZTgNXqHTgWGYzCqLRqvWQnWmTmA7CewV+MAq73YUGyqTOcAAPoRqKQyIwnr0BkyWYCzZaqMRaHiHU7WRgYK64GwuDw+Px7Y7mb7-SVchFGZHATTXCVJcM1SQlXUasg4FUJp0BlUBtN6fA0L7smhsnF3TRwz7ATta7hgRp0rwYHGG36k3SPBAsU9fKIIBFy5hK9kk0JjN5fNFgexjqoIvSB0LeBIoDSgA) | [Detailed validation](https://typia.io/playground/?script=JYWwDg9gTgLgBAbzgeTAUwHYEEzADQrra4BqAzAapjsOQPoCMBAygO4CGA5p2lCQExwAvnABmUCCDgAiAAIBndiADGACwgYA9BCLtc0gNwAoUJFhwYAT1zsxEqdKs3DRo8o3z4IdsAxwAvHDs8pYYynAAFACUAFxwAAr2wPJoADwAbhDAACYAfAH5CEZwcJqacADiAKIAKnAAmsgAqgBKKPFVAHJY8QCScAAiyADCTQCyXTXFcO4YnnBQaPKQc2hxLUsrKQFBHMDwomgwahHTJdKqMDBg8jFlUOysAHSc+6oArgBG7ylQszCYGBPdwgTSKFTqLQ6TB6YCabyeXiaNAADyUYAANktNOkyE8AAzaXTAJ4AK3kGmk0yixhKs3m2QgyneIEBcXYGEsO0ePngi2WHjQZIpGGixmmZTgNXqHTgJCwABlegMsDVeshOtN6Xylu8MfBAk5gOwnul2BicuwAakznAAD6EaikMiMJ7KpkswG2h1UYi0PHu5msjAwb1wNhcHh8fhugYe4Ohkq5CKMoOAmnTYCiSL8vVA+TvZTKJbyAL+QKic0pKKIW30iBYp6+UQQCK5-VPXgSKDyDMlEqLGDvKAYWnCVwlSXDDUkKotOo1ZBwKoTToDKoDLUeeBoYPZNDZOK+mix+OAnbH3DAjTpXgwFNnkN9mYeBtC5ut3eYffZDNCYzeL40TAlaJz1o2XbQDSQA)
  132. ## LLM Function Calling
  133. Turn your HTTP backend into an AI-callable service. `@samchon/openapi` converts your OpenAPI document into function calling schemas that work with OpenAI GPT, Claude, Qwen, Llama, and other LLM providers.
  134. **Type Definitions:**
  135. <table>
  136. <thead>
  137. <tr>
  138. <th>Category</th>
  139. <th>Base</th>
  140. <th>HTTP</th>
  141. <th>MCP</th>
  142. </tr>
  143. </thead>
  144. <tbody>
  145. <tr>
  146. <td>Application</td>
  147. <td><a href="https://samchon.github.io/openapi/api/interfaces/ILlmApplication-1.html"><code>ILlmApplication</code></a></td>
  148. <td><a href="https://samchon.github.io/openapi/api/interfaces/IHttpLlmApplication-1.html"><code>IHttpLlmApplication</code></a></td>
  149. <td><a href="https://samchon.github.io/openapi/api/interfaces/IMcpLlmApplication-1.html"><code>IMcpLlmApplication</code></a></td>
  150. </tr>
  151. <tr>
  152. <td>Function</td>
  153. <td><a href="https://samchon.github.io/openapi/api/interfaces/ILlmFunction-1.html"><code>ILlmFunction</code></a></td>
  154. <td><a href="https://samchon.github.io/openapi/api/interfaces/IHttpLlmFunction-1.html"><code>IHttpLlmFunction</code></a></td>
  155. <td><a href="https://samchon.github.io/openapi/api/interfaces/IMcpLlmFunction-1.html"><code>IMcpLlmFunction</code></a></td>
  156. </tr>
  157. <tr>
  158. <td>Parameters</td>
  159. <td colspan="3" align="center"><a href="https://samchon.github.io/openapi/api/interfaces/ILlmSchema.IParameters.html"><code>ILlmSchema.IParameters</code></a></td>
  160. </tr>
  161. <tr>
  162. <td>Schema</td>
  163. <td colspan="3" align="center"><a href="https://samchon.github.io/openapi/api/types/ILlmSchema.html"><code>ILlmSchema</code></a></td>
  164. </tr>
  165. </tbody>
  166. </table>
  167. ### Complete Example
  168. Here's a full example showing LLM function calling with OpenAI (works identically with Claude, Qwen, etc.):
  169. ```typescript
  170. import { HttpLlm, OpenApi, IHttpLlmApplication, IHttpLlmFunction } from "@samchon/openapi";
  171. import OpenAI from "openai";
  172. // 1. Convert OpenAPI to LLM function calling application
  173. const document: OpenApi.IDocument = OpenApi.convert(swagger);
  174. const application: IHttpLlmApplication = HttpLlm.application({
  175. document,
  176. });
  177. // 2. Find the function by path and method
  178. const func: IHttpLlmFunction | undefined = application.functions.find(
  179. (f) => f.path === "/shoppings/sellers/sale" && f.method === "post"
  180. );
  181. if (!func) throw new Error("Function not found");
  182. // 3. Let OpenAI GPT call the function
  183. const client: OpenAI = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  184. const completion: OpenAI.ChatCompletion = await client.chat.completions.create({
  185. model: "gpt-4o",
  186. messages: [
  187. { role: "system", content: "You are a helpful shopping assistant." },
  188. { role: "user", content: "I want to sell Microsoft Surface Pro 9..." }
  189. ],
  190. tools: [{
  191. type: "function",
  192. function: {
  193. name: func.name,
  194. description: func.description,
  195. parameters: func.parameters,
  196. }
  197. }],
  198. });
  199. // 4. Execute the function call on your actual server
  200. const toolCall = completion.choices[0].message.tool_calls![0];
  201. const result = await HttpLlm.execute({
  202. connection: { host: "http://localhost:37001" },
  203. application,
  204. function: func,
  205. input: JSON.parse(toolCall.function.arguments),
  206. });
  207. ```
  208. **Works with Any LLM Provider:**
  209. ```typescript
  210. // OpenAI
  211. const openai = new OpenAI({ apiKey: "..." });
  212. // Anthropic Claude
  213. const anthropic = new Anthropic({ apiKey: "..." });
  214. // Alibaba Qwen via DashScope
  215. const qwen = new OpenAI({
  216. apiKey: "...",
  217. baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
  218. });
  219. // All use the same func.parameters schema
  220. ```
  221. ### Validation Feedback - Fixing LLM Mistakes
  222. **The Problem**: LLMs make type errors. A lot.
  223. Even when your schema says `Array<string>`, GPT might return just `"string"`. In real-world testing with OpenAI GPT-4o-mini on a shopping service:
  224. - **1st attempt**: 70% success rate ❌
  225. - **2nd attempt** (with validation feedback): 98% success rate ✅
  226. - **3rd attempt**: Never failed ✅
  227. **The Solution**: Validate LLM output and send errors back for correction.
  228. ```typescript
  229. import { HttpLlm, IHttpLlmFunction, IValidation } from "@samchon/openapi";
  230. const func: IHttpLlmFunction = application.functions[0];
  231. // Validate LLM-generated arguments
  232. const result: IValidation<unknown> = func.validate(llmArguments);
  233. if (result.success === false) {
  234. // Send detailed error feedback to LLM
  235. return await retryWithFeedback({
  236. message: "Type errors detected. Please correct the arguments.",
  237. errors: result.errors, // Detailed error information
  238. });
  239. } else {
  240. // Execute the validated function
  241. const output = await HttpLlm.execute({
  242. connection: { host: "http://localhost:3000" },
  243. application,
  244. function: func,
  245. input: result.data,
  246. });
  247. return output;
  248. }
  249. ```
  250. The validation uses [`typia.validate<T>()`](https://typia.io/docs/validators/validate), which provides the most accurate validation and extremely detailed error messages compared to other validators:
  251. Components | `typia` | `TypeBox` | `ajv` | `io-ts` | `zod` | `C.V.`
  252. -------------------------|--------|-----------|-------|---------|-------|------------------
  253. **Easy to use** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  254. [Object (simple)](https://github.com/samchon/typia/blob/master/test/src/structures/ObjectSimple.ts) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔
  255. [Object (hierarchical)](https://github.com/samchon/typia/blob/master/test/src/structures/ObjectHierarchical.ts) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔
  256. [Object (recursive)](https://github.com/samchon/typia/blob/master/test/src/structures/ObjectRecursive.ts) | ✔ | ❌ | ✔ | ✔ | ✔ | ✔
  257. [Object (union, implicit)](https://github.com/samchon/typia/blob/master/test/src/structures/ObjectUnionImplicit.ts) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  258. [Object (union, explicit)](https://github.com/samchon/typia/blob/master/test/src/structures/ObjectUnionExplicit.ts) | ✔ | ✔ | ✔ | ✔ | ✔ | ❌
  259. [Object (additional tags)](https://github.com/samchon/#comment-tags) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔
  260. [Object (template literal)](https://github.com/samchon/typia/blob/master/test/src/structures/TemplateUnion.ts) | ✔ | ✔ | ✔ | ❌ | ❌ | ❌
  261. [Object (dynamic properties)](https://github.com/samchon/typia/blob/master/test/src/structures/DynamicTemplate.ts) | ✔ | ✔ | ✔ | ❌ | ❌ | ❌
  262. [Array (rest tuple)](https://github.com/samchon/typia/blob/master/test/src/structures/TupleRestAtomic.ts) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  263. [Array (hierarchical)](https://github.com/samchon/typia/blob/master/test/src/structures/ArrayHierarchical.ts) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔
  264. [Array (recursive)](https://github.com/samchon/typia/blob/master/test/src/structures/ArrayRecursive.ts) | ✔ | ✔ | ✔ | ✔ | ✔ | ❌
  265. [Array (R+U, explicit)](https://github.com/samchon/typia/blob/master/test/src/structures/ArrayRecursiveUnionExplicit.ts) | ✔ | ✔ | ❌ | ✔ | ✔ | ❌
  266. [Array (R+U, implicit)](https://github.com/samchon/typia/blob/master/test/src/structures/ArrayRecursiveUnionImplicit.ts) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  267. [Array (repeated)](https://github.com/samchon/typia/blob/master/test/src/structures/ArrayRepeatedNullable.ts) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  268. [Array (repeated, union)](https://github.com/samchon/typia/blob/master/test/src/structures/ArrayRepeatedUnionWithTuple.ts) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  269. [**Ultimate Union Type**](https://github.com/samchon/typia/blob/master/test/src/structures/UltimateUnion.ts) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌
  270. > `C.V.` means `class-validator`
  271. ### Human-AI Collaboration (Separating Parameters)
  272. Sometimes you need both human input and AI-generated parameters. Use the `separate` option to split parameters between LLM and human:
  273. ```typescript
  274. import { HttpLlm, LlmTypeChecker } from "@samchon/openapi";
  275. const application = HttpLlm.application({
  276. document,
  277. options: {
  278. separate: (schema) =>
  279. LlmTypeChecker.isString(schema) &&
  280. !!schema.contentMediaType?.startsWith("image"),
  281. },
  282. });
  283. const func = application.functions.find(
  284. (f) => f.path === "/shoppings/sellers/sale" && f.method === "post"
  285. )!;
  286. // func.separated.llm - for AI to fill (text, numbers, etc.)
  287. // func.separated.human - for human to provide (file uploads, images)
  288. const result = await HttpLlm.execute({
  289. connection: { host: "http://localhost:37001" },
  290. application,
  291. function: func,
  292. input: HttpLlm.mergeParameters({
  293. function: func,
  294. llm: llmGeneratedArgs,
  295. human: {
  296. content: {
  297. files: [...], // Human provides files
  298. thumbnails: [...], // Human provides images
  299. },
  300. },
  301. }),
  302. });
  303. ```
  304. ## Model Context Protocol
  305. ```mermaid
  306. flowchart TB
  307. subgraph "JSON Schema Specification"
  308. schemav4("JSON Schema v4 ~ v7") --upgrades--> emended[["OpenAPI v3.1 (emended)"]]
  309. schema2910("JSON Schema 2019-03") --upgrades--> emended
  310. schema2020("JSON Schema 2020-12") --emends--> emended
  311. end
  312. subgraph "AI Ecosystem"
  313. emended --normalizes--> migration[["Migration Schema"]]
  314. migration --AI-Ready--> schema{{"LLM Function Schema"}}
  315. schema --supports--> all("All LLM Providers")
  316. end
  317. ```
  318. `@samchon/openapi` provides better MCP function calling than using the [`mcp_servers`](https://openai.github.io/openai-agents-python/mcp/#using-mcp-servers) property directly.
  319. While MCP can execute server functions directly through the `mcp_servers` property, `@samchon/openapi` offers significant advantages through [validation feedback](#validation-feedback---fixing-llm-mistakes) and [selector agent filtering](https://wrtnlabs.io/agentica/docs/concepts/function-calling/#orchestration-strategy) for context optimization.
  320. For example, the GitHub MCP server has 30 functions. Loading all of them via `mcp_servers` creates huge context that often causes AI agents to crash with hallucinations. Function calling with proper filtering avoids this problem.
  321. > https://github.com/user-attachments/assets/72390cb4-d9b1-4d31-a6dd-d866da5a433b
  322. >
  323. > GitHub MCP server via [`mcp_servers`](https://openai.github.io/openai-agents-python/mcp/#using-mcp-servers) often crashes.
  324. >
  325. > However, function calling to GitHub MCP with [`@agentica`](https://github.com/wrtnlabs/agentica) works properly.
  326. >
  327. > - Function calling demo: https://www.youtube.com/watch?v=rLlHkc24cJs
  328. **Creating MCP applications:**
  329. Use [`McpLlm.application()`](https://samchon.github.io/openapi/api/functions/McpLlm.application.html) to create function calling schemas from MCP tools. The returned [`IMcpLlmApplication`](https://samchon.github.io/openapi/api/interfaces/IMcpLlmApplication-1.html) works across all LLM providers and includes validation feedback.
  330. MCP supports all JSON schema specifications:
  331. - JSON Schema v4, v5, v6, v7
  332. - JSON Schema 2019-03
  333. - JSON Schema 2020-12
  334. ```typescript
  335. import { IMcpLlmApplication, IMcpLlmFunction, IValidation, McpLlm } from "@samchon/openapi";
  336. const application: IMcpLlmApplication = McpLlm.application({
  337. tools: [...], // MCP tools
  338. });
  339. const func: IMcpLlmFunction = application.functions.find(
  340. (f) => f.name === "create",
  341. )!;
  342. // Validate with detailed feedback
  343. const result: IValidation<unknown> = func.validate({
  344. title: "Hello World",
  345. body: "Nice to meet you AI developers",
  346. thumbnail: "https://wrtnlabs.io/agentica/thumbnail.jpg",
  347. });
  348. if (result.success) {
  349. // Execute validated function
  350. console.log("Valid arguments:", result.data);
  351. } else {
  352. // Send errors back to LLM for correction
  353. console.error("Validation errors:", result.errors);
  354. }
  355. ```
  356. > [!NOTE]
  357. >
  358. > You can also compose [`ILlmApplication`](https://samchon.github.io/openapi/api/interfaces/ILlmApplication-1.html) from a TypeScript class using `typia`.
  359. >
  360. > https://typia.io/docs/llm/application
  361. >
  362. > ```typescript
  363. > import { ILlmApplication } from "@samchon/openapi";
  364. > import typia from "typia";
  365. >
  366. > const app: ILlmApplication = typia.llm.application<YourClassType>();
  367. > ```
  368. ## Utilization Cases
  369. ### Agentica
  370. [![Agentica](https://wrtnlabs.io/agentica/og.jpg)](https://github.com/wrtnlabs/agentica)
  371. https://github.com/wrtnlabs/agentica
  372. Agentic AI framework that converts OpenAPI documents into LLM function calling schemas. Uses `@samchon/openapi` to transform backend REST APIs into callable functions with automatic parameter validation and type-safe remote execution.
  373. ```typescript
  374. import { Agentica, assertHttpController } from "@agentica/core";
  375. import OpenAI from "openai";
  376. import typia from "typia";
  377. import { MobileFileSystem } from "./services/MobileFileSystem";
  378. const agent = new Agentica({
  379. vendor: {
  380. api: new OpenAI({ apiKey: "********" }),
  381. model: "gpt-4o-mini",
  382. },
  383. controllers: [
  384. // Functions from TypeScript class
  385. typia.llm.controller(
  386. "filesystem",
  387. MobileFileSystem(),
  388. ),
  389. // Functions from Swagger/OpenAPI
  390. // Uses @samchon/openapi under the hood
  391. assertHttpController({
  392. name: "shopping",
  393. document: await fetch(
  394. "https://shopping-be.wrtn.ai/editor/swagger.json",
  395. ).then(r => r.json()),
  396. connection: {
  397. host: "https://shopping-be.wrtn.ai",
  398. headers: { Authorization: "Bearer ********" },
  399. },
  400. }),
  401. ],
  402. });
  403. await agent.conversate("I wanna buy MacBook Pro");
  404. ```
  405. ### AutoBE
  406. [![AutoBE](https://autobe.dev/og.jpg)](https://autobe.dev)
  407. https://autobe.dev
  408. AI backend code generator achieving 100% compilation success by using function calling to construct compiler AST instead of generating code text. For API specification design, uses `@samchon/openapi` types - AI calls compiler functions to build OpenAPI document structures that define REST endpoints and request/response schemas.
  409. ```typescript
  410. import { MicroAgentica } from "@agentica/core";
  411. import { OpenApi } from "@samchon/openapi";
  412. const agent = new MicroAgentica({
  413. vendor: {
  414. api: new OpenAI({ apiKey: "********" }),
  415. model: "gpt-4o-mini",
  416. },
  417. controllers: [
  418. // Compiler functions that receive/produce OpenApi.IDocument
  419. typia.llm.controller(
  420. "api",
  421. new OpenApiWriteApplication(),
  422. ),
  423. ],
  424. });
  425. await agent.conversate("Design API specification and generate backend app.");
  426. class OpenApiWriteApplication {
  427. // LLM calls this function with OpenApi.IDocument structure
  428. public async write(document: OpenApi.IDocument): Promise<void> {
  429. // Compiler validates schema structure before code generation
  430. ...
  431. }
  432. }
  433. ```
  434. ## License
  435. MIT License
  436. Copyright (c) 2024 Jeongho Nam
  437. For detailed API documentation, visit: https://samchon.github.io/openapi/api/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.