Contex

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