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:

How This Library Differs

Development

# Install dependencies
npm install

# Run tests
npm test

# Type check
npm run typecheck

# Build
npm run build

License

MIT