@aidemd-mcp/server 0.2.0

package/dist/util/classify/index.d.ts

@@ -0,0 +1,17 @@
+import type { AideFile, AideFileType, ValidationWarning } from "../../types/index.js";
+/**
+ * Classify a filename into an AideFileType based on naming conventions:
+ * - `.aide` or `intent.aide` → "intent"
+ * - `research.aide` → "research"
+ * - `todo.aide` → "todo"
+ * - `plan.aide` → "plan"
+ */
+export declare function classifyFile(filename: string): AideFileType;
+/**
+ * Detect anomalies across a set of .aide files:
+ * - .aide + intent.aide in the same folder (naming conflict)
+ * - research.aide without a corresponding intent spec (orphaned research)
+ * - .aide in a folder with no orchestrator index.ts (orphaned spec)
+ * - Orchestrators with 3+ helper imports but no .aide (missing spec)
+ */
+export declare function detectAnomalies(files: AideFile[], root: string): Promise<ValidationWarning[]>;

package/dist/util/classify/index.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, dirname, basename, relative } from "node:path";
+import { SKIP_DIRS } from "../../types/index.js";
+/**
+ * Classify a filename into an AideFileType based on naming conventions:
+ * - `.aide` or `intent.aide` → "intent"
+ * - `research.aide` → "research"
+ * - `todo.aide` → "todo"
+ * - `plan.aide` → "plan"
+ */
+export function classifyFile(filename) {
+    const base = basename(filename);
+    if (base === "research.aide")
+        return "research";
+    if (base === "todo.aide")
+        return "todo";
+    if (base === "plan.aide")
+        return "plan";
+    return "intent";
+}
+/** Check if a file has 2+ relative `./` imports (orchestrator heuristic). */
+async function countRelativeImports(filePath) {
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const matches = content.match(/(?:import|from)\s+["']\.\/[^"']+["']/g);
+        return matches ? matches.length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Check if a directory contains an orchestrator file (index.ts or index.js). */
+async function findOrchestrator(dir) {
+    try {
+        const entries = await readdir(dir);
+        for (const name of entries) {
+            if (name === "index.ts" || name === "index.js")
+                return join(dir, name);
+        }
+    }
+    catch {
+        // skip unreadable dirs
+    }
+    return null;
+}
+/**
+ * Detect anomalies across a set of .aide files:
+ * - .aide + intent.aide in the same folder (naming conflict)
+ * - research.aide without a corresponding intent spec (orphaned research)
+ * - .aide in a folder with no orchestrator index.ts (orphaned spec)
+ * - Orchestrators with 3+ helper imports but no .aide (missing spec)
+ */
+export async function detectAnomalies(files, root) {
+    const warnings = [];
+    // Group files by directory (using absolute path dirname)
+    const byDir = new Map();
+    for (const file of files) {
+        const dir = dirname(file.path);
+        const group = byDir.get(dir) ?? [];
+        group.push(file);
+        byDir.set(dir, group);
+    }
+    // Collect all directories that have .aide files (for missing-spec scan)
+    const dirsWithSpecs = new Set(byDir.keys());
+    for (const [dir, dirFiles] of byDir) {
+        const names = dirFiles.map((f) => basename(f.path));
+        const relDir = dirFiles[0].relativePath.split("/").slice(0, -1).join("/") || ".";
+        // naming-conflict: .aide + intent.aide in same folder
+        if (names.includes(".aide") && names.includes("intent.aide")) {
+            warnings.push({
+                kind: "naming-conflict",
+                path: relDir,
+                message: "Both .aide and intent.aide exist. Remove .aide or rename to intent.aide.",
+            });
+        }
+        // orphaned-research: research.aide without intent spec
+        const hasResearch = names.includes("research.aide");
+        const hasIntent = names.includes(".aide") || names.includes("intent.aide");
+        if (hasResearch && !hasIntent) {
+            warnings.push({
+                kind: "orphaned-research",
+                path: relDir,
+                message: "research.aide exists without a corresponding intent spec.",
+            });
+        }
+        // orphaned-spec: .aide in folder with no orchestrator
+        const orchestrator = await findOrchestrator(dir);
+        if (!orchestrator) {
+            warnings.push({
+                kind: "orphaned-spec",
+                path: relDir,
+                message: "Spec file(s) in folder with no orchestrator (index.ts/index.js).",
+            });
+        }
+    }
+    // missing-spec: find orchestrators with 3+ relative imports but no .aide
+    // Scan directories that DON'T already have specs
+    await scanForMissingSpecs(root, root, dirsWithSpecs, warnings);
+    return warnings;
+}
+/** Walk the project looking for orchestrators without specs. */
+async function scanForMissingSpecs(dir, root, dirsWithSpecs, warnings) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const skipSet = new Set(SKIP_DIRS);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (skipSet.has(entry.name))
+            continue;
+        const subdir = join(dir, entry.name);
+        // Only check dirs that don't already have specs
+        if (!dirsWithSpecs.has(subdir)) {
+            const orchestrator = await findOrchestrator(subdir);
+            if (orchestrator) {
+                const importCount = await countRelativeImports(orchestrator);
+                if (importCount >= 3) {
+                    const relPath = relative(root, subdir).split("\\").join("/");
+                    warnings.push({
+                        kind: "missing-spec",
+                        path: relPath,
+                        message: `Orchestrator has ${importCount} helper imports but no .aide file.`,
+                    });
+                }
+            }
+        }
+        await scanForMissingSpecs(subdir, root, dirsWithSpecs, warnings);
+    }
+}

