1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Contex convert petstore.yaml to an MCP server" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Contex - OpenAPI to Model Context Protocol Server

A generic TypeScript library for converting OpenAPI specifications into MCP (Model Context Protocol) servers. Built with a purely functional architecture using Ramda.

Features

Generic OpenAPI Conversion: Convert any OpenAPI 3.x specification into a fully functional MCP server
OAuth 2.1 Support: Built-in authentication with PKCE support
Purely Functional: Composable pure functions using Ramda and R.pipe()
Type-Safe: Full TypeScript support with Result monad for error handling
Extensible: Easy to add custom tools and resources
Well-Tested: 100% unit test coverage target

Installation

npm install contex zod

Quick Start

import { createMcpServer, isOk } from 'contex';

const result = await createMcpServer({
  name: 'My API Server',
  version: '1.0.0',
  openApiSpec: './openapi.yaml',
  baseUrl: 'https://api.example.com',
});

if (isOk(result)) {
  await result.value.start();
  console.log('MCP server running on port 3000');
}

With OAuth Authentication

import { createMcpServer, isOk } from 'contex';

const result = await createMcpServer({
  name: 'Secure API Server',
  version: '1.0.0',
  openApiSpec: './openapi.yaml',
  baseUrl: 'https://api.example.com',
  auth: {
    type: 'oauth2',
    clientId: process.env.CLIENT_ID,
    clientSecret: process.env.CLIENT_SECRET,
    authorizationUrl: 'https://auth.example.com/authorize',
    tokenUrl: 'https://auth.example.com/token',
    scopes: ['read', 'write'],
    pkce: true, // Enabled by default
  },
  server: {
    port: 3000,
    transport: 'streamable-http',
  },
});

if (isOk(result)) {
  await result.value.start();
}

API Overview

Main Functions

createMcpServer(config) - Create MCP server from OpenAPI spec
createCustomMcpServer(name, version, tools, resources) - Create server with custom tools

Result Type

The library uses a Result<T, E> monad for error handling:

import { isOk, isErr, fold, formatError } from 'contex';

const result = await createMcpServer(config);

// Pattern matching with type guards
if (isOk(result)) {
  const server = result.value;
} else {
  console.error(formatError(result.error));
}

// Or use fold
const server = fold(
  (error) => { console.error(error); return null; },
  (server) => server
)(result);

Tool and Resource Generation

import {
  parseOpenApiSpec,
  extractOperations,
  buildToolsPipeline,
  buildResourcesPipeline,
} from 'contex';

// Parse OpenAPI spec
const specResult = await parseOpenApiSpec('./openapi.yaml');

if (isOk(specResult)) {
  const spec = specResult.value;
  
  // Extract operations
  const operations = extractOperations(spec);
  
  // Build tools
  const tools = buildToolsPipeline('https://api.example.com')(operations);
  
  // Build resources
  const resources = buildResourcesPipeline(spec);
}

Architecture

See docs/ARCHITECTURE.md for details.

Documentation

API Reference - Complete API documentation
Architecture Guide - Design principles and patterns
Examples - Usage examples and patterns

Examples

See the examples/ directory for complete examples:

basic-server.ts - Basic MCP server from OpenAPI
with-oauth.ts - Server with OAuth authentication
custom-tools.ts - Server with custom tool definitions

Existing Alternatives

Several similar libraries exist in the ecosystem:

Library	Description
openapi-mcpserver-generator	Generates MCP server code from OpenAPI specs
openapi-mcp-generator	TypeScript tool for OpenAPI → MCP conversion
openapi-to-mcp-converter	Automatic OpenAPI to MCP Server conversion
openapi-mcp-server	Bridge between OpenAPI and MCP for Claude Desktop
api-to-mcp	Turn any API into MCP tools
Stainless	Commercial platform for MCP server generation
Speakeasy	Commercial tool for generating MCP servers

How This Library Differs

Feature	Existing Tools	This Library
Architecture	Mostly imperative/OOP	Purely functional
Error Handling	Exceptions	Result monad
OAuth Support	Limited/varies	Full OAuth 2.1 + PKCE
Runtime	Code generation	Runtime conversion
Composability	Low	High (`R.pipe`)

Development

# Install dependencies
npm install

# Run tests
npm test

# Type check
npm run typecheck

# Build
npm run build

License

MIT

Contex