@friehub/blueprint 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { loadCatalogFromRoot } from "../core/load-catalog.js";
+import { resolve as resolveDeps, detectCycles } from "../core/resolve.js";
+import { searchModules } from "../core/search.js";
+import { loadAdapters } from "../core/adapters/load.js";
+const ROOT_DIR = process.env.BLUEPRINT_ROOT || process.cwd();
+const server = new Server({ name: "engineering-blueprint", version: "0.1.0" }, { capabilities: { tools: {} } });
+let catalog = null;
+let adapters = [];
+async function loadData() {
+    if (!catalog) {
+        const result = await loadCatalogFromRoot(ROOT_DIR, "loose");
+        catalog = result.value;
+        const adapterResult = await loadAdapters(`${ROOT_DIR}/adapters`);
+        adapters = adapterResult.adapters;
+    }
+}
+function moduleSummary(m) {
+    return {
+        name: m.name,
+        version: m.version,
+        functionCount: m.functions.length,
+        hardDeps: m.hardDeps,
+        softDeps: m.softDeps,
+        coreInherits: m.coreInherits,
+    };
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "list_modules",
+            description: "List all available module contracts (108 modules)",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "get_module",
+            description: "Get the full contract for a module including functions, types, and dependencies",
+            inputSchema: {
+                type: "object",
+                properties: { name: { type: "string", description: "Module name (e.g., payments, billing, auth)" } },
+                required: ["name"],
+            },
+        },
+        {
+            name: "search_modules",
+            description: "Search modules by name, summary, or function name",
+            inputSchema: {
+                type: "object",
+                properties: { query: { type: "string", description: "Search query" } },
+                required: ["query"],
+            },
+        },
+        {
+            name: "resolve_deps",
+            description: "Resolve a set of modules with all transitive dependencies",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    modules: { type: "array", items: { type: "string" }, description: "Module names to resolve" },
+                },
+                required: ["modules"],
+            },
+        },
+        {
+            name: "list_adapters",
+            description: "List available adapters (83 adapters across 35 modules)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    module: { type: "string", description: "Optional: filter by module name" },
+                },
+            },
+        },
+        {
+            name: "get_adapter",
+            description: "Get adapter details including config requirements",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    module: { type: "string", description: "Module name" },
+                    provider: { type: "string", description: "Adapter provider name (e.g., stripe, redis)" },
+                },
+                required: ["module", "provider"],
+            },
+        },
+        {
+            name: "get_dependency_graph",
+            description: "Get dependency graph (hard deps, soft deps) for a module",
+            inputSchema: {
+                type: "object",
+                properties: { module: { type: "string", description: "Module name" } },
+                required: ["module"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    await loadData();
+    const { name, arguments: args } = request.params;
+    const input = (args || {});
+    try {
+        switch (name) {
+            case "list_modules": {
+                const modules = (catalog?.modules || []).map(moduleSummary);
+                return { content: [{ type: "text", text: JSON.stringify({ total: modules.length, modules }, null, 2) }] };
+            }
+            case "get_module": {
+                const modName = input.name;
+                const mod = catalog?.modules.find((m) => m.name === modName);
+                if (!mod)
+                    return { content: [{ type: "text", text: `Module "${modName}" not found` }] };
+                return { content: [{ type: "text", text: JSON.stringify(mod, null, 2) }] };
+            }
+            case "search_modules": {
+                const query = input.query;
+                const results = searchModules(catalog, query);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                query,
+                                total: results.length,
+                                results: results.slice(0, 10).map((r) => ({
+                                    name: r.module.name,
+                                    score: r.score,
+                                    matchType: r.matchType,
+                                    summary: r.module.summary,
+                                })),
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "resolve_deps": {
+                const modules = input.modules || [];
+                const cycles = detectCycles(catalog);
+                if (cycles.length > 0) {
+                    return { content: [{ type: "text", text: JSON.stringify({ error: "Cycles detected", cycles }) }] };
+                }
+                const resolved = resolveDeps(catalog, modules);
+                return { content: [{ type: "text", text: JSON.stringify(resolved, null, 2) }] };
+            }
+            case "list_adapters": {
+                const modName = input.module;
+                const filtered = modName ? adapters.filter((a) => a.module === modName) : adapters;
+                const grouped = {};
+                for (const a of filtered) {
+                    const mod = a.module;
+                    if (!grouped[mod])
+                        grouped[mod] = [];
+                    grouped[mod].push(a.name);
+                }
+                return { content: [{ type: "text", text: JSON.stringify(grouped, null, 2) }] };
+            }
+            case "get_adapter": {
+                const modName = input.module;
+                const provider = input.provider;
+                const adapter = adapters.find((a) => a.module === modName && a.name === provider);
+                if (!adapter)
+                    return { content: [{ type: "text", text: `Adapter "${provider}" not found for module "${modName}"` }] };
+                return { content: [{ type: "text", text: JSON.stringify(adapter, null, 2) }] };
+            }
+            case "get_dependency_graph": {
+                const modName = input.module;
+                const mod = catalog?.modules.find((m) => m.name === modName);
+                if (!mod)
+                    return { content: [{ type: "text", text: `Module "${modName}" not found` }] };
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                module: modName,
+                                hardDeps: mod.hardDeps,
+                                softDeps: mod.softDeps,
+                                coreInherits: mod.coreInherits,
+                                recommends: mod.softDeps,
+                                requiredBy: catalog?.modules.filter((m) => m.hardDeps.includes(modName)).map((m) => m.name),
+                                softDepsOf: catalog?.modules.filter((m) => m.softDeps.includes(modName)).map((m) => m.name),
+                            }, null, 2),
+                        }],
+                };
+            }
+            default:
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+        }
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }] };
+    }
+});
+async function startMCP() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Engineering Blueprinter MCP server running on stdio");
+    console.error(`Root directory: ${ROOT_DIR}`);
+}
+startMCP().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+});