package/dist/util/parseBody/index.d.ts

@@ -0,0 +1,7 @@
+import type { BodySection } from "../../types/index.js";
+/**
+ * Split a .aide body string into sections by `##` headings.
+ * Content before the first heading is collected as an unnamed section (heading: "").
+ * Each section's summary is the first sentence or a paragraph count.
+ */
+export default function parseBody(body: string): BodySection[];

package/dist/util/parseBody/index.js

@@ -0,0 +1,43 @@
+/** Extract a summary from section content: first sentence, or "N paragraphs" count. */
+function summarize(content) {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return "";
+    const firstSentenceMatch = trimmed.match(/^[^.!?]+[.!?]/);
+    if (firstSentenceMatch)
+        return firstSentenceMatch[0].trim();
+    const paragraphs = trimmed.split(/\n\s*\n/).filter((p) => p.trim().length > 0);
+    if (paragraphs.length === 1)
+        return paragraphs[0].trim().slice(0, 80);
+    return `${paragraphs.length} paragraphs`;
+}
+/**
+ * Split a .aide body string into sections by `##` headings.
+ * Content before the first heading is collected as an unnamed section (heading: "").
+ * Each section's summary is the first sentence or a paragraph count.
+ */
+export default function parseBody(body) {
+    const lines = body.split("\n");
+    const sections = [];
+    let currentHeading = "";
+    let currentLines = [];
+    for (const line of lines) {
+        if (line.startsWith("## ")) {
+            if (currentHeading !== "" || currentLines.some((l) => l.trim())) {
+                const content = currentLines.join("\n").trim();
+                sections.push({ heading: currentHeading, content, summary: summarize(content) });
+            }
+            currentHeading = line.slice(3).trim();
+            currentLines = [];
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    // Flush the final section.
+    if (currentHeading !== "" || currentLines.some((l) => l.trim())) {
+        const content = currentLines.join("\n").trim();
+        sections.push({ heading: currentHeading, content, summary: summarize(content) });
+    }
+    return sections;
+}

package/dist/util/parseFrontmatter/index.d.ts

@@ -0,0 +1,12 @@
+import type { AideFrontmatter } from "../../types/index.js";
+/** Parsed result of a raw .aide file string. */
+export interface ParseFrontmatterResult {
+    frontmatter: AideFrontmatter | null;
+    body: string;
+}
+/**
+ * Parse YAML frontmatter and body from a raw .aide file string.
+ * Returns `{ frontmatter: null, body: raw }` when no `---` block is present.
+ * Missing `outcomes` fields default to empty arrays rather than throwing.
+ */
+export default function parseFrontmatter(raw: string): ParseFrontmatterResult;

package/dist/util/parseFrontmatter/index.js

@@ -0,0 +1,64 @@
+import { parse } from "yaml";
+/** Extract the YAML block between the first pair of `---` delimiters. Returns null when no block is found. */
+function extractYamlBlock(raw) {
+    const trimmed = raw.trimStart();
+    if (!trimmed.startsWith("---"))
+        return null;
+    const afterOpen = trimmed.slice(3);
+    const closeIndex = afterOpen.indexOf("\n---");
+    if (closeIndex === -1)
+        return null;
+    const yaml = afterOpen.slice(0, closeIndex).trim();
+    const rest = afterOpen.slice(closeIndex + 4).replace(/^\n/, "");
+    return { yaml, rest };
+}
+/** Coerce a parsed YAML value into a string array, returning an empty array on failure. */
+function toStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === "string");
+}
+/** Coerce raw parsed YAML into a well-typed AideFrontmatter, tolerating missing fields. */
+function coerceFrontmatter(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const obj = raw;
+    const fm = {};
+    if (typeof obj.scope === "string")
+        fm.scope = obj.scope;
+    if (typeof obj.description === "string")
+        fm.description = obj.description;
+    if (typeof obj.intent === "string")
+        fm.intent = obj.intent;
+    if (obj.status === "aligned" || obj.status === "misaligned")
+        fm.status = obj.status;
+    if (obj.outcomes && typeof obj.outcomes === "object") {
+        const outcomes = obj.outcomes;
+        fm.outcomes = {
+            desired: toStringArray(outcomes.desired),
+            undesired: toStringArray(outcomes.undesired),
+        };
+    }
+    return fm;
+}
+/**
+ * Parse YAML frontmatter and body from a raw .aide file string.
+ * Returns `{ frontmatter: null, body: raw }` when no `---` block is present.
+ * Missing `outcomes` fields default to empty arrays rather than throwing.
+ */
+export default function parseFrontmatter(raw) {
+    const block = extractYamlBlock(raw);
+    if (!block)
+        return { frontmatter: null, body: raw };
+    let parsed;
+    try {
+        parsed = parse(block.yaml);
+    }
+    catch {
+        return { frontmatter: null, body: raw };
+    }
+    return {
+        frontmatter: coerceFrontmatter(parsed),
+        body: block.rest,
+    };
+}

