@doquflow/server 0.1.0

package/dist/extractor.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extract = extract;
+function uniq(arr) {
+    return Array.from(new Set(arr.filter((s) => s && s.length > 0)));
+}
+function collect(re, content, group = 1) {
+    const out = [];
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        if (m[group])
+            out.push(m[group]);
+    }
+    return out;
+}
+const RE_CLASS = /(?:abstract\s+|sealed\s+|partial\s+|public\s+|private\s+|protected\s+|internal\s+|static\s+)*(?:class|interface|struct|enum|record)\s+([A-Z]\w*)/g;
+const RE_FUNC_KW = /(?:public|private|protected|internal|static|async|override|function|def|fn|sub)\s+(?:[\w<>\[\],?\s]+?\s+)?([A-Za-z_]\w*)\s*\(/g;
+const RE_FUNC_ARROW = /\b([A-Za-z_]\w*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>/g;
+const RE_METHOD_TS = /^\s*(?:public|private|protected|static|async|readonly|\s)*([a-z_]\w*)\s*\([^)]*\)\s*[:{]/gm;
+const RE_USING = /\busing\s+([\w.]+)\s*;/g;
+const RE_IMPORT_FROM = /\bimport\s+(?:[\w*${}\s,]+\s+from\s+)?['"]([^'"]+)['"]/g;
+const RE_REQUIRE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_DECORATOR = /@(Injectable|Component|Inject|Service|Module|Directive|Pipe|NgModule|Controller)\b/g;
+const RE_NEW_CLASS = /\bnew\s+([A-Z]\w*)\s*\(/g;
+// Standard SQL FROM/JOIN/INTO/UPDATE/DELETE patterns.
+const RE_SQL_TABLE = /(?:\bFROM|\bJOIN|\bINTO|\bUPDATE|\bDELETE\s+FROM|\bTABLE)\s+([A-Za-z_][\w.]*)/gi;
+// EF / ORM DbSet<T> declaration.
+const RE_DBSET = /\bDbSet<\s*([A-Z]\w*)\s*>/g;
+// Attribute-based table mapping: [Table("name")] and .Table("name")
+const RE_TABLE_ATTR = /\[Table\(\s*["']([^"']+)["']/g;
+const RE_TABLE_FLUENT = /\.Table\(\s*["']([^"']+)["']\s*\)/g;
+// EF DbContext property access: _db.Orders., context.Users., _repository.Items. etc.
+// Catches patterns like `_db.Orders.ToListAsync()`, `_context.Users.Find(id)`.
+const RE_EF_PROP = /\b(?:_?db|_?context|_?ctx|_?repository|_?repo)\s*\.\s*([A-Z]\w+)(?=[\s.(])/g;
+const RE_DOTNET_ROUTE = /\[(?:Route|Http(?:Get|Post|Put|Delete|Patch))\(\s*["']([^"']*)["']/g;
+const RE_MIN_API = /\bapp\.Map(?:Get|Post|Put|Delete|Patch)\s*\(\s*["']([^"']+)["']/g;
+const RE_EXPRESS = /\b(?:router|app)\.(?:get|post|put|delete|patch|use)\s*\(\s*['"]([^'"]+)['"]/g;
+const RE_NEST = /@(?:Get|Post|Put|Delete|Patch)\s*\(\s*['"]([^'"]+)['"]/g;
+const RE_NG_PATH = /\bpath\s*:\s*['"]([^'"]+)['"]/g;
+const RE_CFG_CONNSTR = /\bConnectionStrings:([\w.]+)/g;
+const RE_PROCESS_ENV = /\bprocess\.env\.([A-Z_][A-Z0-9_]*)/g;
+const RE_DOTNET_ENV = /\bEnvironment\.GetEnvironmentVariable\(\s*["']([^"']+)["']/g;
+const RE_ICONFIG = /\bIConfiguration\b/g;
+const RE_APPSETTINGS = /\bappsettings(?:\.[A-Za-z0-9]+)?\.json\b/g;
+// SQL keywords and noise that the regex may pick up as table names.
+// Also strips single-letter hits (LINQ aliases: `from u in _db.Users` → u).
+const SQL_KEYWORD_NOISE = new Set([
+    "select", "where", "set", "on", "as", "by", "in", "is", "not", "null",
+    "and", "or", "top", "all", "any", "exists", "between", "like", "case",
+    "when", "then", "else", "end", "with", "having", "group", "order",
+    "asc", "desc", "distinct", "outer", "inner", "left", "right", "full",
+    "cross", "natural", "values", "default", "primary", "key", "index",
+]);
+// EF DbContext property names that are framework plumbing, not tables.
+const EF_NOISE = new Set([
+    "SaveChanges", "SaveChangesAsync", "Entry", "Add", "AddRange", "Remove",
+    "RemoveRange", "Update", "UpdateRange", "Attach", "Find", "FindAsync",
+    "FromSqlRaw", "FromSqlInterpolated", "Database", "Model", "ChangeTracker",
+    "Configuration", "ToList", "ToListAsync", "FirstOrDefault", "FirstOrDefaultAsync",
+    "Where", "Any", "Count", "Include", "ThenInclude", "OrderBy", "GroupBy", "Select",
+]);
+function cleanTableNames(names) {
+    return names.filter((n) => {
+        if (n.length < 2)
+            return false;
+        if (SQL_KEYWORD_NOISE.has(n.toLowerCase()))
+            return false;
+        if (EF_NOISE.has(n))
+            return false;
+        return true;
+    });
+}
+function extract(content) {
+    const classes = collect(new RegExp(RE_CLASS.source, "g"), content);
+    const functions = uniq([
+        ...collect(new RegExp(RE_FUNC_KW.source, "g"), content),
+        ...collect(new RegExp(RE_FUNC_ARROW.source, "g"), content),
+        ...collect(new RegExp(RE_METHOD_TS.source, "gm"), content),
+    ]).filter((n) => !["if", "for", "while", "switch", "catch", "return", "function"].includes(n));
+    const dependencies = uniq([
+        ...collect(new RegExp(RE_USING.source, "g"), content),
+        ...collect(new RegExp(RE_IMPORT_FROM.source, "g"), content),
+        ...collect(new RegExp(RE_REQUIRE.source, "g"), content),
+        ...collect(new RegExp(RE_DECORATOR.source, "g"), content),
+        ...collect(new RegExp(RE_NEW_CLASS.source, "g"), content),
+    ]);
+    const db_tables = uniq(cleanTableNames([
+        ...collect(new RegExp(RE_SQL_TABLE.source, "gi"), content),
+        ...collect(new RegExp(RE_DBSET.source, "g"), content),
+        ...collect(new RegExp(RE_TABLE_ATTR.source, "g"), content),
+        ...collect(new RegExp(RE_TABLE_FLUENT.source, "g"), content),
+        ...collect(new RegExp(RE_EF_PROP.source, "g"), content),
+    ]));
+    const endpoints = uniq([
+        ...collect(new RegExp(RE_DOTNET_ROUTE.source, "g"), content),
+        ...collect(new RegExp(RE_MIN_API.source, "g"), content),
+        ...collect(new RegExp(RE_EXPRESS.source, "g"), content),
+        ...collect(new RegExp(RE_NEST.source, "g"), content),
+        ...collect(new RegExp(RE_NG_PATH.source, "g"), content),
+    ]);
+    const config_refs = [];
+    config_refs.push(...collect(new RegExp(RE_CFG_CONNSTR.source, "g"), content).map((s) => `ConnectionStrings:${s}`));
+    config_refs.push(...collect(new RegExp(RE_PROCESS_ENV.source, "g"), content).map((s) => `process.env.${s}`));
+    config_refs.push(...collect(new RegExp(RE_DOTNET_ENV.source, "g"), content));
+    if (RE_ICONFIG.test(content))
+        config_refs.push("IConfiguration");
+    if (RE_APPSETTINGS.test(content))
+        config_refs.push("appsettings.json");
+    return {
+        classes: uniq(classes),
+        functions: uniq(functions),
+        dependencies,
+        db_tables,
+        endpoints,
+        config_refs: uniq(config_refs),
+    };
+}

package/dist/filesystem.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walk = walk;
+exports.isBinary = isBinary;
+exports.safeReadFile = safeReadFile;
+exports.ensureDir = ensureDir;
+exports.writeFileAtomic = writeFileAtomic;
+exports.readJsonIfExists = readJsonIfExists;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "vendor",
+    ".git",
+    ".svn",
+    ".hg",
+    "dist",
+    "build",
+    "bin",
+    "obj",
+    ".docuflow",
+    ".next",
+    ".nuxt",
+    "out",
+    "target",
+    ".venv",
+    "venv",
+    "__pycache__",
+]);
+const SKIP_FILE_PATTERNS = [
+    /\.min\.js$/i,
+    /\.min\.css$/i,
+    /\.map$/i,
+    /\.lock$/i,
+    /package-lock\.json$/i,
+];
+const MAX_FILE_BYTES = 300 * 1024;
+async function walk(root) {
+    const files = [];
+    const skipped = [];
+    const absRoot = node_path_1.default.resolve(root);
+    async function recurse(dir) {
+        let entries;
+        try {
+            entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+        }
+        catch (e) {
+            skipped.push({ path: dir, reason: `readdir failed: ${e.message}` });
+            return;
+        }
+        for (const entry of entries) {
+            const full = node_path_1.default.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                await recurse(full);
+            }
+            else if (entry.isFile()) {
+                if (SKIP_FILE_PATTERNS.some((re) => re.test(entry.name))) {
+                    skipped.push({ path: full, reason: "skipped by pattern" });
+                    continue;
+                }
+                let stat;
+                try {
+                    stat = await promises_1.default.stat(full);
+                }
+                catch (e) {
+                    skipped.push({ path: full, reason: `stat failed: ${e.message}` });
+                    continue;
+                }
+                if (stat.size > MAX_FILE_BYTES) {
+                    skipped.push({ path: full, reason: `file >300KB (${stat.size} bytes)` });
+                    continue;
+                }
+                files.push({ path: full, size: stat.size });
+            }
+        }
+    }
+    try {
+        const stat = await promises_1.default.stat(absRoot);
+        if (!stat.isDirectory()) {
+            skipped.push({ path: absRoot, reason: "not a directory" });
+            return { files, skipped };
+        }
+    }
+    catch (e) {
+        skipped.push({ path: absRoot, reason: `root stat failed: ${e.message}` });
+        return { files, skipped };
+    }
+    await recurse(absRoot);
+    return { files, skipped };
+}
+function isBinary(buf) {
+    const len = Math.min(buf.length, 512);
+    for (let i = 0; i < len; i++) {
+        if (buf[i] === 0)
+            return true;
+    }
+    return false;
+}
+async function safeReadFile(filePath) {
+    try {
+        const buf = await promises_1.default.readFile(filePath);
+        if (isBinary(buf)) {
+            return { size: buf.length, binary: true };
+        }
+        return { content: buf.toString("utf8"), size: buf.length };
+    }
+    catch (e) {
+        return { size: 0, error: e.message };
+    }
+}
+async function ensureDir(dir) {
+    await promises_1.default.mkdir(dir, { recursive: true });
+}
+async function writeFileAtomic(filePath, content) {
+    await ensureDir(node_path_1.default.dirname(filePath));
+    await promises_1.default.writeFile(filePath, content, "utf8");
+    return Buffer.byteLength(content, "utf8");
+}
+async function readJsonIfExists(filePath) {
+    try {
+        const txt = await promises_1.default.readFile(filePath, "utf8");
+        return JSON.parse(txt);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const read_module_1 = require("./tools/read-module");
+const list_modules_1 = require("./tools/list-modules");
+const write_spec_1 = require("./tools/write-spec");
+const read_specs_1 = require("./tools/read-specs");
+const server = new index_js_1.Server({ name: "docuflow", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "read_module",
+            description: "Read a single source file, detect its language, and extract classes, functions, dependencies, DB tables, endpoints, and config references. Returns raw content truncated at 8000 chars.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute or relative path to the source file." },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "list_modules",
+            description: "Walk a project directory and return extracted facts for every non-binary file. Skips node_modules, dist, build, .git, vendor, obj, bin, .docuflow, *.min.js, *.map, *.lock, and files >300KB. Raw content is omitted for bulk results.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Root directory to scan." },
+                    extensions: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional extension filter e.g. [\".cs\",\".ts\"]. If omitted all non-binary files are included.",
+                    },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "write_spec",
+            description: "Write a markdown spec file to <project_path>/.docuflow/specs/<filename>.md and update the index. The agent provides the full markdown content.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project (where .docuflow/ will be created)." },
+                    filename: { type: "string", description: "Name for the spec file, without extension." },
+                    content: { type: "string", description: "Full markdown content to write." },
+                },
+                required: ["project_path", "filename", "content"],
+            },
+        },
+        {
+            name: "read_specs",
+            description: "Read previously written specs from <project_path>/.docuflow/specs/. Optionally filter by module name.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    module_name: {
+                        type: "string",
+                        description: "Optional: name of a specific spec to retrieve (with or without .md).",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        if (name === "read_module") {
+            result = await (0, read_module_1.readModule)(args);
+        }
+        else if (name === "list_modules") {
+            result = await (0, list_modules_1.listModules)(args);
+        }
+        else if (name === "write_spec") {
+            result = await (0, write_spec_1.writeSpec)(args);
+        }
+        else if (name === "read_specs") {
+            result = await (0, read_specs_1.readSpecs)(args);
+        }
+        else {
+            result = { error: `Unknown tool: ${name}` };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: e?.message ?? String(e) }) }] };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    process.stderr.write(`DocuFlow MCP fatal error: ${e?.message ?? e}\n`);
+    process.exit(1);
+});

package/dist/language-map.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extensionToLanguage = extensionToLanguage;
+const node_path_1 = __importDefault(require("node:path"));
+const EXT_MAP = {
+    ".cs": "csharp",
+    ".vb": "vbnet",
+    ".fs": "fsharp",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".php": "php",
+    ".java": "java",
+    ".py": "python",
+    ".rb": "ruby",
+    ".go": "go",
+    ".rs": "rust",
+    ".kt": "kotlin",
+    ".swift": "swift",
+    ".html": "html",
+    ".htm": "html",
+    ".cshtml": "razor",
+    ".razor": "razor",
+    ".vue": "vue",
+    ".css": "css",
+    ".scss": "scss",
+    ".sass": "sass",
+    ".less": "less",
+    ".json": "json",
+    ".xml": "xml",
+    ".yml": "yaml",
+    ".yaml": "yaml",
+    ".sql": "sql",
+    ".sh": "shell",
+    ".bash": "shell",
+    ".ps1": "powershell",
+    ".md": "markdown",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".hpp": "cpp",
+    ".cc": "cpp",
+};
+function extensionToLanguage(filePath) {
+    const base = node_path_1.default.basename(filePath).toLowerCase();
+    // Angular pattern detection — checked first, before generic .ts.
+    if (base.endsWith(".component.ts") || base.endsWith(".service.ts") || base.endsWith(".module.ts") || base.endsWith(".directive.ts") || base.endsWith(".pipe.ts") || base.endsWith(".guard.ts")) {
+        return "angular";
+    }
+    const ext = node_path_1.default.extname(base);
+    return EXT_MAP[ext] ?? "unknown";
+}

package/dist/tools/list-modules.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listModules = listModules;
+const node_path_1 = __importDefault(require("node:path"));
+const filesystem_1 = require("../filesystem");
+const language_map_1 = require("../language-map");
+const extractor_1 = require("../extractor");
+async function listModules(input) {
+    const projectPath = node_path_1.default.resolve(input.path);
+    const exts = input.extensions?.map((e) => (e.startsWith(".") ? e.toLowerCase() : "." + e.toLowerCase()));
+    const { files, skipped } = await (0, filesystem_1.walk)(projectPath);
+    const allSkipped = [...skipped];
+    const modules = [];
+    const langs = new Set();
+    for (const f of files) {
+        if (exts && !exts.includes(node_path_1.default.extname(f.path).toLowerCase())) {
+            allSkipped.push({ path: f.path, reason: "extension filter" });
+            continue;
+        }
+        const read = await (0, filesystem_1.safeReadFile)(f.path);
+        if (read.error) {
+            allSkipped.push({ path: f.path, reason: `read failed: ${read.error}` });
+            continue;
+        }
+        if (read.binary) {
+            allSkipped.push({ path: f.path, reason: "binary" });
+            continue;
+        }
+        const language = (0, language_map_1.extensionToLanguage)(f.path);
+        langs.add(language);
+        const facts = (0, extractor_1.extract)(read.content ?? "");
+        modules.push({
+            path: node_path_1.default.relative(projectPath, f.path) || f.path,
+            language,
+            size_bytes: read.size,
+            ...facts,
+        });
+    }
+    return {
+        scanned_at: new Date().toISOString(),
+        project_path: projectPath,
+        total_files: modules.length,
+        skipped_files: allSkipped,
+        languages_found: Array.from(langs).sort(),
+        modules,
+    };
+}

package/dist/tools/read-module.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readModule = readModule;
+const node_path_1 = __importDefault(require("node:path"));
+const filesystem_1 = require("../filesystem");
+const language_map_1 = require("../language-map");
+const extractor_1 = require("../extractor");
+const MAX_RAW = 8000;
+async function readModule(input) {
+    const filePath = node_path_1.default.resolve(input.path);
+    const language = (0, language_map_1.extensionToLanguage)(filePath);
+    const read = await (0, filesystem_1.safeReadFile)(filePath);
+    if (read.error) {
+        return {
+            path: filePath,
+            language,
+            size_bytes: 0,
+            classes: [],
+            functions: [],
+            dependencies: [],
+            db_tables: [],
+            endpoints: [],
+            config_refs: [],
+            error: read.error,
+        };
+    }
+    if (read.binary) {
+        return {
+            path: filePath,
+            language,
+            size_bytes: read.size,
+            classes: [],
+            functions: [],
+            dependencies: [],
+            db_tables: [],
+            endpoints: [],
+            config_refs: [],
+            error: "binary file skipped",
+        };
+    }
+    const content = read.content ?? "";
+    const facts = (0, extractor_1.extract)(content);
+    return {
+        path: filePath,
+        language,
+        size_bytes: read.size,
+        ...facts,
+        raw_content: content.length > MAX_RAW ? content.slice(0, MAX_RAW) : content,
+    };
+}

package/dist/tools/read-specs.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSpecs = readSpecs;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const filesystem_1 = require("../filesystem");
+async function readSpecs(input) {
+    const projectPath = node_path_1.default.resolve(input.project_path);
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const indexPath = node_path_1.default.join(docuDir, "index.json");
+    const index = await (0, filesystem_1.readJsonIfExists)(indexPath);
+    if (!index || index.specs.length === 0) {
+        return { specs_found: 0, specs: [] };
+    }
+    let entries = index.specs;
+    if (input.module_name) {
+        const needle = input.module_name.replace(/\.md$/i, "").toLowerCase();
+        entries = entries.filter((s) => s.filename.replace(/\.md$/i, "").toLowerCase() === needle);
+    }
+    const specs = [];
+    for (const entry of entries) {
+        const filePath = node_path_1.default.join(docuDir, "specs", entry.filename);
+        try {
+            const content = await promises_1.default.readFile(filePath, "utf8");
+            specs.push({ filename: entry.filename, written_at: entry.written_at, content });
+        }
+        catch {
+            // spec entry exists in index but file missing — skip silently
+        }
+    }
+    return { specs_found: specs.length, specs };
+}

package/dist/tools/write-spec.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSpec = writeSpec;
+const node_path_1 = __importDefault(require("node:path"));
+const filesystem_1 = require("../filesystem");
+const promises_1 = __importDefault(require("node:fs/promises"));
+// Per-project write lock: maps projectPath → promise chain so that concurrent
+// calls to writeSpec on the same project are always serialised. This prevents
+// the read-modify-write on index.json from racing when the agent issues several
+// write_spec calls in parallel (e.g. writing one spec per module at once).
+const indexLocks = new Map();
+function withLock(key, fn) {
+    const prev = indexLocks.get(key) ?? Promise.resolve();
+    const next = prev.then(fn).catch(() => { });
+    indexLocks.set(key, next);
+    return next;
+}
+async function writeSpec(input) {
+    const projectPath = node_path_1.default.resolve(input.project_path);
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const specsDir = node_path_1.default.join(docuDir, "specs");
+    await (0, filesystem_1.ensureDir)(specsDir);
+    const cleanName = input.filename.replace(/\.md$/i, "");
+    const targetFile = node_path_1.default.join(specsDir, `${cleanName}.md`);
+    // Write the markdown file immediately — each spec file is independent so
+    // parallel writes to different filenames are safe without locking.
+    const bytes = await (0, filesystem_1.writeFileAtomic)(targetFile, input.content);
+    // Serialise index updates per project to avoid read-modify-write races.
+    const indexPath = node_path_1.default.join(docuDir, "index.json");
+    let indexUpdated = false;
+    let writeError;
+    await withLock(projectPath, async () => {
+        try {
+            const existing = (await (0, filesystem_1.readJsonIfExists)(indexPath)) ?? { specs: [] };
+            const now = new Date().toISOString();
+            const idx = existing.specs.findIndex((s) => s.filename === `${cleanName}.md`);
+            if (idx >= 0)
+                existing.specs[idx].written_at = now;
+            else
+                existing.specs.push({ filename: `${cleanName}.md`, written_at: now });
+            await promises_1.default.writeFile(indexPath, JSON.stringify(existing, null, 2), "utf8");
+            indexUpdated = true;
+        }
+        catch (e) {
+            writeError = e?.message ?? String(e);
+        }
+    });
+    if (writeError) {
+        return { written_to: targetFile, bytes_written: bytes, index_updated: false, error: writeError };
+    }
+    return { written_to: targetFile, bytes_written: bytes, index_updated: indexUpdated };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@doquflow/server",
+  "version": "0.1.0",
+  "description": "Docuflow MCP server — lets AI agents read codebases and persist living specs",
+  "author": "Docuflow <hello@doquflows.dev>",
+  "license": "MIT",
+  "homepage": "https://github.com/doquflows/docuflow",
+  "repository": { "type": "git", "url": "https://github.com/doquflows/docuflow.git" },
+  "bugs": { "url": "https://github.com/doquflows/docuflow/issues" },
+  "keywords": ["mcp", "ai-agents", "claude-code", "documentation", "codebase", "developer-tools"],
+  "bin": { "docuflow-server": "./dist/index.js" },
+  "files": ["dist/**"],
+  "scripts": { "build": "tsc" },
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.0.4" },
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" }
+}