# ⚡ Konfig MCP Engine

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
[![Tests](https://img.shields.io/badge/Tests-3%2F3%20Passed-brightgreen.svg)](tests/)
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-blue.svg)](package.json)
[![Node Version](https://img.shields.io/badge/Node-%3E%3D20.0.0-brightgreen.svg)](package.json)

> **Enterprise OpenAPI v3.0 / v3.1 to Live Model Context Protocol (MCP) Generator & Tool Bridge.**  
> *Transform existing enterprise Swagger/OpenAPI specifications into typed, agent-ready MCP tools on the fly — zero code, zero boilerplate, zero hallucinated parameters.*

---

## 💡 The Problem

Enterprise architectures run on thousands of REST endpoints documented via OpenAPI / Swagger. However, bringing these APIs to autonomous AI agents (Claude Code, Cursor, Antigravity, AutoGen, CrewAI) currently requires:
1. **Manual Glue Code:** Handcrafting boilerplate MCP servers for each microservice.
2. **Schema Inconsistencies:** Parameter types, headers, and request bodies often get mistranslated, causing LLM tool call failures.
3. **Maintenance Hell:** Every upstream API update breaks hardcoded tool implementations.

**Konfig MCP Engine bridges this gap:** Derived from years of production-grade AST engineering at Konfig (Ex-C3-AI), it dynamically ingests OpenAPI v3.0 and v3.1 specs and transforms them in-memory into fully validated, typed Model Context Protocol tool schemas with zero external dependencies.

---

## ⚡ Key Capabilities

* 🚀 **Instant OpenAPI to MCP Transformation:** Ingests raw OpenAPI JSON objects or files and outputs JSON-RPC 2.0 MCP `tools/list` schemas instantly.
* 🎯 **Strict Schema Mapping:** Maps path parameters, query parameters, headers, and `application/json` request bodies directly to compliant JSON Schema v7 definitions.
* 🪶 **Zero External Dependencies:** Built with pure ECMAScript standard libraries (`node:readline`, `node:fs`). Zero bloat, instant startup, hermetic execution.
* 🛡️ **Anti-Carbonara Architecture:** Clean separation of concerns:
  - `src/core/`: Pure deterministic transformation logic (100% in-memory, no I/O side effects).
  - `src/cli/`: Lightweight command-line interface for pipelines and automation.
  - `src/mcp/`: Native Stdio JSON-RPC 2.0 server for Claude Desktop, Cursor, and Antigravity.
* 🤖 **Autonomous Multi-Agent Friendly:** Agents can dynamically discover API capabilities at runtime by passing any OpenAPI spec into `konfig_transform_openapi`.

---

## 🤖 Model Context Protocol (MCP) Setup

### Add to Claude Desktop / Cursor / Antigravity

Add the engine to your `claude_desktop_config.json` or Antigravity MCP settings:

```json
{
  "mcpServers": {
    "konfig-mcp-engine": {
      "command": "node",
      "args": ["/path/to/konfig_mcp_engine/src/mcp/server.js"]
    }
  }
}
```

Or run via `npx` (when installed from npm):

```json
{
  "mcpServers": {
    "konfig-mcp-engine": {
      "command": "npx",
      "args": ["-y", "konfig-mcp-engine"]
    }
  }
}
```

---

### Available MCP Tools

| Tool Name | Description | Parameters |
| :--- | :--- | :--- |
| `konfig_transform_openapi` | Transforms an OpenAPI 3.0/3.1 specification JSON object into ready-to-call MCP Tool schemas for AI agents. | `spec` (object, required): Parsed OpenAPI v3 spec |

#### Example Tool Invocation

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "konfig_transform_openapi",
    "arguments": {
      "spec": {
        "openapi": "3.0.0",
        "info": { "title": "Petstore API", "version": "1.0.0" },
        "paths": {
          "/pets": {
            "get": {
              "operationId": "listPets",
              "summary": "List all pets",
              "parameters": [
                { "name": "limit", "in": "query", "schema": { "type": "integer" } }
              ]
            }
          }
        }
      }
    }
  }
}
```

---

## 💻 CLI Usage

You can also use Konfig MCP Engine directly from the command line:

```bash
# Generate MCP Tools JSON from an OpenAPI specification
node src/cli/index.js generate path/to/openapi.json
```

Or when installed globally:

```bash
konfig-mcp generate ./swagger.json > mcp-tools.json
```

---

## 🧪 Testing & Verification

Run the hermetic test suite:

```bash
npm test
```

Expected output:
```
▶ Konfig MCP Engine
  ✔ transforms OpenAPI endpoints into MCP tools
  ✔ handles empty or invalid specs gracefully
  ✔ handles MCP handshake, notifications, and ping
✔ Konfig MCP Engine (5ms)
```

---

## 🏛️ Architecture

```
konfig_mcp_engine/
├── src/
│   ├── core/
│   │   ├── transformer.js    # Pure OpenAPI -> MCP Tool AST Transformer
│   │   └── index.js          # Core module export
│   ├── cli/
│   │   └── index.js          # CLI entry point (konfig-mcp)
│   └── mcp/
│       └── server.js         # Stdio JSON-RPC 2.0 MCP Server
├── tests/
│   └── transformer.test.js   # Unit & Integration tests
├── package.json
├── server.json               # MCP Registry Schema
├── smithery.yaml             # Smithery deployment config
└── Dockerfile
```

---

## 📜 Origin & Heritage

This project is part of the **Diamantenschmiede (Pioneer #7)** open-source initiative, refining and advancing abandoned or sunset software into hardened, zero-dependency tools for the modern agentic era.

Based on foundational AST research from `konfig-dev/konfig` (MIT, Copyright (c) 2021-2024 Konfig Inc.).

---

## 📄 License

[MIT](LICENSE) © 2026 tastenkasperle (Diamantenschmiede) & Konfig Inc.