package/dist/util/scan/index.d.ts

@@ -0,0 +1,7 @@
+import type { ScanResult } from "../../types/index.js";
+/**
+ * Recursively walk the filesystem from `root` and collect all .aide files.
+ * Skips node_modules, .git, dist, build, .next, coverage, __pycache__.
+ * Reads the first ~1000 bytes of each file to extract the first meaningful body line as summary.
+ */
+export default function scan(root: string, path?: string, shallow?: boolean): Promise<ScanResult>;

package/dist/util/scan/index.js

@@ -0,0 +1,82 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { classifyFile } from "../../util/classify/index.js";
+import { SKIP_DIRS } from "../../types/index.js";
+/** Extract the first meaningful body line as the summary, truncated to ~80 chars. */
+function extractSummary(content) {
+    const lines = content.split("\n");
+    let bodyStart = 0;
+    // Skip YAML frontmatter if present
+    if (lines[0] && lines[0].trim() === "---") {
+        let closingIdx = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === "---") {
+                closingIdx = i;
+                break;
+            }
+        }
+        bodyStart = closingIdx !== -1 ? closingIdx + 1 : lines.length;
+    }
+    // Find the first non-empty, non-heading line after frontmatter
+    for (let i = bodyStart; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.length <= 80)
+            return line;
+        return line.slice(0, 77) + "...";
+    }
+    return "";
+}
+/** Normalize a Windows or mixed path to POSIX forward slashes. */
+function toPosix(p) {
+    return p.split("\\").join("/");
+}
+/** Recursively walk a directory and collect all .aide files. */
+async function walk(dir, root, files, shallow) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.includes(entry.name))
+                continue;
+            await walk(fullPath, root, files, shallow);
+            continue;
+        }
+        if (!entry.name.endsWith(".aide"))
+            continue;
+        let summary = "";
+        if (!shallow) {
+            try {
+                const buf = await readFile(fullPath, { encoding: "utf-8" });
+                summary = extractSummary(buf.slice(0, 1000));
+            }
+            catch {
+                // skip unreadable files
+            }
+        }
+        files.push({
+            path: fullPath,
+            relativePath: toPosix(relative(root, fullPath)),
+            type: classifyFile(entry.name),
+            summary,
+        });
+    }
+}
+/**
+ * Recursively walk the filesystem from `root` and collect all .aide files.
+ * Skips node_modules, .git, dist, build, .next, coverage, __pycache__.
+ * Reads the first ~1000 bytes of each file to extract the first meaningful body line as summary.
+ */
+export default async function scan(root, path, shallow) {
+    const scanRoot = path ? join(root, path) : root;
+    const files = [];
+    await walk(scanRoot, root, files, !!shallow);
+    return { root, files };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@aidemd-mcp/server",
+	"version": "0.2.0",
+	"description": "MCP server that teaches any agent the AIDE methodology through tool descriptions and progressive disclosure tooling",
+	"type": "module",
+	"bin": {
+		"aidemd-mcp": "dist/index.js",
+		"aide-tree": "dist/cli/index.js",
+		"server": "dist/cli/init/index.js"
+	},
+	"main": "dist/index.js",
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+		"prepublishOnly": "rm -rf dist && npm run build",
+		"dev": "tsc --watch",
+		"test": "vitest run",
+		"aide-tree": "node dist/cli/index.js",
+		"export-pdf": "tsx scripts/export-pdf.ts"
+	},
+	"keywords": [
+		"mcp",
+		"aide",
+		"progressive-disclosure",
+		"ai-agents",
+		"spec-documents"
+	],
+	"author": "TetsuKod.ai",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aidemd-mcp/server.git"
+	},
+	"license": "MIT",
+	"files": [
+		"dist",
+		"README.md",
+		".aide",
+		".claude/commands/aide"
+	],
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.1",
+		"ink": "^7.0.0",
+		"react": "^19.2.5",
+		"yaml": "^2.8.3",
+		"zod": "^3.24.4"
+	},
+	"devDependencies": {
+		"@types/marked": "^6.0.0",
+		"@types/node": "^22.15.2",
+		"@types/react": "^19.2.14",
+		"ink-testing-library": "^4.0.0",
+		"marked": "^18.0.0",
+		"pdf-lib": "^1.17.1",
+		"puppeteer": "^24.40.0",
+		"tsc-alias": "^1.8.16",
+		"tsx": "^4.21.0",
+		"typescript": "^5.8.3",
+		"vitest": "^3.1.2"
+	}
+}