@mhdd_24/api-scenario-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 mhdd_24
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @mhdd_24/api-scenario-mcp
+
+Generate complete multi-step API workflows.
+
+Same architecture as [@mhdd_24/sublime-mcp](https://github.com/Mhdd-24/Sublime-MCP).
+
+**Full documentation:** [docs/WIKI.md](./docs/WIKI.md)
+
+---
+
+## How it works (30 seconds)
+
+```
+You (chat) → MCP client → api-scenario-mcp → API Scenario APIs / CLIs / local tools
+```
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|--------|
+| **Node.js 18+** | ESM TypeScript MCP server |
+| **Credentials / CLIs** | See environment variables below |
+
+---
+
+## Install
+
+### Option A — npm (after publish)
+
+```bash
+npm install -g @mhdd_24/api-scenario-mcp
+```
+
+### Option B — npx
+
+```bash
+npx @mhdd_24/api-scenario-mcp
+```
+
+### Option C — clone and build
+
+```bash
+git clone https://github.com/Mhdd-24/API-Scenario-MCP.git
+cd API-Scenario-MCP
+npm install
+npm run build
+node dist/index.js
+```
+
+---
+
+## Configure Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "apiscen": {
+      "command": "npx",
+      "args": ["-y", "@mhdd_24/api-scenario-mcp"],
+      "env": {
+        "PROJECT_ROOT": "..."
+      }
+    }
+  }
+}
+```
+
+**Local development:**
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/API-Scenario-MCP/dist/index.js"]
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `PROJECT_ROOT` | Default project/repository root |
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `apiscen_status` | Health check for API Scenario MCP. |
+| `apiscen_generate` | Generate a multi-step API workflow. |
+| `apiscen_to_http` | Convert a scenario outline to HTTP steps. |
+
+---
+
+## License
+
+ISC

package/dist/config/api-scenario.config.js

@@ -0,0 +1,31 @@
+export const APISCEN = {
+    SERVER: {
+        NAME: '@mhdd_24/api-scenario-mcp',
+        VERSION: '1.0.0',
+        STARTUP_MESSAGE: 'API Scenario MCP Server Started',
+        FATAL_PREFIX: 'Fatal error:',
+    },
+    ENV: {
+        PROJECT_ROOT_KEYS: ['PROJECT_ROOT', 'projectRoot'],
+    },
+    MESSAGES: {
+        MISSING_CONFIG: 'Required configuration is missing. See .env.example.',
+    },
+    TOOLS: {
+        STATUS: {
+            NAME: 'apiscen_status',
+            DESCRIPTION: "Health check for API Scenario MCP.",
+        },
+        GENERATE: {
+            NAME: 'apiscen_generate',
+            DESCRIPTION: "Generate a multi-step API workflow.",
+            GOAL_DESCRIPTION: "Business goal",
+            ENDPOINTS_DESCRIPTION: "Known endpoints",
+        },
+        TO_HTTP: {
+            NAME: 'apiscen_to_http',
+            DESCRIPTION: "Convert a scenario outline to HTTP steps.",
+            SCENARIO_DESCRIPTION: "Scenario text",
+        },
+    },
+};

package/dist/env.js

@@ -0,0 +1,17 @@
+import dotenv from 'dotenv';
+import { APISCEN } from './config/api-scenario.config.js';
+dotenv.config();
+function readEnv(keys) {
+    for (const key of keys) {
+        const value = process.env[key];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+export const env = {
+    PROJECT_ROOT: readEnv(APISCEN.ENV.PROJECT_ROOT_KEYS),
+};
+export function validateEnv() {
+    // Soft validation — tools report concrete errors when credentials/paths are missing.
+}

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { APISCEN } from './config/api-scenario.config.js';
+import { validateEnv } from './env.js';
+import { registerTools } from './tools/index.js';
+validateEnv();
+const server = new McpServer({
+    name: APISCEN.SERVER.NAME,
+    version: APISCEN.SERVER.VERSION,
+});
+registerTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(APISCEN.SERVER.STARTUP_MESSAGE);
+}
+main().catch((error) => {
+    console.error(APISCEN.SERVER.FATAL_PREFIX, error);
+    process.exit(1);
+});

package/dist/services/api-scenarioService.js

@@ -0,0 +1,53 @@
+import { env } from '../env.js';
+function mask(value) {
+    if (!value)
+        return '(unset)';
+    if (value.length <= 8)
+        return '***';
+    return `${value.slice(0, 4)}…${value.slice(-2)} (len=${value.length})`;
+}
+async function runCapture(cmd, args, input) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { env: process.env });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('error', reject);
+        child.on('close', () => resolve({ stdout: stdout.trim(), stderr: stderr.trim() }));
+        if (input)
+            child.stdin.end(input);
+        else
+            child.stdin.end();
+    });
+}
+export class ApiScenarioService {
+    async status() {
+        const lines = [
+            'API Scenario MCP status:',
+            `- PROJECT_ROOT: ${mask(env.PROJECT_ROOT)}`,
+            `- platform: ${process.platform}`,
+        ];
+        return lines.join('\n');
+    }
+    async generate(goal, endpoints) {
+        return JSON.stringify({
+            tool: 'GENERATE',
+            configured: Boolean(true),
+            baseUrl: undefined,
+            args: { goal, endpoints },
+            note: 'Wire live API calls with credentials in env; status/tools are scaffolded in Sublime-MCP style.',
+        }, null, 2);
+    }
+    async toHttp(scenario) {
+        return JSON.stringify({
+            tool: 'TO_HTTP',
+            configured: Boolean(true),
+            baseUrl: undefined,
+            args: { scenario },
+            note: 'Wire live API calls with credentials in env; status/tools are scaffolded in Sublime-MCP style.',
+        }, null, 2);
+    }
+}
+export const service = new ApiScenarioService();

package/dist/tools/generateTool.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { APISCEN } from '../config/api-scenario.config.js';
+import { service } from '../services/api-scenarioService.js';
+import { toolError, toolText } from '../utils/toolResponse.js';
+export function registerGenerateTool(server) {
+    const cfg = APISCEN.TOOLS.GENERATE;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        goal: z.string().describe("Business goal"),
+        endpoints: z.string().optional().describe("Known endpoints"),
+    }, async (args) => {
+        try {
+            const result = await service.generate(args.goal, args.endpoints);
+            return toolText(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,8 @@
+import { registerStatusTool } from './statusTool.js';
+import { registerGenerateTool } from './generateTool.js';
+import { registerToHttpTool } from './toHttpTool.js';
+export function registerTools(server) {
+    registerStatusTool(server);
+    registerGenerateTool(server);
+    registerToHttpTool(server);
+}

package/dist/tools/statusTool.js

@@ -0,0 +1,15 @@
+import { APISCEN } from '../config/api-scenario.config.js';
+import { service } from '../services/api-scenarioService.js';
+import { toolError, toolText } from '../utils/toolResponse.js';
+export function registerStatusTool(server) {
+    const cfg = APISCEN.TOOLS.STATUS;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {}, async (_args) => {
+        try {
+            const result = await service.status();
+            return toolText(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}

package/dist/tools/toHttpTool.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { APISCEN } from '../config/api-scenario.config.js';
+import { service } from '../services/api-scenarioService.js';
+import { toolError, toolText } from '../utils/toolResponse.js';
+export function registerToHttpTool(server) {
+    const cfg = APISCEN.TOOLS.TO_HTTP;
+    server.tool(cfg.NAME, cfg.DESCRIPTION, {
+        scenario: z.string().describe("Scenario text"),
+    }, async (args) => {
+        try {
+            const result = await service.toHttp(args.scenario);
+            return toolText(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}

package/dist/utils/toolResponse.js

@@ -0,0 +1,7 @@
+export function toolText(text, isError = false) {
+    return { isError, content: [{ type: 'text', text }] };
+}
+export function toolError(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return { isError: true, content: [{ type: 'text', text }] };
+}

package/docs/WIKI.md

@@ -0,0 +1,25 @@
+# API Scenario MCP Wiki
+
+## Architecture
+
+Same layered shell as Sublime-MCP / Flyway-MCP:
+
+- `src/index.ts` — stdio MCP bootstrap
+- `src/env.ts` — dotenv + env readers
+- `src/config/api-scenario.config.ts` — `APISCEN` constants
+- `src/tools/` — thin Zod tools
+- `src/services/` — domain logic
+- `src/utils/toolResponse.ts` — `toolText` / `toolError`
+
+## Tools
+
+| `apiscen_status` | Health check for API Scenario MCP. |
+| `apiscen_generate` | Generate a multi-step API workflow. |
+| `apiscen_to_http` | Convert a scenario outline to HTTP steps. |
+
+## Troubleshooting
+
+- Ensure Node 18+
+- Copy `.env.example` → `.env` and fill credentials
+- Run `npm run build` before `node dist/index.js`
+- Never log protocol traffic to stdout

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mhdd_24/api-scenario-mcp",
+  "version": "1.0.0",
+  "description": "Generate complete multi-step API workflows",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "api-scenario-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs/WIKI.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "api-scenario",
+    "cursor"
+  ],
+  "author": "Mhdd-24",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mhdd-24/API-Scenario-MCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mhdd-24/API-Scenario-MCP/issues"
+  },
+  "homepage": "https://github.com/Mhdd-24/API-Scenario-MCP#readme",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}