@stackkedjohn/mcp-factory-cli 0.1.2 → 0.2.0

package/README.md

@@ -25,6 +25,7 @@ npm install -g @stackkedjohn/mcp-factory-cli
 
 ```bash
 # Generate MCP server from API documentation
+# Supports: OpenAPI, Swagger, API Blueprint (.apib)
 mcp-factory create ./api-docs.yaml
 
 # Build the generated server
@@ -103,6 +104,7 @@ Options:
 **Supported Formats:**
 - OpenAPI 3.x (JSON/YAML)
 - Swagger 2.0 (JSON/YAML)
+- API Blueprint (.apib)
 - Postman Collections (coming soon)
 - Unstructured docs with `--ai-parse` (coming soon)
 
@@ -111,6 +113,9 @@ Options:
 # Local file
 mcp-factory create ./openapi.yaml
 
+# API Blueprint file
+mcp-factory create ./api-documentation.apib
+
 # URL (coming soon)
 mcp-factory create https://api.example.com/openapi.json
 

package/dist/commands/create.js

@@ -2,6 +2,7 @@ import * as path from 'path';
 import { detectFormat } from '../parsers/detector.js';
 import { parseOpenAPI } from '../parsers/openapi.js';
 import { parsePostman } from '../parsers/postman.js';
+import { parseAPIBlueprint } from '../parsers/apib-parser.js';
 import { parseWithAI } from '../parsers/ai-parser.js';
 import { analyzePatterns } from '../generator/analyzer.js';
 import { generateServer } from '../generator/engine.js';
@@ -22,6 +23,9 @@ export async function createCommand(input, options) {
         else if (detection.format === 'postman') {
             schema = parsePostman(detection.content);
         }
+        else if (detection.format === 'apib') {
+            schema = await parseAPIBlueprint(detection.content);
+        }
         else if (options.aiParse) {
             logger.info('Using AI parser for unstructured docs...');
             schema = await parseWithAI(JSON.stringify(detection.content));

package/dist/parsers/apib-parser.d.ts

@@ -0,0 +1,2 @@
+import type { APISchema } from '../schema/api-schema.js';
+export declare function parseAPIBlueprint(content: string): Promise<APISchema>;

package/dist/parsers/apib-parser.js

@@ -0,0 +1,354 @@
+import drafterModule from 'drafter.js';
+import { ParseError } from '../utils/errors.js';
+// Type assertion for drafter.js API (type definitions are incomplete)
+const drafter = drafterModule;
+// Helper to check if element has a class
+function hasClass(element, className) {
+    if (!element?.meta?.classes)
+        return false;
+    if (element.meta.classes.element === 'array') {
+        return element.meta.classes.content.some((c) => c.content === className);
+    }
+    return false;
+}
+export async function parseAPIBlueprint(content) {
+    try {
+        // Parse the API Blueprint document using drafter.js (synchronous)
+        const result = drafter.parseSync(content, {});
+        // Check for parsing errors
+        if (result.error) {
+            throw new ParseError(`API Blueprint parsing failed: ${result.error.message}`);
+        }
+        const ast = result;
+        // Extract API metadata
+        const apiMetadata = ast.content[0];
+        const name = apiMetadata.meta?.title?.content || 'Untitled API';
+        const baseUrl = extractBaseUrl(ast);
+        // Extract all endpoints
+        const endpoints = [];
+        for (const resourceGroup of ast.content) {
+            if (resourceGroup.element === 'category' && hasClass(resourceGroup, 'resourceGroup')) {
+                for (const resource of resourceGroup.content) {
+                    if (resource.element === 'resource') {
+                        const resourcePath = resource.attributes?.href?.content || '';
+                        for (const transition of resource.content) {
+                            if (transition.element === 'transition') {
+                                const transaction = transition.content.find((c) => c.element === 'httpTransaction');
+                                if (transaction) {
+                                    const endpoint = parseAction(transaction, resourcePath, transition);
+                                    endpoints.push(endpoint);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Also check for resources at the top level (like in api category)
+            if (resourceGroup.element === 'category' && hasClass(resourceGroup, 'api')) {
+                for (const item of resourceGroup.content) {
+                    if (item.element === 'resource') {
+                        const resourcePath = item.attributes?.href?.content || '';
+                        for (const transition of item.content) {
+                            if (transition.element === 'transition') {
+                                const transaction = transition.content.find((c) => c.element === 'httpTransaction');
+                                if (transaction) {
+                                    const endpoint = parseAction(transaction, resourcePath, transition);
+                                    endpoints.push(endpoint);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Also check for resources at the very top level
+            if (resourceGroup.element === 'resource') {
+                const resourcePath = resourceGroup.attributes?.href?.content || '';
+                for (const transition of resourceGroup.content) {
+                    if (transition.element === 'transition') {
+                        const transaction = transition.content.find((c) => c.element === 'httpTransaction');
+                        if (transaction) {
+                            const endpoint = parseAction(transaction, resourcePath, transition);
+                            endpoints.push(endpoint);
+                        }
+                    }
+                }
+            }
+        }
+        // Detect authentication
+        const auth = detectAuth(ast);
+        return {
+            name,
+            baseUrl,
+            auth,
+            endpoints,
+        };
+    }
+    catch (error) {
+        if (error instanceof ParseError) {
+            throw error;
+        }
+        throw new ParseError(`Failed to parse API Blueprint: ${error.message}`);
+    }
+}
+function extractBaseUrl(ast) {
+    // Look for HOST in metadata within category
+    for (const element of ast.content) {
+        if (element.element === 'category' && hasClass(element, 'api')) {
+            // Check attributes.metadata array
+            if (element.attributes?.metadata?.element === 'array') {
+                for (const metaItem of element.attributes.metadata.content) {
+                    if (metaItem.element === 'member') {
+                        const key = metaItem.content?.key?.content;
+                        if (key === 'HOST') {
+                            return metaItem.content.value.content;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return 'https://api.example.com';
+}
+function parseAction(transaction, resourcePath, transition) {
+    const request = transaction.content.find((c) => c.element === 'httpRequest');
+    const response = transaction.content.find((c) => c.element === 'httpResponse');
+    const method = (request?.attributes?.method?.content || 'GET').toUpperCase();
+    const path = request?.attributes?.href?.content || resourcePath;
+    // Extract description - check transition's copy element first, then meta.title
+    let description = '';
+    const copyElement = transition.content.find((c) => c.element === 'copy');
+    if (copyElement?.content) {
+        description = copyElement.content;
+    }
+    else if (transition.meta?.title?.content) {
+        description = transition.meta.title.content;
+    }
+    else if (transaction.meta?.title?.content) {
+        description = transaction.meta.title.content;
+    }
+    else if (request?.meta?.title?.content) {
+        description = request.meta.title.content;
+    }
+    // Parse parameters
+    const parameters = parseParameters(request);
+    // Parse request body
+    const requestBody = parseRequestBody(request);
+    // Parse response
+    const responseSchema = parseResponse(response);
+    // Parse errors (look for non-2xx responses)
+    const errors = parseErrors(transaction);
+    const id = `${method.toLowerCase()}-${path.replace(/\//g, '-').replace(/[{}]/g, '')}`;
+    return {
+        id,
+        method,
+        path,
+        description,
+        parameters,
+        requestBody,
+        response: responseSchema,
+        errors,
+    };
+}
+function parseParameters(request) {
+    const parameters = [];
+    if (!request?.attributes?.hrefVariables) {
+        return parameters;
+    }
+    const hrefVariables = request.attributes.hrefVariables.content;
+    for (const variable of hrefVariables) {
+        if (variable.element === 'member') {
+            const name = variable.content.key.content;
+            const description = variable.meta?.description?.content || '';
+            const required = variable.attributes?.typeAttributes?.includes('required') || false;
+            // Determine parameter location
+            let location = 'path';
+            if (variable.attributes?.typeAttributes?.includes('query')) {
+                location = 'query';
+            }
+            else if (variable.attributes?.typeAttributes?.includes('header')) {
+                location = 'header';
+            }
+            const schema = mapTypeToSchemaType(variable.content.value.element);
+            parameters.push({
+                name,
+                in: location,
+                description,
+                required,
+                schema,
+            });
+        }
+    }
+    return parameters;
+}
+function parseRequestBody(request) {
+    if (!request?.content) {
+        return undefined;
+    }
+    const asset = request.content.find((c) => c.element === 'asset');
+    if (!asset) {
+        return undefined;
+    }
+    const contentType = asset.attributes?.contentType?.content || 'application/json';
+    const bodyContent = asset.content;
+    // Try to parse body as JSON to infer schema
+    let schema = { type: 'object' };
+    if (bodyContent) {
+        try {
+            const parsed = JSON.parse(bodyContent);
+            schema = inferSchemaFromValue(parsed);
+        }
+        catch {
+            // If not JSON, keep as generic object
+            schema = { type: 'object' };
+        }
+    }
+    return {
+        required: true,
+        contentType,
+        schema,
+    };
+}
+function parseResponse(response) {
+    const statusCode = parseInt(response?.attributes?.statusCode?.content || '200');
+    const description = response?.meta?.title?.content || '';
+    let contentType = 'application/json';
+    let schema = { type: 'object' };
+    if (response?.content) {
+        const asset = response.content.find((c) => c.element === 'asset');
+        if (asset) {
+            contentType = asset.attributes?.contentType?.content || 'application/json';
+            const bodyContent = asset.content;
+            if (bodyContent) {
+                try {
+                    const parsed = JSON.parse(bodyContent);
+                    schema = inferSchemaFromValue(parsed);
+                }
+                catch {
+                    schema = { type: 'object' };
+                }
+            }
+        }
+    }
+    return {
+        statusCode,
+        description,
+        contentType,
+        schema,
+    };
+}
+function parseErrors(transaction) {
+    const errors = [];
+    if (!transaction?.content) {
+        return errors;
+    }
+    for (const item of transaction.content) {
+        if (item.element === 'httpResponse') {
+            const statusCode = parseInt(item.attributes?.statusCode?.content || '200');
+            // Only include error responses (4xx and 5xx)
+            if (statusCode >= 400) {
+                const description = item.meta?.title?.content || `Error ${statusCode}`;
+                let schema;
+                const asset = item.content?.find((c) => c.element === 'asset');
+                if (asset?.content) {
+                    try {
+                        const parsed = JSON.parse(asset.content);
+                        schema = inferSchemaFromValue(parsed);
+                    }
+                    catch {
+                        schema = { type: 'object' };
+                    }
+                }
+                errors.push({
+                    statusCode,
+                    description,
+                    schema,
+                });
+            }
+        }
+    }
+    return errors;
+}
+function detectAuth(ast) {
+    // Convert AST to string for pattern matching
+    const astString = JSON.stringify(ast);
+    // Look for common authentication patterns
+    if (astString.includes('Authorization') || astString.includes('bearer')) {
+        return {
+            type: 'bearer',
+            location: 'header',
+            name: 'Authorization',
+            description: 'Bearer token authentication',
+        };
+    }
+    if (astString.includes('api-key') || astString.includes('apiKey') || astString.includes('X-API-Key')) {
+        return {
+            type: 'api-key',
+            location: 'header',
+            name: 'X-API-Key',
+            description: 'API key authentication',
+        };
+    }
+    if (astString.includes('oauth') || astString.includes('OAuth')) {
+        return {
+            type: 'oauth',
+            description: 'OAuth 2.0 authentication',
+        };
+    }
+    if (astString.includes('Basic')) {
+        return {
+            type: 'basic',
+            description: 'Basic authentication',
+        };
+    }
+    return {
+        type: 'none',
+    };
+}
+function mapTypeToSchemaType(element) {
+    switch (element) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'array':
+            return { type: 'array', items: { type: 'object' } };
+        case 'object':
+            return { type: 'object' };
+        default:
+            return { type: 'string' };
+    }
+}
+function inferSchemaFromValue(value) {
+    if (Array.isArray(value)) {
+        const itemSchema = value.length > 0 ? inferSchemaFromValue(value[0]) : { type: 'object' };
+        return {
+            type: 'array',
+            items: itemSchema,
+        };
+    }
+    if (typeof value === 'object' && value !== null) {
+        const properties = {};
+        const required = [];
+        for (const [key, val] of Object.entries(value)) {
+            properties[key] = inferSchemaFromValue(val);
+            required.push(key);
+        }
+        return {
+            type: 'object',
+            properties,
+            required,
+        };
+    }
+    if (typeof value === 'string') {
+        return { type: 'string' };
+    }
+    if (typeof value === 'number') {
+        return { type: 'number' };
+    }
+    if (typeof value === 'boolean') {
+        return { type: 'boolean' };
+    }
+    return { type: 'object' };
+}