package/dist/mcp/server.test.js

@@ -0,0 +1,136 @@
+import { strict as assert } from "node:assert";
+import { describe, it, before, after } from "node:test";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+const ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const SERVER_PATH = join(ROOT, "dist", "mcp", "server.js");
+function sendRequest(proc, request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const timeout = setTimeout(() => {
+            proc.kill();
+            reject(new Error("Timeout waiting for response"));
+        }, 15000);
+        proc.stdout.on("data", (chunk) => {
+            chunks.push(chunk);
+            const text = Buffer.concat(chunks).toString("utf8");
+            if (text.includes("}")) {
+                clearTimeout(timeout);
+                resolve(text);
+            }
+        });
+        proc.stderr.on("data", () => { });
+        proc.stdin.write(JSON.stringify(request) + "\n");
+    });
+}
+describe("MCP server", () => {
+    let server;
+    before(() => {
+        server = spawn("node", [SERVER_PATH], {
+            env: { ...process.env, BLUEPRINT_ROOT: ROOT },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    });
+    after(() => {
+        if (server && !server.killed)
+            server.kill();
+    });
+    it("responds to tools/list", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/list",
+            params: {},
+        });
+        const json = JSON.parse(response);
+        assert.ok(json.result, "should have result");
+        assert.ok(json.result.tools, "should have tools array");
+        assert.ok(json.result.tools.length >= 7, "should have at least 7 tools");
+    });
+    it("responds to list_modules", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 2,
+            method: "tools/call",
+            params: { name: "list_modules", arguments: {} },
+        });
+        const json = JSON.parse(response);
+        const content = JSON.parse(json.result.content[0].text);
+        assert.ok(content.total >= 100, "should have 108 modules");
+        assert.ok(content.modules.length >= 100);
+    });
+    it("responds to get_module for payments", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 3,
+            method: "tools/call",
+            params: { name: "get_module", arguments: { name: "payments" } },
+        });
+        const json = JSON.parse(response);
+        const content = JSON.parse(json.result.content[0].text);
+        assert.equal(content.name, "payments");
+        assert.ok(content.functions.length >= 10);
+    });
+    it("returns error for unknown module", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 4,
+            method: "tools/call",
+            params: { name: "get_module", arguments: { name: "nonexistent" } },
+        });
+        const json = JSON.parse(response);
+        const text = json.result.content[0].text;
+        assert.ok(text.includes("not found") || text.includes("Not found"));
+    });
+    it("responds to search_modules", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 5,
+            method: "tools/call",
+            params: { name: "search_modules", arguments: { query: "payment" } },
+        });
+        const json = JSON.parse(response);
+        const content = JSON.parse(json.result.content[0].text);
+        assert.ok(content.total > 0);
+        assert.ok(content.results.some((r) => r.name === "payments"));
+    });
+    it("responds to resolve_deps", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 6,
+            method: "tools/call",
+            params: { name: "resolve_deps", arguments: { modules: ["billing"] } },
+        });
+        const json = JSON.parse(response);
+        const content = JSON.parse(json.result.content[0].text);
+        assert.ok(content.modules.length > 0);
+        assert.ok(content.modules.some((m) => m.name === "billing"));
+        assert.ok(content.modules.some((m) => m.name === "payments"));
+    });
+    it("responds to list_adapters", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 7,
+            method: "tools/call",
+            params: { name: "list_adapters", arguments: { module: "payments" } },
+        });
+        const json = JSON.parse(response);
+        const content = JSON.parse(json.result.content[0].text);
+        assert.ok(content.payments, "should have payments adapters");
+        assert.ok(content.payments.includes("stripe"));
+    });
+    it("responds to get_adapter", { timeout: 15000 }, async () => {
+        const response = await sendRequest(server, {
+            jsonrpc: "2.0",
+            id: 8,
+            method: "tools/call",
+            params: { name: "get_adapter", arguments: { module: "payments", provider: "stripe" } },
+        });
+        const json = JSON.parse(response);
+        const content = JSON.parse(json.result.content[0].text);
+        assert.equal(content.name, "stripe");
+        assert.equal(content.module, "payments");
+        assert.ok(content.config.required.length > 0);
+    });
+});