package/dist/parsers/apib-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/parsers/apib-parser.test.js

@@ -0,0 +1,59 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseAPIBlueprint } from './apib-parser.js';
+describe('API Blueprint Parser', () => {
+    it('should parse a basic API Blueprint document', async () => {
+        const apibContent = `
+FORMAT: 1A
+HOST: https://api.example.com
+
+# My API
+This is my API description.
+
+## GET /users
+Get a list of users
+
++ Response 200 (application/json)
+    + Body
+
+            [
+              {
+                "id": 1,
+                "name": "John Doe"
+              }
+            ]
+
+## POST /users
+Create a new user
+
++ Request (application/json)
+    + Body
+
+            {
+              "name": "John Doe"
+            }
+
++ Response 201 (application/json)
+    + Body
+
+            {
+              "id": 1,
+              "name": "John Doe"
+            }
+`;
+        const schema = await parseAPIBlueprint(apibContent);
+        assert.strictEqual(schema.name, 'My API');
+        assert.strictEqual(schema.baseUrl, 'https://api.example.com');
+        assert.strictEqual(schema.endpoints.length, 2);
+        // Check GET endpoint
+        const getEndpoint = schema.endpoints.find((e) => e.method === 'GET');
+        assert.ok(getEndpoint);
+        assert.strictEqual(getEndpoint.path, '/users');
+        assert.strictEqual(getEndpoint.description, 'Get a list of users');
+        // Check POST endpoint
+        const postEndpoint = schema.endpoints.find((e) => e.method === 'POST');
+        assert.ok(postEndpoint);
+        assert.strictEqual(postEndpoint.path, '/users');
+        assert.strictEqual(postEndpoint.description, 'Create a new user');
+    });
+});

package/dist/parsers/detector.d.ts

@@ -1,4 +1,4 @@
-export type InputFormat = 'openapi' | 'swagger' | 'postman' | 'unknown';
+export type InputFormat = 'openapi' | 'swagger' | 'postman' | 'apib' | 'unknown';
 export interface DetectionResult {
     format: InputFormat;
     content: any;

package/dist/parsers/detector.js

@@ -10,6 +10,14 @@ export async function detectFormat(input) {
     catch {
         throw new ParseError(`Could not read file: ${input}`);
     }
+    // Check file extension for API Blueprint
+    if (input.endsWith('.apib') || input.endsWith('.apiblueprint')) {
+        return { format: 'apib', content };
+    }
+    // Alternatively, check content for API Blueprint markers
+    if (content.trim().startsWith('FORMAT: 1A')) {
+        return { format: 'apib', content };
+    }
     // Try parsing as JSON
     let parsed;
     try {

package/dist/parsers/detector.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/parsers/detector.test.js

@@ -0,0 +1,20 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { detectFormat } from './detector.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+describe('Format Detector', () => {
+    it('should detect API Blueprint format from .apib file', async () => {
+        // Create temp .apib file
+        const tempFile = path.join(process.cwd(), 'test.apib');
+        await fs.writeFile(tempFile, 'FORMAT: 1A\n# My API\n## GET /users', 'utf-8');
+        try {
+            const result = await detectFormat(tempFile);
+            assert.strictEqual(result.format, 'apib');
+            assert.ok(result.content.includes('FORMAT: 1A'));
+        }
+        finally {
+            await fs.unlink(tempFile);
+        }
+    });
+});