package/dist/utils/args.js

@@ -0,0 +1,142 @@
+const KNOWN_FLAGS = new Set(["--root", "--strict", "--help", "-h", "--version", "-v", "--output", "--modules", "--format", "--compact", "--quiet", "--module", "--lang", "--name", "--minimal", "--prompts", "--adapter"]);
+const COMMANDS = new Set(["build", "resolve", "list", "inspect", "graph", "search", "adapters", "generate", "prototype", "schema", "verify", "implement", "mcp"]);
+const ADAPTER_SUBCOMMANDS = new Set(["list", "add", "remove", "show", "verify", "search"]);
+const GENERATE_SUBCOMMANDS = new Set(["interfaces", "adapters", "tests", "all"]);
+const LANGUAGES = new Set(["typescript", "rust", "python", "go"]);
+export function parseArguments(args) {
+    const parsed = {
+        command: "build",
+        adapterSubcommand: undefined,
+        generateSubcommand: undefined,
+        root: undefined,
+        strict: undefined,
+        help: undefined,
+        version: undefined,
+        output: undefined,
+        modules: [],
+        target: undefined,
+        query: undefined,
+        provider: undefined,
+        module: undefined,
+        language: undefined,
+        format: "ascii",
+        compact: false,
+        quiet: false,
+        minimal: false,
+        prompts: false,
+        unknown: [],
+    };
+    let i = 0;
+    if (i < args.length && !args[i].startsWith("-") && COMMANDS.has(args[i])) {
+        parsed.command = args[i];
+        i++;
+    }
+    if (parsed.command === "adapters" && i < args.length && !args[i].startsWith("-") && ADAPTER_SUBCOMMANDS.has(args[i])) {
+        parsed.adapterSubcommand = args[i];
+        i++;
+    }
+    if (parsed.command === "generate" && i < args.length && !args[i].startsWith("-") && GENERATE_SUBCOMMANDS.has(args[i])) {
+        parsed.generateSubcommand = args[i];
+        i++;
+    }
+    if (parsed.command === "adapters" && parsed.adapterSubcommand === "add" && i < args.length && !args[i].startsWith("-")) {
+        parsed.provider = args[i];
+        i++;
+        if (i < args.length && !args[i].startsWith("-")) {
+            parsed.module = args[i];
+            i++;
+        }
+    }
+    if (parsed.command === "adapters" && parsed.adapterSubcommand === "remove" && i < args.length && !args[i].startsWith("-")) {
+        parsed.module = args[i];
+        i++;
+    }
+    if (parsed.command === "adapters" && (parsed.adapterSubcommand === "list" || parsed.adapterSubcommand === "verify" || parsed.adapterSubcommand === "search") && i < args.length && !args[i].startsWith("-")) {
+        parsed.query = args[i];
+        i++;
+    }
+    if (parsed.command === "generate" && i < args.length && !args[i].startsWith("-")) {
+        parsed.provider = args[i];
+        i++;
+        if (i < args.length && !args[i].startsWith("-")) {
+            parsed.module = args[i];
+            i++;
+        }
+    }
+    if ((parsed.command === "inspect" || parsed.command === "graph") && i < args.length && !args[i].startsWith("-")) {
+        parsed.target = args[i];
+        i++;
+    }
+    if (parsed.command === "verify" && i < args.length && !args[i].startsWith("-")) {
+        parsed.target = args[i];
+        i++;
+    }
+    if (parsed.command === "search" && i < args.length && !args[i].startsWith("-")) {
+        parsed.query = args[i];
+        i++;
+    }
+    for (; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--root" && i + 1 < args.length) {
+            parsed.root = args[++i];
+        }
+        else if (arg === "--strict") {
+            parsed.strict = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            parsed.help = true;
+        }
+        else if (arg === "--version" || arg === "-v") {
+            parsed.version = true;
+        }
+        else if (arg === "--output" && i + 1 < args.length) {
+            parsed.output = args[++i];
+        }
+        else if (arg === "--modules" && i + 1 < args.length) {
+            parsed.modules = (args[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+        }
+        else if (arg === "--module" && i + 1 < args.length) {
+            parsed.module = args[++i];
+        }
+        else if (arg === "--lang" && i + 1 < args.length) {
+            const lang = args[++i] ?? "";
+            if (LANGUAGES.has(lang)) {
+                parsed.language = lang;
+            }
+            else {
+                parsed.unknown.push(arg);
+            }
+        }
+        else if (arg === "--format" && i + 1 < args.length) {
+            const fmt = args[++i];
+            if (fmt === "ascii" || fmt === "mermaid") {
+                parsed.format = fmt;
+            }
+            else {
+                parsed.unknown.push(arg);
+            }
+        }
+        else if (arg === "--compact") {
+            parsed.compact = true;
+        }
+        else if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--minimal") {
+            parsed.minimal = true;
+        }
+        else if (arg === "--prompts") {
+            parsed.prompts = true;
+        }
+        else if (arg === "--adapter" && i + 1 < args.length) {
+            parsed.provider = args[++i];
+        }
+        else if (arg === "--name" && i + 1 < args.length) {
+            parsed.target = args[++i];
+        }
+        else if (arg.startsWith("-") && !KNOWN_FLAGS.has(arg)) {
+            parsed.unknown.push(arg);
+        }
+    }
+    return parsed;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@friehub/blueprint",
+  "version": "0.1.0",
+  "description": "A domain contract catalogue for backend development. 108 interfaces, 83 adapters, AI-ready.",
+  "keywords": ["contract", "domain", "backend", "ai", "code-generation", "adapter", "blueprint"],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli.js"
+  },
+  "bin": {
+    "blueprint": "./dist/cli.js"
+  },
+  "bin": {
+    "blueprinter": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/core/*.test.js dist/core/adapters/*.test.js",
+    "test:mcp": "node --test dist/mcp/*.test.js",
+    "test:integration": "npm run build && bash scripts/integration-test.sh",
+    "postinstall": "npm run build",
+    "link": "npm run build && npm link"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/handlebars": "^4.0.40",
+    "handlebars": "^4.7.9",
+    "yaml": "^2.9.0"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}